How SDL_PushEvent() Works in SDL2

Think of SDL's event system as having an internal list, called the event queue. As things happen in your application window – the user moves the mouse, presses a key, clicks a button, tries to close the window – SDL detects these occurrences and adds corresponding SDL_Event structures to the back of this queue.

Your main application loop typically uses functions like SDL_PollEvent() to check this queue.

1// Typical event loop in main()
2SDL_Event E;
3while (true) {
4  // Check if events are waiting in the queue
5  while (SDL_PollEvent(&E)) { 
6    // SDL_PollEvent takes an event from the FRONT
7    // of the queue and puts it into 'E'.
8    // If the queue is empty, it returns 0.
9
10    // Handle the event 'E'
11    if (E.type == SDL_QUIT) { /* ... */ }
12    if (E.type == SDL_MOUSEBUTTONDOWN) { /* ... */ }
13    // ... pass E to UIManager.HandleEvent(E) ...
14  }
15  // ... Rendering ...
16}

SDL_PollEvent() looks at the front of the queue. If an event is waiting, it removes that event from the queue, copies its data into the SDL_Event variable you provide (like E), and returns 1 (true). If the queue is empty, it returns 0 (false) and doesn't modify E.

SDL_PushEvent(): Adding to the Queue

The SDL_PushEvent() function allows your code to manually add an SDL_Event structure to this same event queue.

1int SDL_PushEvent(SDL_Event* event);

You create an SDL_Event structure, fill it with the appropriate data for the event type you want to simulate or signal, and then pass a pointer to it to SDL_PushEvent().

1// Button.cpp (Example from lesson)
2#include "Button.h"
3
4void Button::OnLeftClick() {
5  // Create an event structure on the stack
6  SDL_Event QuitEvent{}; 
7
8  // Set its type field
9  QuitEvent.type = SDL_QUIT;
10
11  // Push a *copy* of QuitEvent onto the queue
12  SDL_PushEvent(&QuitEvent);
13}

When you call SDL_PushEvent(), SDL takes a copy of the event data you provided and adds that copy to the back of the internal event queue.

Where Does the Event Go?

The event pushed by SDL_PushEvent() simply joins the end of the line in the main event queue. It sits there waiting its turn alongside events generated directly by user input or window system actions.

When your main loop eventually calls SDL_PollEvent() (or SDL_WaitEvent()), it will process events from the front of the queue in the order they were added. If your pushed event reaches the front of the queue, SDL_PollEvent() will retrieve it just like any other event, and your event handling logic (e.g., the if (E.type == SDL_QUIT) check in main) will react to it.

Why Use SDL_PushEvent()?

1. Inter-Component Communication: As shown in the lesson, a component deep in your UI hierarchy (like a Button) can trigger a high-level application action (like quitting) without needing direct pointers or references all the way back up to main. It just pushes the relevant event, and the main loop handles it naturally.
2. Simulating Events: Useful for testing, tutorials, or game replays where you want to programmatically trigger input events.
3. Asynchronous Operations: If you have work happening on a separate thread that needs to signal the main thread to do something (like update the UI), the worker thread can push an event onto the queue for the main thread's event loop to pick up safely.

Note: SDL also allows you to define and register your own custom event types, providing a more structured way to send application-specific messages via the event queue. We will cover custom events and more advanced event management techniques in detail in a later lesson.