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
- the user made something with the mouse (moved, pressed button etc)
- the processor recieved an interrupt
- Allegro captures this and calls CGUI's interrupt handler
- CGUI's interrupt handler will put this mouse event into the queue of
messages together with a reference to CGUI's mouse processor
- CGUI's event processor will later on find the message in the queue
and will launch the call-back found in the message, which in this
case happens to be CGUI's mouse processor
- CGUI's mouse processor will pass the message to the window in focus,
which in turn will pass it to its predecessors: the objects in it.
If the mouse-event matches the conditions for the actions of some
object it will perform the action of the object. Typically a click
on a button will lead to the action of invoking the call-back
function that you passed to the `MkButton'.
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).
Start event processing. This function will not return until
StopProcessEvents has been called.
See also:
StopProcessEvents.
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:
- Handler: The call-back function (probably written by you) that you
want to be called.
- data: a pointer to some of your data that `Handler' needs to be
called with.
- delay: a delay time in milliseconds. The delayed queue is
implemented as a separate queue, so what is really done is that
when a timer expires, the messege will be moved from the delayed
queue into the end of the queue of current events. If some
processing is in progress and/or some messages was already there
in the message queue all these prosessing must be finished before
the delayed message will actualy start executing. Most of the time
the queue is empty. The accuracy of time measurment is one unit of
the time resolution provided by Allegro, but as best 1 ms (i.e. a
delay time specified as 5 ms on a DJGPP system will be delayed in
the range of 4 to 5 ms, depending on what delay it happens to be
until next tick). Just pass 0 if you don't want the message to be
delayed.
- objid: An optional (pass 0 if you don't need it) reference to an
window-object. In some cases you may get obscure bugs in your
application if your queued messages refers to data or window-objects
that don't exist any longer. You can avoid such dangling references
by killing the queued event message at proper time (i.e when the
data is about to be destroyed). Often you will find it easier to set
a link from the event to the object that it depends on. It will then
be destroyed, with the object.
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.
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.
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.
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:
- mask: the meeting is identified by this bitmask (mask from invite
and attend will be anded, and a non-zero is regarded as a match)
- text: an identification text (n.u.)
- data: a pointer to any data that may be updated or read by the
"attending" function.
Return value is 1 (it will always succeed).
See also:
Attend.
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