Event supplies a set of high-level function for proper handling of Wimp events.
It polls the Wimp for you, and then passes the resulting event to one or more of your handler routines based on the event which occurred and the window and icon the event occurred in. Events are cascaded down through your handlers (from specific to generic) until one of them returns TRUE, indicating that it has been dealt with succesfully. This allows you to have application-wide defaults for certain event types, with occasional overrides of that default for specific windows or icons.
Any event which has no handlers attached is automatically masked out in subsequent Wimp_Polls (except for quit messages). A set of default (and example) handlers for some events is provided in the Handlers library.
(Note that you should be careful not to leave handlers attached to windows that you delete - potentially a new window might gain the same handle and all the old handlers will become unexpectedly attached to it. The best way to avoid this is to use Window_Delete, which neatly tidies everything up for you.)
This function attaches an event handler to a a particular 'eventtype', 'window' and 'icon'. Any of these can be event_ANY to be non-specific. 'handler' is your handler function, and 'reference' is passed directly to your handler function and can be anything you like.
You can only attach events to a specific icon if you also specify a window.
The more-specific events are called first, so you can have a general routine handling all icon clicks, and then several ones for specific icons which will be called first if those icons are clicked. If two events are of identical priority (ie. you attach the same event to the same window and icon), the one most recently attached will be called first.
Note that Null reason events are not enabled unless you specifically ask for them, whereas all other events will be enabled by you registering a handler for event_ANY.
This releases an event handler. This should be called with same parameters as were passed to Event_Claim to claim it. It will only release one claim each time it is called, so make sure you haven't mistakenly made multiple identical claims.
This function releases all handlers which were attached to a specific window. This should called by you if you delete a window with low-level routines, but it is done for you if you use Window_Delete.
Call this to process a Wimp_Poll event. It will cascade the event down through the event-handler hierarchy until one of your event handlers returns TRUE to indicate succesful handling of the message.
Note that you only need to call this if you have "manually" polled the Wimp using a SWI rather than using Event_Poll or Event_PollIdle, as these functions call it for you.
This is a simple event poll routine to be called by your main poll loop. It simply calls Wimp_Poll and then Event_Process for you.
eg. while (TRUE) Event_Poll();
This is a simple event poll routine to be called by your main poll loop. It simply calls Wimp_PollIdle and then Event_Process for you.
eg. while (TRUE) Event_PollIdle(100);
This would mean that the earliest you would want to receive a Null reason event was 100 centiseconds after this call. Only really useful if you have claimed a Null reason event.
This initialises the Wimp and the Event system for your task, including registering an exit event handler which calls the Wimp_CloseDown SWI.
taskname should be your task name, version should be the Wimp version * 100 required for your program to run. and messages should point to a zero-terminated list of user message numbers you are interested in.
A messages list with just zero means you are interested in all messages, whereas passing NULL means you aren't interested in any messages (except quit, which you will receive anyway).
Note: All the above is true for Wimp versions >= 310 which are the only versions now supported by DeskLib.
This functions calls Event_Initialise3 with default values for a task under a Nested Wimp with no messages.
The nested wimp is available as a softload (in UniBoot) for very old machines, so can be considered a sensible minimum requirement.
Call this to Wimp_CloseDown your application. This calls exit(), so nothing after this in your application will be called (you shouldn't do anything after calling Wimp_CloseDown anyway).
#define Event_Initialise(taskname) \
Event_Initialise3(taskname, 310, NULL)
MACRO: void Event_Initialise(const char *taskname);
This calls Event_Initialise3 for you, with version set to 310 (the earliest version supported by DeskLib), and expressing an interest in *no* messages.
Unless you have a good reason to support very old and non-updated installations, you should call Event_InitNested instead, to unlock some useful WIMP functionality.
Note: in versions of DeskLib up to and including 2.40, this set the wimp version to 200 and got notified of *all* messages.
This type is for functions which can be used to process events claimed using Event_Claim. It should return TRUE if it has processed the event passed to it, or FALSE to let it "fall through" for any other handlers to try and deal with it.
This is the function-type of the Event_Claim and Event_Release functions. It is useful for writing functions which accept a pointer to either of these functions, in order to claim or release a set of events consistently.
Event mask used by the Event FNs for Wimp_Poll and Wimp_PollIdle calls
Wimp task-handle of this application, set by Event_Initialise or equivalent.
This is the Wimp version number * 100, as set up when the Event library is initialised.
Your application name, set by Event_Initialise or equivalent.
This contains the last event received by the Event system.