###### (This is the documentation for SDL3, which is the current stable version. [SDL2](https://wiki.libsdl.org/SDL2/) was the previous version!)
# SDL_AddEventWatch

Add a callback to be triggered when an event is added to the event queue.

## Header File

Defined in [<SDL3/SDL_events.h>](https://github.com/libsdl-org/SDL/blob/main/include/SDL3/SDL_events.h)

## Syntax

```c
bool SDL_AddEventWatch(SDL_EventFilter filter, void *userdata);
```

## Function Parameters

|                                    |              |                                                                               |
| ---------------------------------- | ------------ | ----------------------------------------------------------------------------- |
| [SDL_EventFilter](SDL_EventFilter) | **filter**   | an [SDL_EventFilter](SDL_EventFilter) function to call when an event happens. |
| void *                             | **userdata** | a pointer that is passed to `filter`.                                         |

## Return Value

(bool) Returns true on success or false on failure; call
[SDL_GetError](SDL_GetError)() for more information.

## Remarks

`filter` will be called when an event happens, and its return value is
ignored.

**WARNING**: Be very careful of what you do in the event filter function,
as it may run in a different thread!

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.

Note: the callback is called for events posted by the user through
[SDL_PushEvent](SDL_PushEvent)(), but not for disabled events, nor for
events by a filter callback set with
[SDL_SetEventFilter](SDL_SetEventFilter)(), nor for events posted by the
user through [SDL_PeepEvents](SDL_PeepEvents)().

## Thread Safety

It is safe to call this function from any thread.

## Version

This function is available since SDL 3.1.3.

## See Also

- [SDL_RemoveEventWatch](SDL_RemoveEventWatch)
- [SDL_SetEventFilter](SDL_SetEventFilter)

----
[CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction), [CategoryEvents](CategoryEvents)