events topic

CategoryEvents

Event queue management.

It's extremely common--often required--that an app deal with SDL's event queue. Almost all useful information about interactions with the real world flow through here: the user interacting with the computer and app, hardware coming and going, the system changing in some way, etc.

An app generally takes a moment, perhaps at the start of a new frame, to examine any events that have occurred since the last time and process or ignore them. This is generally done by calling SDL_PollEvent() in a loop until it returns false (or, if using the main callbacks, events are provided one at a time in calls to SDL_AppEvent() before the next call to SDL_AppIterate(); in this scenario, the app does not call SDL_PollEvent() at all).

There is other forms of control, too: SDL_PeepEvents() has more functionality at the cost of more complexity, and SDL_WaitEvent() can block the process until something interesting happens, which might be beneficial for certain types of programs on low-power hardware. One may also call SDL_AddEventWatch() to set a callback when new events arrive.

The app is free to generate their own events, too: SDL_PushEvent allows the app to put events onto the queue for later retrieval; SDL_RegisterEvents can guarantee that these events have a type that isn't in use by other parts of the system.

Functions

sdlAddEventWatch(Pointer<NativeFunction<SdlEventFilter>> filter, Pointer<NativeType> userdata) → bool events
Add a callback to be triggered when an event is added to the event queue.
sdlEventEnabled(int type) → bool events
Query the state of processing events by type.
sdlFilterEvents(Pointer<NativeFunction<SdlEventFilter>> filter, Pointer<NativeType> userdata) → void events
Run a specific filter function on the current event queue, removing any events for which the filter returns false.
sdlFlushEvent(int type) → void events
Clear events of a specific type from the event queue.
sdlFlushEvents(int minType, int maxType) → void events
Clear events of a range of types from the event queue.
sdlGetEventDescription(Pointer<SdlEvent> event, Pointer<Int8> buf, int buflen) → int events
Generate an English description of an event.
sdlGetEventFilter(Pointer<Pointer<NativeFunction<SdlEventFilter>>> filter, Pointer<Pointer<NativeType>> userdata) → bool events
Query the current event filter.
sdlGetWindowFromEvent(Pointer<SdlEvent> event) → Pointer<SdlWindow> events
Get window associated with an event.
sdlHasEvent(int type) → bool events
Check for the existence of a certain event type in the event queue.
sdlHasEvents(int minType, int maxType) → bool events
Check for the existence of certain event types in the event queue.
sdlPeepEvents(Pointer<SdlEvent> events, int numevents, int action, int minType, int maxType) → int events
Check the event queue for messages and optionally return them.
sdlPollEvent(Pointer<SdlEvent> event) → bool events
Poll for currently pending events.
sdlPumpEvents() → void events
Pump the event loop, gathering events from the input devices.
sdlPushEvent(Pointer<SdlEvent> event) → bool events
Add an event to the event queue.
sdlRegisterEvents(int numevents) → int events
Allocate a set of user-defined events, and return the beginning event number for that set of events.
sdlRemoveEventWatch(Pointer<NativeFunction<SdlEventFilter>> filter, Pointer<NativeType> userdata) → void events
Remove an event watch callback added with SDL_AddEventWatch().
sdlSetEventEnabled(int type, bool enabled) → void events
Set the state of processing events by type.
sdlSetEventFilter(Pointer<NativeFunction<SdlEventFilter>> filter, Pointer<NativeType> userdata) → void events
Set up a filter to process all events before they are added to the internal event queue.
sdlWaitEvent(Pointer<SdlEvent> event) → bool events
Wait indefinitely for the next available event.
sdlWaitEventTimeout(Pointer<SdlEvent> event, int timeoutMs) → bool events
Wait until the specified timeout (in milliseconds) for the next available event.