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  an event from a user event source.  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.

       You can use al_emit_user_event to emit both user and non-user events from your user  event
       source.   Note  that  emitting input events will not update the corresponding input device
       states.  For example, you may emit an event of type  ALLEGRO_EVENT_KEY_DOWN(3alleg5),  but
       it     will     not     update    the    ALLEGRO_KEYBOARD_STATE(3alleg5)    returned    by
       al_get_keyboard_state(3alleg5).

SEE ALSO

       ALLEGRO_USER_EVENT(3alleg5), al_unref_user_event(3alleg5)