# 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](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](SDL_AppEvent)() before the next call to
[SDL_AppIterate](SDL_AppIterate)(); in this scenario, the app does not call
[SDL_PollEvent](SDL_PollEvent)() at all).

There is other forms of control, too: [SDL_PeepEvents](SDL_PeepEvents)()
has more functionality at the cost of more complexity, and
[SDL_WaitEvent](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](SDL_AddEventWatch)() to set a callback when new events
arrive.

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

<!-- END CATEGORY DOCUMENTATION -->

## Functions

<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: CategoryEvents, CategoryAPIFunction -->
- [SDL_AddEventWatch](SDL_AddEventWatch)
- [SDL_EventEnabled](SDL_EventEnabled)
- [SDL_FilterEvents](SDL_FilterEvents)
- [SDL_FlushEvent](SDL_FlushEvent)
- [SDL_FlushEvents](SDL_FlushEvents)
- [SDL_GetEventDescription](SDL_GetEventDescription)
- [SDL_GetEventFilter](SDL_GetEventFilter)
- [SDL_GetWindowFromEvent](SDL_GetWindowFromEvent)
- [SDL_HasEvent](SDL_HasEvent)
- [SDL_HasEvents](SDL_HasEvents)
- [SDL_PeepEvents](SDL_PeepEvents)
- [SDL_PollEvent](SDL_PollEvent)
- [SDL_PumpEvents](SDL_PumpEvents)
- [SDL_PushEvent](SDL_PushEvent)
- [SDL_RegisterEvents](SDL_RegisterEvents)
- [SDL_RemoveEventWatch](SDL_RemoveEventWatch)
- [SDL_SetEventEnabled](SDL_SetEventEnabled)
- [SDL_SetEventFilter](SDL_SetEventFilter)
- [SDL_WaitEvent](SDL_WaitEvent)
- [SDL_WaitEventTimeout](SDL_WaitEventTimeout)
<!-- END CATEGORY LIST -->

## Datatypes

<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: CategoryEvents, CategoryAPIDatatype -->
- [SDL_EventFilter](SDL_EventFilter)
- [SDL_NotificationID](SDL_NotificationID)
<!-- END CATEGORY LIST -->

## Structs

<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: CategoryEvents, CategoryAPIStruct -->
- [SDL_AudioDeviceEvent](SDL_AudioDeviceEvent)
- [SDL_CameraDeviceEvent](SDL_CameraDeviceEvent)
- [SDL_ClipboardEvent](SDL_ClipboardEvent)
- [SDL_CommonEvent](SDL_CommonEvent)
- [SDL_DisplayEvent](SDL_DisplayEvent)
- [SDL_DropEvent](SDL_DropEvent)
- [SDL_Event](SDL_Event)
- [SDL_GamepadAxisEvent](SDL_GamepadAxisEvent)
- [SDL_GamepadButtonEvent](SDL_GamepadButtonEvent)
- [SDL_GamepadCapSenseEvent](SDL_GamepadCapSenseEvent)
- [SDL_GamepadDeviceEvent](SDL_GamepadDeviceEvent)
- [SDL_GamepadSensorEvent](SDL_GamepadSensorEvent)
- [SDL_GamepadTouchpadEvent](SDL_GamepadTouchpadEvent)
- [SDL_JoyAxisEvent](SDL_JoyAxisEvent)
- [SDL_JoyBallEvent](SDL_JoyBallEvent)
- [SDL_JoyBatteryEvent](SDL_JoyBatteryEvent)
- [SDL_JoyButtonEvent](SDL_JoyButtonEvent)
- [SDL_JoyDeviceEvent](SDL_JoyDeviceEvent)
- [SDL_JoyHatEvent](SDL_JoyHatEvent)
- [SDL_KeyboardDeviceEvent](SDL_KeyboardDeviceEvent)
- [SDL_KeyboardEvent](SDL_KeyboardEvent)
- [SDL_MouseButtonEvent](SDL_MouseButtonEvent)
- [SDL_MouseDeviceEvent](SDL_MouseDeviceEvent)
- [SDL_MouseMotionEvent](SDL_MouseMotionEvent)
- [SDL_MouseWheelEvent](SDL_MouseWheelEvent)
- [SDL_NotificationEvent](SDL_NotificationEvent)
- [SDL_PenAxisEvent](SDL_PenAxisEvent)
- [SDL_PenButtonEvent](SDL_PenButtonEvent)
- [SDL_PenMotionEvent](SDL_PenMotionEvent)
- [SDL_PenProximityEvent](SDL_PenProximityEvent)
- [SDL_PenTouchEvent](SDL_PenTouchEvent)
- [SDL_PinchFingerEvent](SDL_PinchFingerEvent)
- [SDL_QuitEvent](SDL_QuitEvent)
- [SDL_RenderEvent](SDL_RenderEvent)
- [SDL_SensorEvent](SDL_SensorEvent)
- [SDL_TextEditingCandidatesEvent](SDL_TextEditingCandidatesEvent)
- [SDL_TextEditingEvent](SDL_TextEditingEvent)
- [SDL_TextInputEvent](SDL_TextInputEvent)
- [SDL_TouchFingerEvent](SDL_TouchFingerEvent)
- [SDL_UserEvent](SDL_UserEvent)
- [SDL_WindowEvent](SDL_WindowEvent)
<!-- END CATEGORY LIST -->

## Enums

<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: CategoryEvents, CategoryAPIEnum -->
- [SDL_EventAction](SDL_EventAction)
- [SDL_EventType](SDL_EventType)
<!-- END CATEGORY LIST -->

## Macros

<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
<!-- BEGIN CATEGORY LIST: CategoryEvents, CategoryAPIMacro -->
- (none.)
<!-- END CATEGORY LIST -->

----
[CategoryAPICategory](CategoryAPICategory)

