Events

The event processing in CGUI will be started by a call to ProcessEvents stopped by a call to StopProcessEvents. Typically ProcessEvents is called at beginning of your program (after InitCgui and after making it possible for the user to generate some events by e.g. creating a window).
A typical external event is a mouse event. A mouse event may serve as an explanation to what actions are taken when an event occures It works in a similar manner with hot-keys. Sometimes you may want things to happen later on. For that purpose you may explicitly generate an event with some delay (this may be used in animation). The call GenEvent(foo, bar, 0); is equivalent to the call foo(bar); at end of the function that calls GenEvent (provided that the event queue is empty).


void ProcessEvents(void);

Start event processing. This function will not return until StopProcessEvents has been called.
See also: StopProcessEvents.
void StopProcessEvents(void);

Stop event processing. You shall call this function in the call-back function where you want CGUI to stop the event handling, e.g. in the call-back for a button "Exit". In a typical gui-program you don't need to call for StopProcessEvents, if you prefere you can call exit(), instead.
See also: ProcessEvents.
unsigned GenEvent(void (*Handler)(void*), void *data, unsigned delay, int objid);

Generates an event, i.e. adds one messages to the event queue. The effect of calling
   GenEvent(my_function, mydata, 0, 0);
   is
   my_function(mydata);
   
if the event queue happens to be empty. The purpose is to serialize the work to be done (i.e. let some processing be finished before invoking the function in concern), or to ensure that some events that may be in the queue will be processed prior to your function. Another purpose is to achieve that the function will be called after a certain amount of time.
Return value: An event id. Event ids are not the same as the ids of window objects. There can never be two events with the same id, and there can never be two window objects with the same id, but a window object may occasionally have the same id as an event id.
Parameters: Return value: an id that identifies the event, greater than zero, or 0 if it fails (that is: if the event queue has been stopped because of a call to `StopProcessEvents').
See also: ProcessEvents, StopProcessEvents.
int KillEvent(unsigned eventid);

Removes specified event from the event queues. Returns the true if the message was there.
Only events generated by your program can be killed. Events generated bu CGUI itself are protected.
Returns 0 if the event was not found, else non-0.


void FlushGenEvents(void);

Removes all events generated by previous calls to the function GenEvent from the event queue. Events generated bu CGUI itself are protected.
See also: GenEvent.
void InstallKBHandler(int (*Handler)(void *data, int scan, int key), void *data);

Installs a key-board handler. This handler will be called for each key pressed by the user.
For "normal" programming of an application this is not needed. By default the hot-key handler will be installed by InitCgui. When an edit-box will be selected for input by the user it will install a keyboard handler for the edit-box - this one overrides the hot-key handler. I.e. all subsequent key-presses will go to the key-board handler of the edit-box instead of the key-board handler of the hot-keys.
The call-back function "Handler" should return a non-zero value if the key is accepted. A rejected key will be passed to next keyboard-handler on the stack of keyboard handlers.
The pointer "data" will be transparently passed to the handler when invoked, together with scan-code and ascii-code.
See also: InitCgui.
void *UnInstallKBHandler(int (*Handler)(void *, int , int ));

Removes the a keyboard-handler previously installed by InstallKBHandler. Also handlers not on top of the stack may be removed. Return 0 if the specified handler is not present.
See also: InstallKBHandler.
int Invite(int mask, void *data, char *text);

Meetings is a mechanism that makes a kind of "hand-shaking" possible. It will make it possible to simulate "process-like" objects, which may be used in communication protocols.
About meetings: Any of your functions may invite to a meeting, which means that its execution will be held (within "Invite"). The only way for the function to continue is that an event occurs and the callback of that event calls for "Attend" with a matching mask. Until Attend has been called, other events will be properly processed. Invitations are stack-based, which means:
If, while one invitation is open, another call-back "invites" to a new meeting, then that later of the invitations has to be attended (by anyone) before the event system will try to match any attendings to the first of the invitations.
   ________
   | 0x8  | last invite
   --------
   | 0x80 |
   --------
   | 0x2  |  first invite
   --------
   
In the figure above all "attendings" with mask 0x80 and 0x2 will fail until the meeting with mask 0x8 has been finished.
Return value: always 1
Parameters: Return value is 1 (it will always succeed).
See also: Attend.
void *Attend(int mask);

Will attend a meeting invited to by function `Invite' if parameter `mask' matches the meeting. Return value: Attend returns the pointer "data" passed by `Invite' if successful meeting, otherwise NULL.
See also: Invite.

Back to contents