NAME¶
al_emit_user_event - Allegro 5 API
SYNOPSIS¶
-
#include <allegro5/allegro.h>
bool al_emit_user_event(ALLEGRO_EVENT_SOURCE *src,
ALLEGRO_EVENT *event, void (*dtor)(ALLEGRO_USER_EVENT *))
DESCRIPTION¶
Emit a user event. The event source must have been initialised with
al_init_user_event_source(3alleg5). Returns false if the event source isn't
registered with any queues, hence the event wouldn't have been delivered into
any queues.
Events are
copied in and out of event queues, so after this function
returns the memory pointed to by event may be freed or reused. Some fields of
the event being passed in may be modified by the function.
Reference counting will be performed if dtor is not NULL. Whenever a copy of the
event is made, the reference count increases. You need to call
al_unref_user_event(3alleg5) to decrease the reference count once you are done
with a user event that you have received from al_get_next_event(3alleg5),
al_peek_next_event(3alleg5), al_wait_for_event(3alleg5), etc.
Once the reference count drops to zero dtor will be called with a copy of the
event as an argument. It should free the resources associated with the event,
but
not the event itself (since it is just a copy).
If dtor is NULL then reference counting will not be performed. It is safe, but
unnecessary, to call al_unref_user_event(3alleg5) on non-reference counted
user events.
SEE ALSO¶
ALLEGRO_USER_EVENT(3alleg5), al_unref_user_event(3alleg5)