al_emit_user_event(3alleg5)

💖 al_emit_user_event 💖

okay bestie, welcome to the Allegro 5 API corner of the manual, where we're talking about al_emit_user_event — the function that lets you yeet your own custom events into the wild. it's giving "main character sends a message to the group chat" energy and honestly? obsessed. 🦋

---

✨ SYNOPSIS ✨

#include <allegro5/allegro.h>

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

---

🌸 DESCRIPTION 🌸

so like, this is the moment. you take an event source and you emit an event from a user event source. slay. but no cap, there's a prerequisite: that event source has to have been initialised first with al_init_user_event_source(3alleg5). can't skip that step, bestie, it's the vibe check. 💅

it returns false if the event source isn't registered with any queues — which lowkey means the event wouldn't have been delivered into any queues at all. so a false here is the universe telling you "nobody was listening, girl." 😭

heads up: events are copied in and out of event queues. so the second this function returns, the memory that event points to may be freed or reused. also, some fields of the event you passed in may get modified by the function itself. so like... don't go clinging to that pointer afterwards, it's not yours anymore. 🙈

now, the reference counting part — this is where it gets ✨iconic✨:

• reference counting will be performed if dtor is not NULL.
• whenever a copy of the event is made, the reference count goes up.
• you need to call al_unref_user_event(3alleg5) to bring the reference count back down once you're done with a user event you received from al_get_next_event(3alleg5), al_peek_next_event(3alleg5), al_wait_for_event(3alleg5), etc. don't forget, or it'll just sit there forever. 💀

once the reference count drops to zero, dtor gets called with a copy of the event as an argument. it should free the resources associated with the event — but not the event itself, because it's just a copy, bestie. not the whole thing. just a copy. 🎀

if dtor is NULL then reference counting will not be performed. and here's a lil fun fact: it's safe, but unnecessary, to call al_unref_user_event(3alleg5) on non-reference counted user events. so like, no harm no foul, but also why would you. 🧚

and finally — plot twist — you can use al_emit_user_event to emit both user and non-user events from your user event source. rainbow of possibilities. 🌈

⚠️ but be careful: 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). the keyboard state does not know. the keyboard state did not receive your memo. do not trust it. 💀

---

👑 SEE ALSO 👑

• ALLEGRO_USER_EVENT(3alleg5)
• al_unref_user_event(3alleg5)

---

and that's the whole page, bestie — you ate. this was the Allegro reference manual talking about al_emit_user_event(3alleg5), and like every good group chat, it's over way too soon. go emit something iconic. periodt. 💜✨🎀