# date: 2003 - 03 - 04 # This file documents the event queues API which is now considered # finalised for milestone 1. Allegro 5 API: Event queues Status: Finalised for milestone 1 around 2003-01-10. Timeouts changed to longs & milliseconds, 2003-03-04. Pertinent Threads & Brief Change History: Brackets contain attributions for suggestions, complaints or whatnot which inspired the change or something about that change. Apologies if someone is left out. This history is not meant to be exhaustive. * "Event queues" 2002-09-14: - attributions missing, lazy * "Event queues, part 2" 2002-09-23: - attributions missing, lazy * "Keyboard interface" 2002-12-08: - al_wait_for_specific_event (pw, hein) * "Events and inputs, slight overhaul?" 2002-12-19: - lots of functions names shortened - instead of the user receiving pointers to an event, the user passes a pointer to an event structure which is filled in - al_release_event() removed - timeouts now specified by one argument only ---------------------------------------------------------------------- - Type: AL_EVENT_QUEUE This is an abstract data type representing an event queue object. An event queue is an object that collects _event packets_ from _event sources_ which are registered with it. Event packets may be taken out of the event queue and examined. - Function: AL_EVENT_QUEUE *al_create_event_queue(void) Create a new, empty event queue, returning a pointer to object if successful. Returns NULL on error. A system driver must be installed before an event queue can be created. - Function: void al_destroy_event_queue(AL_EVENT_QUEUE *queue) Destroy the event queue specified. All event sources currently registered with the queue will be automatically unregistered before the queue is destroyed. QUEUE may not be NULL. - Function: void al_register_event_source(AL_EVENT_QUEUE *queue, AL_EVENT_SOURCE *source) Register the event source with the event queue specified. From then on, any event packets generated by the event source will be placed at the end of the queue, unless the queue is full. The queue will generally grow up to some arbitrarily large size before it is considered full. An event source may be registered with any number of event queues simultaneously, or none. It is an error to register an event source with an event queue more than once. The implementation may choose to signal this error, or ignore it. Note that you will need to typecast the SOURCE argument. - Function: void al_unregister_event_source(AL_EVENT_QUEUE *queue, AL_EVENT_SOURCE *source) Unregister an event source with an event queue. From then on, any new events generated by the event source will not be put into the queue.[1] It is an error to unregister an event source with an event queue if the source is not actually registered with the queue. The implementation may signal the error, or ignore it. [1]If the queue had any events in it which originated from the event source, they will still be in the queue. - Function: bool al_event_queue_is_empty(AL_EVENT_QUEUE *queue) Return true if the event queue specified is currently empty. - Function: bool al_get_next_event(AL_EVENT_QUEUE *queue, AL_EVENT *ret_event) Take the next event packet out of the event queue specified, and copy the contents into RET_EVENT, returning true. The original event packet will be removed from the queue. If the event queue is empty, return false and the contents of RET_EVENT are unspecified. RET_EVENT may not be NULL. - Function: bool al_peek_next_event(AL_EVENT_QUEUE *queue, AL_EVENT *ret_event) Copy the contents of the next event packet in the event queue specified into RET_EVENT and return true. The original event packet will remain at the head of the queue. If the event queue is actually empty, this function returns false and the contents of RET_EVENT are unspecified. RET_EVENT may not be NULL. - Function: void al_drop_next_event(AL_EVENT_QUEUE *queue) Drop the next event packet from the queue. If the queue is empty, nothing happens. - Function: void al_flush_event_queue(AL_EVENT_QUEUE *queue) Drops all events, if any, from the queue. - Function: bool al_wait_for_event(AL_EVENT_QUEUE *queue, AL_EVENT *ret_event, long timeout_msecs) Wait until the event queue specified is non-empty, then copy the first event packet in the queue into RET_EVENT (the event packet will no longer be in the queue). TIMEOUT_MSECS determines approximately how many milliseconds to wait. If TIMEOUT_MSECS is zero, the call will wait indefinitely. If the call times out, false is returned. Otherwise true is returned. Usage note: It is usually preferable to use this function rather than e.g. al_get_next_event(). Busy waiting, like so: while (!al_get_next_event(queue, &e)) ; will eat up nearly all of the CPU time on the system. On the other hand al_wait_for_event() will, weather permitting, be implemented so as to minimise CPU usage, thereby freeing up the CPU for other applications or users on the same system. - Function: bool al_wait_for_specific_event(AL_EVENT_QUEUE *queue, AL_EVENT *ret_event, long timeout_msecs, AL_EVENT_SOURCE *src_or_null, unsigned long event_mask) Wait until the head of the event queue contains an event packet that satisfies the following criteria, then copy that event packet into RET_EVENT: 1. If SRC_OR_NULL is not NULL, then the event must come from the event source specified. If SRC_OR_NULL is NULL, there is no such restriction. 2. The event must match the bitfield EVENT_MASK. i.e. (the_event's_type & EVENT_MASK) must hold true. All events at the front of the queue which do not satisfy those criteria _will be discarded_. TIMEOUT_MSECS determines how long for the function call to wait. If TIMEOUT_MSECS is zero, the call will wait indefinitely. If the call times out, NULL is returned.