# SDL_SetEventFilter

Set up a filter to process all events before they are added to the internal 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
void SDL_SetEventFilter(SDL_EventFilter filter, void *userdata);
```

## Function Parameters

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

## Remarks

If you just want to see events without modifying them or preventing them
from being queued, you should use [SDL_AddEventWatch](SDL_AddEventWatch)()
instead.

If the filter function returns true when called, then the event will be
added to the internal queue. If it returns false, then the event will be
dropped from the queue, but the internal state will still be updated. This
allows selective filtering of dynamically arriving events.

**WARNING**: Be very careful of what you do in the event filter function,
as it may run in a different thread! The exception is handling of
[SDL_EVENT_WINDOW_EXPOSED](SDL_EVENT_WINDOW_EXPOSED), which is guaranteed
to be sent from the OS on the main thread and you are expected to redraw
your window in response to this event.

On platforms that support it, if the quit event is generated by an
interrupt signal (e.g. pressing Ctrl-C), it will be delivered to the
application at the next event poll.

Note: Disabled events never make it to the event filter function; see
[SDL_SetEventEnabled](SDL_SetEventEnabled)().

Note: Events pushed onto the queue with [SDL_PushEvent](SDL_PushEvent)()
get passed through the event filter, but events pushed onto the queue with
[SDL_PeepEvents](SDL_PeepEvents)() do not.

## Thread Safety

It is safe to call this function from any thread.

## Version

This function is available since SDL 3.2.0.

## Code Examples

```c
#include <SDL3/SDL.h>
#include <SDL3/SDL_main.h>

// Just a quick warning: this is a silly way to do things, but it
//  illustrates how event filters work. In real life, you'd just
//  handle the event when you get it from SDL_PollEvent in the main
//  loop. Generally if you find yourself using an event filter, you
//  should stop and think carefully about whether you have a good
//  reason to be doing so in the first place.


// This is the function we'll pass to SDL_SetEventFilter. If it sees
// that the user has pressed the keyboard's space bar, it toggles
// the value pointed to by `userdata`, to represent the color blue,
// between 255 and 0. The main program uses this value to clear the
// window to a specific color as the space bar is pressed.
static bool SDLCALL my_event_filter(void *userdata, SDL_Event * event)
{
    if ((event->type == SDL_EVENT_KEY_DOWN) && (event->key.key == SDLK_SPACE)) {
        Uint8 *blue = (Uint8 *) userdata;
        if (*blue == 0) {
            *blue = 255;
        } else {
            *blue = 0;
        }
    }
    return true;  // let all events be added to the queue since we always return 1.
}

int main(int argc, char **argv)
{
    Uint8 blue = 0;
    int quit = 0;

    // Just get a window on the screen and clear it to black.
    // In real life, you should check these for errors!
    SDL_Init(SDL_INIT_VIDEO);
    SDL_Window *window = SDL_CreateWindow("Hello SDL", 640, 480, 0);
    SDL_Renderer *renderer = SDL_CreateRenderer(window, NULL);
    SDL_SetRenderDrawColor(renderer, 0, 0, 0, 255);
    SDL_RenderClear(renderer);
    SDL_RenderPresent(renderer);

    // Set up an event filter...
    SDL_SetEventFilter(my_event_filter, &blue);

    // Now run the event loop mostly forever. Each event goes through the
    //  my_event_filter function before it lands here. Each frame, we fill
    //  in the window with whatever color `blue` is set to, which might be
    //  changed by the filter function, as its address is our userdata.
    while (!quit) {
        SDL_Event e;
        while (SDL_PollEvent(&e)) {
            if (e.type == SDL_EVENT_QUIT) {
                quit = 1;
            }
        }

        SDL_SetRenderDrawColor(renderer, 0, 0, blue, 255);
        SDL_RenderClear(renderer);
        SDL_RenderPresent(renderer);
    }

    SDL_Quit();
    return 0;
}
```

## See Also

- [SDL_AddEventWatch](SDL_AddEventWatch)
- [SDL_SetEventEnabled](SDL_SetEventEnabled)
- [SDL_GetEventFilter](SDL_GetEventFilter)
- [SDL_PeepEvents](SDL_PeepEvents)
- [SDL_PushEvent](SDL_PushEvent)

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

