devela::_dep::sdl3::sys

Module events

Help

Available on crate feature dep_sdl3 only.

Expand description

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 occured 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.

Structs§

SDL_AudioDeviceEvent: Audio device event structure (event.adevice.*)
SDL_CameraDeviceEvent: Camera device event structure (event.cdevice.*)
SDL_ClipboardEvent: An event triggered when the clipboard contents have changed (event.clipboard.*)
SDL_CommonEvent: Fields shared by every event
SDL_DisplayEvent: Display state change event data (event.display.*)
SDL_DropEvent: An event used to drop text or request a file open by the system (event.drop.*)
SDL_EventAction: The type of action to request from SDL_PeepEvents().
SDL_EventType: The types of events that can be delivered.
SDL_GamepadAxisEvent: Gamepad axis motion event structure (event.gaxis.*)
SDL_GamepadButtonEvent: Gamepad button event structure (event.gbutton.*)
SDL_GamepadDeviceEvent: Gamepad device event structure (event.gdevice.*)
SDL_GamepadSensorEvent: Gamepad sensor event structure (event.gsensor.*)
SDL_GamepadTouchpadEvent: Gamepad touchpad event structure (event.gtouchpad.*)
SDL_JoyAxisEvent: Joystick axis motion event structure (event.jaxis.*)
SDL_JoyBallEvent: Joystick trackball motion event structure (event.jball.*)
SDL_JoyBatteryEvent: Joystick battery level change event structure (event.jbattery.*)
SDL_JoyButtonEvent: Joystick button event structure (event.jbutton.*)
SDL_JoyDeviceEvent: Joystick device event structure (event.jdevice.*)
SDL_JoyHatEvent: Joystick hat position change event structure (event.jhat.*)
SDL_KeyboardDeviceEvent: Keyboard device event structure (event.kdevice.*)
SDL_KeyboardEvent: Keyboard button event structure (event.key.*)
SDL_MouseButtonEvent: Mouse button event structure (event.button.*)
SDL_MouseDeviceEvent: Mouse device event structure (event.mdevice.*)
SDL_MouseMotionEvent: Mouse motion event structure (event.motion.*)
SDL_MouseWheelEvent: Mouse wheel event structure (event.wheel.*)
SDL_PenAxisEvent: Pressure-sensitive pen pressure / angle event structure (event.paxis.*)
SDL_PenButtonEvent: Pressure-sensitive pen button event structure (event.pbutton.*)
SDL_PenMotionEvent: Pressure-sensitive pen motion event structure (event.pmotion.*)
SDL_PenProximityEvent: Pressure-sensitive pen proximity event structure (event.pmotion.*)
SDL_PenTouchEvent: Pressure-sensitive pen touched event structure (event.ptouch.*)
SDL_QuitEvent: The “quit requested” event
SDL_RenderEvent: Renderer event structure (event.render.*)
SDL_SensorEvent: Sensor event structure (event.sensor.*)
SDL_TextEditingCandidatesEvent: Keyboard IME candidates event structure (event.edit_candidates.*)
SDL_TextEditingEvent: Keyboard text editing event structure (event.edit.*)
SDL_TextInputEvent: Keyboard text input event structure (event.text.*)
SDL_TouchFingerEvent: Touch finger event structure (event.tfinger.*)
SDL_UserEvent: A user-defined event type (event.user.*)
SDL_WindowEvent: Window state change event data (event.window.*)

Constants§

SDL_ADDEVENT: Add events to the back of the queue.
SDL_EVENT_AUDIO_DEVICE_ADDED: A new audio device is available
SDL_EVENT_AUDIO_DEVICE_FORMAT_CHANGED: An audio device’s format has been changed by the system.
SDL_EVENT_AUDIO_DEVICE_REMOVED: An audio device has been removed.
SDL_EVENT_CAMERA_DEVICE_ADDED: A new camera device is available
SDL_EVENT_CAMERA_DEVICE_APPROVED: A camera device has been approved for use by the user.
SDL_EVENT_CAMERA_DEVICE_DENIED: A camera device has been denied for use by the user.
SDL_EVENT_CAMERA_DEVICE_REMOVED: A camera device has been removed.
SDL_EVENT_CLIPBOARD_UPDATE: The clipboard or primary selection changed
SDL_EVENT_DID_ENTER_BACKGROUND: The application did enter the background and may not get CPU for some time. This event must be handled in a callback set with SDL_AddEventWatch(). Called on iOS in applicationDidEnterBackground() Called on Android in onPause()
SDL_EVENT_DID_ENTER_FOREGROUND: The application is now interactive. This event must be handled in a callback set with SDL_AddEventWatch(). Called on iOS in applicationDidBecomeActive() Called on Android in onResume()
SDL_EVENT_DISPLAY_ADDED: Display has been added to the system
SDL_EVENT_DISPLAY_CONTENT_SCALE_CHANGED: Display has changed content scale
SDL_EVENT_DISPLAY_CURRENT_MODE_CHANGED: Display has changed current mode
SDL_EVENT_DISPLAY_DESKTOP_MODE_CHANGED: Display has changed desktop mode
SDL_EVENT_DISPLAY_FIRST
SDL_EVENT_DISPLAY_LAST
SDL_EVENT_DISPLAY_MOVED: Display has changed position
SDL_EVENT_DISPLAY_ORIENTATION: Display orientation has changed to data1
SDL_EVENT_DISPLAY_REMOVED: Display has been removed from the system
SDL_EVENT_DROP_BEGIN: A new set of drops is beginning (NULL filename)
SDL_EVENT_DROP_COMPLETE: Current set of drops is now complete (NULL filename)
SDL_EVENT_DROP_FILE: The system requests a file open
SDL_EVENT_DROP_POSITION: Position while moving over the window
SDL_EVENT_DROP_TEXT: text/plain drag-and-drop event
SDL_EVENT_ENUM_PADDING
SDL_EVENT_FINGER_CANCELED
SDL_EVENT_FINGER_DOWN
SDL_EVENT_FINGER_MOTION
SDL_EVENT_FINGER_UP
SDL_EVENT_FIRST: Unused (do not remove)
SDL_EVENT_GAMEPAD_ADDED: A new gamepad has been inserted into the system
SDL_EVENT_GAMEPAD_AXIS_MOTION: Gamepad axis motion
SDL_EVENT_GAMEPAD_BUTTON_DOWN: Gamepad button pressed
SDL_EVENT_GAMEPAD_BUTTON_UP: Gamepad button released
SDL_EVENT_GAMEPAD_REMAPPED: The gamepad mapping was updated
SDL_EVENT_GAMEPAD_REMOVED: A gamepad has been removed
SDL_EVENT_GAMEPAD_SENSOR_UPDATE: Gamepad sensor was updated
SDL_EVENT_GAMEPAD_STEAM_HANDLE_UPDATED: Gamepad Steam handle has changed
SDL_EVENT_GAMEPAD_TOUCHPAD_DOWN: Gamepad touchpad was touched
SDL_EVENT_GAMEPAD_TOUCHPAD_MOTION: Gamepad touchpad finger was moved
SDL_EVENT_GAMEPAD_TOUCHPAD_UP: Gamepad touchpad finger was lifted
SDL_EVENT_GAMEPAD_UPDATE_COMPLETE: Gamepad update is complete
SDL_EVENT_JOYSTICK_ADDED: A new joystick has been inserted into the system
SDL_EVENT_JOYSTICK_AXIS_MOTION: Joystick axis motion
SDL_EVENT_JOYSTICK_BALL_MOTION: Joystick trackball motion
SDL_EVENT_JOYSTICK_BATTERY_UPDATED: Joystick battery level change
SDL_EVENT_JOYSTICK_BUTTON_DOWN: Joystick button pressed
SDL_EVENT_JOYSTICK_BUTTON_UP: Joystick button released
SDL_EVENT_JOYSTICK_HAT_MOTION: Joystick hat position change
SDL_EVENT_JOYSTICK_REMOVED: An opened joystick has been removed
SDL_EVENT_JOYSTICK_UPDATE_COMPLETE: Joystick update is complete
SDL_EVENT_KEYBOARD_ADDED: A new keyboard has been inserted into the system
SDL_EVENT_KEYBOARD_REMOVED: A keyboard has been removed
SDL_EVENT_KEYMAP_CHANGED: Keymap changed due to a system event such as an input language or keyboard layout change.
SDL_EVENT_KEY_DOWN: Key pressed
SDL_EVENT_KEY_UP: Key released
SDL_EVENT_LAST: This last event is only for bounding internal arrays
SDL_EVENT_LOCALE_CHANGED: The user’s locale preferences have changed.
SDL_EVENT_LOW_MEMORY: The application is low on memory, free memory if possible. This event must be handled in a callback set with SDL_AddEventWatch(). Called on iOS in applicationDidReceiveMemoryWarning() Called on Android in onTrimMemory()
SDL_EVENT_MOUSE_ADDED: A new mouse has been inserted into the system
SDL_EVENT_MOUSE_BUTTON_DOWN: Mouse button pressed
SDL_EVENT_MOUSE_BUTTON_UP: Mouse button released
SDL_EVENT_MOUSE_MOTION: Mouse moved
SDL_EVENT_MOUSE_REMOVED: A mouse has been removed
SDL_EVENT_MOUSE_WHEEL: Mouse wheel motion
SDL_EVENT_PEN_AXIS: Pressure-sensitive pen angle/pressure/etc changed
SDL_EVENT_PEN_BUTTON_DOWN: Pressure-sensitive pen button pressed
SDL_EVENT_PEN_BUTTON_UP: Pressure-sensitive pen button released
SDL_EVENT_PEN_DOWN: Pressure-sensitive pen touched drawing surface
SDL_EVENT_PEN_MOTION: Pressure-sensitive pen is moving on the tablet
SDL_EVENT_PEN_PROXIMITY_IN: Pressure-sensitive pen has become available
SDL_EVENT_PEN_PROXIMITY_OUT: Pressure-sensitive pen has become unavailable
SDL_EVENT_PEN_UP: Pressure-sensitive pen stopped touching drawing surface
SDL_EVENT_POLL_SENTINEL: Signals the end of an event poll cycle
SDL_EVENT_PRIVATE0
SDL_EVENT_PRIVATE1
SDL_EVENT_PRIVATE2
SDL_EVENT_PRIVATE3
SDL_EVENT_QUIT: User-requested quit
SDL_EVENT_RENDER_DEVICE_LOST: The device has been lost and can’t be recovered.
SDL_EVENT_RENDER_DEVICE_RESET: The device has been reset and all textures need to be recreated
SDL_EVENT_RENDER_TARGETS_RESET: The render targets have been reset and their contents need to be updated
SDL_EVENT_SENSOR_UPDATE: A sensor was updated
SDL_EVENT_SYSTEM_THEME_CHANGED: The system theme changed
SDL_EVENT_TERMINATING: The application is being terminated by the OS. This event must be handled in a callback set with SDL_AddEventWatch(). Called on iOS in applicationWillTerminate() Called on Android in onDestroy()
SDL_EVENT_TEXT_EDITING: Keyboard text editing (composition)
SDL_EVENT_TEXT_EDITING_CANDIDATES: Keyboard text editing candidates
SDL_EVENT_TEXT_INPUT: Keyboard text input
SDL_EVENT_USER: Events SDL_EVENT_USER through SDL_EVENT_LAST are for your use, and should be allocated with SDL_RegisterEvents()
SDL_EVENT_WILL_ENTER_BACKGROUND: The application is about to enter the background. This event must be handled in a callback set with SDL_AddEventWatch(). Called on iOS in applicationWillResignActive() Called on Android in onPause()
SDL_EVENT_WILL_ENTER_FOREGROUND: The application is about to enter the foreground. This event must be handled in a callback set with SDL_AddEventWatch(). Called on iOS in applicationWillEnterForeground() Called on Android in onResume()
SDL_EVENT_WINDOW_CLOSE_REQUESTED: The window manager requests that the window be closed
SDL_EVENT_WINDOW_DESTROYED: The window with the associated ID is being or has been destroyed. If this message is being handled in an event watcher, the window handle is still valid and can still be used to retrieve any properties associated with the window. Otherwise, the handle has already been destroyed and all resources associated with it are invalid
SDL_EVENT_WINDOW_DISPLAY_CHANGED: Window has been moved to display data1
SDL_EVENT_WINDOW_DISPLAY_SCALE_CHANGED: Window display scale has been changed
SDL_EVENT_WINDOW_ENTER_FULLSCREEN: The window has entered fullscreen mode
SDL_EVENT_WINDOW_EXPOSED: Window has been exposed and should be redrawn, and can be redrawn directly from event watchers for this event
SDL_EVENT_WINDOW_FIRST
SDL_EVENT_WINDOW_FOCUS_GAINED: Window has gained keyboard focus
SDL_EVENT_WINDOW_FOCUS_LOST: Window has lost keyboard focus
SDL_EVENT_WINDOW_HDR_STATE_CHANGED: Window HDR properties have changed
SDL_EVENT_WINDOW_HIDDEN: Window has been hidden
SDL_EVENT_WINDOW_HIT_TEST: Window had a hit test that wasn’t SDL_HITTEST_NORMAL
SDL_EVENT_WINDOW_ICCPROF_CHANGED: The ICC profile of the window’s display has changed
SDL_EVENT_WINDOW_LAST
SDL_EVENT_WINDOW_LEAVE_FULLSCREEN: The window has left fullscreen mode
SDL_EVENT_WINDOW_MAXIMIZED: Window has been maximized
SDL_EVENT_WINDOW_METAL_VIEW_RESIZED: The pixel size of a Metal view associated with the window has changed
SDL_EVENT_WINDOW_MINIMIZED: Window has been minimized
SDL_EVENT_WINDOW_MOUSE_ENTER: Window has gained mouse focus
SDL_EVENT_WINDOW_MOUSE_LEAVE: Window has lost mouse focus
SDL_EVENT_WINDOW_MOVED: Window has been moved to data1, data2
SDL_EVENT_WINDOW_OCCLUDED: The window has been occluded
SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED: The pixel size of the window has changed to data1xdata2
SDL_EVENT_WINDOW_RESIZED: Window has been resized to data1xdata2
SDL_EVENT_WINDOW_RESTORED: Window has been restored to normal size and position
SDL_EVENT_WINDOW_SAFE_AREA_CHANGED: The window safe area has been changed
SDL_EVENT_WINDOW_SHOWN: Window has been shown
SDL_GETEVENT: Retrieve/remove events from the front of the queue.
SDL_PEEKEVENT: Check but don’t remove events from the queue front.

Functions§

SDL_AddEventWatch^⚠: Add a callback to be triggered when an event is added to the event queue.
SDL_EventEnabled^⚠: Query the state of processing events by type.
SDL_FilterEvents^⚠: Run a specific filter function on the current event queue, removing any events for which the filter returns false.
SDL_FlushEvent^⚠: Clear events of a specific type from the event queue.
SDL_FlushEvents^⚠: Clear events of a range of types from the event queue.
SDL_GetEventFilter^⚠: Query the current event filter.
SDL_GetWindowFromEvent^⚠: Get window associated with an event.
SDL_HasEvent^⚠: Check for the existence of a certain event type in the event queue.
SDL_HasEvents^⚠: Check for the existence of certain event types in the event queue.
SDL_PeepEvents^⚠: Check the event queue for messages and optionally return them.
SDL_PollEvent^⚠: Poll for currently pending events.
SDL_PumpEvents^⚠: Pump the event loop, gathering events from the input devices.
SDL_PushEvent^⚠: Add an event to the event queue.
SDL_RegisterEvents^⚠: Allocate a set of user-defined events, and return the beginning event number for that set of events.
SDL_RemoveEventWatch^⚠: Remove an event watch callback added with SDL_AddEventWatch().
SDL_SetEventEnabled^⚠: Set the state of processing events by type.
SDL_SetEventFilter^⚠: Set up a filter to process all events before they are added to the internal event queue.
SDL_WaitEvent^⚠: Wait indefinitely for the next available event.
SDL_WaitEventTimeout^⚠: Wait until the specified timeout (in milliseconds) for the next available event.

Type Aliases§

SDL_EventFilter: A function pointer used for callbacks that watch the event queue.

Unions§

SDL_Event: The structure for all events in SDL.