SDL_AddEventWatch(3)

📦
version 3.4.18 · 9 versions
, in fedora 43, fedora 44

💖 SDL_AddEventWatch(3) 💖

okay bestie, welcome to the SDL3 FUNCTIONS corner of the manual, where we're talking about SDL_AddEventWatch — literally the function that lets you be nosy about every event the second it shows up. no cap.

✨ NAME ✨

SDL_AddEventWatch — add a callback to be triggered when an event is added to the event queue. it's giving personal event bodyguard, fr fr.

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_events.h>

bool SDL_AddEventWatch(SDL_EventFilter filter, void *userdata);

look at her. two args, one bool, zero drama. 💅

🦋 DESCRIPTION 🦋

so here's the tea: filter will be called when an event happens, and its return value is ignored. like, it can return whatever it wants, nobody's checking. main character behavior honestly.

⚠️ WARNING: Be very careful of what you do in the event filter function, as it may run in a different thread! 😭 this is not a drill. do not go wild in there.

if the quit event is generated by a signal (e.g. SIGINT), it will bypass the internal queue and be delivered to the watch callback immediately, and arrive at the next event poll. iconic shortcut, honestly.

Note: the callback is called for events posted by the user through SDL_PushEvent(), but not for disabled events, nor for events by a filter callback set with SDL_SetEventFilter(), nor for events posted by the user through SDL_PeepEvents(). so like, know your limits bestie. 🫶

🎀 FUNCTION PARAMETERS 🎀

  • filter — an SDL_EventFilter function to call when an event happens. your lil event-listening bestie.
  • userdata — a pointer that is passed to filter. a little gift basket you hand over so filter has context. 🍓

⭐ RETURN VALUE ⭐

Returns true on success or false on failure; call SDL_GetError() for more information. so if it comes back false, go ask SDL_GetError() what's wrong, she always knows. 💀

🌈 THREAD SAFETY 🌈

It is safe to call this function from any thread. yes, ANY. go off, queen. 👑

💜 AVAILABILITY 💜

This function is available since SDL 3.2.0. vintage-ish but make it fresh. ✨

🔥 SEE ALSO 🔥

iykyk — that's the whole friend group right there. 🌸

and that's the page, bestie!! brought to you by Simple Directmedia Layer, running SDL 3.4.18. mwah, go watch some events. 💖🎀🦋

📦 where this page comes from