|
Events
ALLEGRO_EVENT
An ALLEGRO_EVENT is a union of all builtin event structures, i.e. it is an object large enough to hold the data of any event type. All events have the following fields in common:
By examining the type field you can then access type-specific fields. The any.source field tells you which event source generated that particular event. The any.timestamp field tells you when the event was generated. The time is referenced to the same starting point as al_current_time(). Each event is of one of the following types:
See also: ALLEGRO_EVENT_SOURCE, ALLEGRO_EVENT_TYPE, ALLEGRO_USER_EVENT ALLEGRO_USER_EVENT
An event structure that can be emitted by user event sources. These are the public fields:
See also: al_emit_user_event ALLEGRO_EVENT_QUEUE
An event queue holds events that have been generated by event sources that are registered with the queue. Events are stored in the order they are generated. Access is in a strictly FIFO (first-in-first-out) order. See also: al_create_event_queue, al_destroy_event_queue ALLEGRO_EVENT_SOURCE
An event source is any object which can generate events. For example, an ALLEGRO_DISPLAY can generate events, and you can get the ALLEGRO_EVENT_SOURCE pointer from an ALLEGRO_DISPLAY with al_get_display_event_source. You may create your own "user" event sources that emit custom events. See also: ALLEGRO_EVENT, al_init_user_event_source, al_emit_user_event ALLEGRO_EVENT_TYPE
An integer used to distinguish between different types of events. See also: ALLEGRO_EVENT, ALLEGRO_GET_EVENT_TYPE, ALLEGRO_EVENT_TYPE_IS_USER ALLEGRO_GET_EVENT_TYPE
Make an event type identifier, which is a 32-bit integer. Usually this will be made from four 8-bit character codes, for example:
You should try to make your IDs unique so they don't clash with any 3rd party code you may be using. IDs less than 1024 are reserved for Allegro or its addons. See also: ALLEGRO_EVENT, ALLEGRO_EVENT_TYPE_IS_USER ALLEGRO_EVENT_TYPE_IS_USER
A macro which evaluates to true if the event type is not a builtin event type, i.e. one of those described in ALLEGRO_EVENT_TYPE. al_create_event_queue
Create a new, empty event queue, returning a pointer to object if successful. Returns NULL on error. See also: ALLEGRO_EVENT_QUEUE al_init_user_event_source
Initialise an event source for emitting user events. The space for the event source must already have been allocated. One possible way of creating custom event sources is to derive other structures with ALLEGRO_EVENT_SOURCE at the head, e.g.
The advantage here is that the THING pointer will be the same as the ALLEGRO_EVENT_SOURCE pointer. Events emitted by the event source will have the event source pointer as the However, it is only one technique and you are not obliged to use it. See also: ALLEGRO_EVENT_SOURCE, al_emit_user_event, al_destroy_user_event_source al_destroy_event_queue
Destroy the event queue specified. All event sources currently registered with the queue will be automatically unregistered before the queue is destroyed. See also: ALLEGRO_EVENT_QUEUE al_destroy_user_event_source
Destroy an event source initialised with al_init_user_event_source. See also: ALLEGRO_EVENT_SOURCE al_drop_next_event
Drop the next event from the queue. If the queue is empty, nothing happens. Returns true iff an event was dropped. al_emit_user_event
Emit a user event. The event source must have been initialised with al_init_user_event_source. Some fields of the event being passed in may be modified. Returns Reference counting will be performed on the event if You need to call al_unref_user_event when you are done with a reference counted user event that you have gotten from al_get_next_event, al_peek_next_event, al_wait_for_event, etc. You may, but do not need to, call al_unref_user_event on non-reference counted user events. See also: ALLEGRO_USER_EVENT al_event_queue_is_empty
Return true if the event queue specified is currently empty. al_flush_event_queue
Drops all events, if any, from the queue. al_get_event_source_data
Returns the abstract user data associated with the event source. If no data was previously set, returns NULL. See also: al_set_event_source_data al_get_next_event
Take the next event out of the event queue specified, and copy the contents into See also: ALLEGRO_EVENT al_peek_next_event
Copy the contents of the next event in the event queue specified into See also: ALLEGRO_EVENT al_register_event_source
Register the event source with the event queue specified. An event source may be registered with any number of event queues simultaneously, or none. Trying to register an event source with the same event queue more than once does nothing. See also: ALLEGRO_EVENT_QUEUE, ALLEGRO_EVENT_SOURCE al_set_event_source_data
Assign the abstract user data to the event source. Allegro does not use the data internally for anything; it is simply meant as a convenient way to associate your own data or objects with events. See also: al_get_event_source_data al_unref_user_event
Unreference a user-defined event. This must be called on any user event that you get from al_get_next_event, al_peek_next_event, al_wait_for_event, etc. which is reference counted. This function does nothing if the event is not reference counted. See also: al_emit_user_event. al_unregister_event_source
Unregister an event source with an event queue. If the event source is not actually registered with the event queue, nothing happens. If the queue had any events in it which originated from the event source, they will no longer be in the queue after this call. al_wait_for_event
Wait until the event queue specified is non-empty. If See also: ALLEGRO_EVENT, al_wait_for_event_timed, al_wait_for_event_until al_wait_for_event_timed
Wait until the event queue specified is non-empty. If
See also: ALLEGRO_EVENT, al_wait_for_event, al_wait_for_event_until al_wait_for_event_until
Wait until the event queue specified is non-empty. If
See also: ALLEGRO_EVENT, ALLEGRO_TIMEOUT, al_init_timeout, al_wait_for_event, al_wait_for_event_timed |
Last updated: 2009-11-29 01:40:57 UTC