noble (3) al_emit_user_event.3alleg5.gz

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)