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)