al_emit_user_event(3)

🎀 al_emit_user_event(3) 🎀

okay so bestie, this page is from the Library Functions Manual and it's serving Allegro 5 API realness. The main character is al_emit_user_event, and she's here to help you emit events from your very own user event source. 💅

---

✨ NAME ✨

• al_emit_user_event — Allegro 5 API. That's the whole name section, short and iconic. 💖

📜 SYNOPSIS 📜

#include <allegro5/allegro.h>

bool al_emit_user_event(ALLEGRO_EVENT_SOURCE *src,
   ALLEGRO_EVENT *event, void (*dtor)(ALLEGRO_USER_EVENT *))

🫶 DESCRIPTION 🫶

okay so here's the tea, bestie: you're emitting an event from a user event source. But first, that event source must have been initialised with al_init_user_event_source(3). No cap.

This function returns false if the event source isn't registered with any queues — which means the event wouldn't have been delivered into any queues. So if you get a false, that's why. 😭

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. Also, some fields of the event being passed in may be modified by the function. So don't clutch that pointer after the call, bestie.

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(3) to decrease the reference count once you are done with a user event that you have received from al_get_next_event(3), al_peek_next_event(3), al_wait_for_event(3), etc. iykyk.

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). This part is lowkey important, so don't fumble it. 🧚

If dtor is NULL, then reference counting will not be performed. It is safe, but unnecessary, to call al_unref_user_event(3) on non-reference counted user events. slay — safe and unnecessary is a whole vibe.

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(3), but it will not update the ALLEGRO_KEYBOARD_STATE(3) returned by al_get_keyboard_state(3). So don't expect the keyboard state to magically catch up — it won't. periodt. 💀

bestie warning: the dtor should free the resources associated with the event, but not the event itself, because it's just a copy. Do not free the copy as if it were the original event. 🙈

🔍 SEE ALSO 🔍

• ALLEGRO_USER_EVENT(3)
• al_unref_user_event(3)

---

and that's the page, bestie. it's from the Allegro reference manual — al_emit_user_event(3) — with that footer energy. no date on the footer, just the manual name and the page title, and honestly? iconic. 🎀✨