Event Handling¶

Event handling allows your application to receive input from the user. Event handling is initialized with a call to:

>>> from csdl2 import *
>>> SDL_Init(SDL_INIT_EVENTS)

SDL stores each event as a SDL_Event in an event queue. SDL_Event structures are read from the queue with the SDL_PollEvent function and it is then up to the application to process the information stored with them.

class csdl2.SDL_Event¶

A union that contains structures for the different event types.

type¶

An int specifying the event type. Use the event type’s corresponding attribute to get/set information about the event:

Value of `type`	Attr of `SDL_Event`
`SDL_CONTROLLERAXISMOTION`	`SDL_Event.caxis`
`SDL_CONTROLLERBUTTONDOWN`, `SDL_CONTROLLERBUTTONUP`	`SDL_Event.cbutton`
`SDL_CONTROLLERDEVICEADDED`, `SDL_CONTROLLERDEVICEREMOVED`, `SDL_CONTROLLERDEVICEREMAPPED`	`SDL_Event.cdevice`
`SDL_DOLLARGESTURE`, `SDL_DOLLARRECORD`	`SDL_Event.dgesture`
`SDL_DROPFILE`	`SDL_Event.drop`
`SDL_FINGERMOTION`, `SDL_FINGERDOWN`, `SDL_FINGERUP`	`SDL_Event.tfinger`
`SDL_KEYDOWN`, `SDL_KEYUP`	`SDL_Event.key`
`SDL_JOYAXISMOTION`	`SDL_Event.jaxis`
`SDL_JOYBALLMOTION`	`SDL_Event.jball`
`SDL_JOYHATMOTION`	`SDL_Event.jhat`
`SDL_JOYBUTTONDOWN`, `SDL_JOYBUTTONUP`	`SDL_Event.jbutton`
`SDL_JOYDEVICEADDED`, `SDL_JOYDEVICEREMOVED`	`SDL_Event.jdevice`
`SDL_MOUSEMOTION`	`SDL_Event.motion`
`SDL_MOUSEBUTTONDOWN`, `SDL_MOUSEBUTTONUP`	`SDL_Event.button`
`SDL_MOUSEWHEEL`	`SDL_Event.wheel`
`SDL_MULTIGESTURE`	`SDL_Event.mgesture`
`SDL_QUIT`	`SDL_Event.quit`
`SDL_SYSWMEVENT`	`SDL_Event.syswm`
`SDL_TEXTEDITING`	`SDL_Event.edit`
`SDL_TEXTINPUT`	`SDL_Event.text`
`SDL_USEREVENT`	`SDL_Event.user`
`SDL_WINDOWEVENT`	`SDL_Event.window`

motion¶: (readonly) If SDL_Event.type is SDL_MOUSEMOTION, use this attribute to access the underlying SDL_MouseMotionEvent mouse motion event data.

csdl2.SDL_QUIT¶: User-requested quit.

csdl2.SDL_APP_TERMINATING¶: The application is being terminated by the OS. Called on iOS in applicationWillTerminate(). Called on Android in onDestroy().

csdl2.SDL_APP_LOWMEMORY¶: The application is low on memory, free memory if possible. Called on iOS in applicationDidReceiveMemoryWarning(). Called on Android in onLowMemory().

csdl2.SDL_APP_WILLENTERBACKGROUND¶: The application is about to enter the background. Called on iOS in applicationWillResignActive(). Called on Android in onPause().

csdl2.SDL_APP_DIDENTERBACKGROUND¶: The application did enter the background and may not get CPU for some time. Called on iOS in applicationDidEnterBackground(). Called on Android in onPause().

csdl2.SDL_APP_WILLENTERFOREGROUND¶: The application is about to enter the foreground. Called on iOS in applicationWillEnterForeground(). Called on Android in onResume().

csdl2.SDL_APP_DIDENTERFOREGROUND¶: The application is now interactive. Called on iOS in applicationDidBecomeActive(). Called on Android in onResume().

csdl2.SDL_WINDOWEVENT¶: Window state change.

csdl2.SDL_SYSWMEVENT¶: System specific event.

csdl2.SDL_KEYDOWN¶: Key pressed.

csdl2.SDL_KEYUP¶: Key released.

csdl2.SDL_TEXTEDITING¶: Keyboard text editing (composition).

csdl2.SDL_TEXTINPUT¶: Keyboard text input.

csdl2.SDL_MOUSEMOTION¶: Mouse moved.

csdl2.SDL_MOUSEBUTTONDOWN¶: Mouse button pressed.

csdl2.SDL_MOUSEBUTTONUP¶: Mouse button released.

csdl2.SDL_MOUSEWHEEL¶: Mouse wheel motion.

csdl2.SDL_JOYAXISMOTION¶: Joystick axis motion.

csdl2.SDL_JOYBALLMOTION¶: Joystick trackball motion.

csdl2.SDL_JOYHATMOTION¶: Joystick hat position change.

csdl2.SDL_JOYBUTTONDOWN¶: Joystick button pressed.

csdl2.SDL_JOYBUTTONUP¶: Joystick button released.

csdl2.SDL_JOYDEVICEADDED¶: A new joystick has been inserted into the system.

csdl2.SDL_JOYDEVICEREMOVED¶: An opened joystick has been removed.

csdl2.SDL_CONTROLLERAXISMOTION¶: Game controller axis motion.

csdl2.SDL_CONTROLLERBUTTONDOWN¶: Game controller button pressed.

csdl2.SDL_CONTROLLERBUTTONUP¶: Game controller button released.

csdl2.SDL_CONTROLLERDEVICEADDED¶: A new game controller has been inserted into the system.

csdl2.SDL_CONTROLLERDEVICEREMOVED¶: A opened game controller has been removed.

csdl2.SDL_CONTROLLERDEVICEREMAPPED¶: The controller mapping was updated.

csdl2.SDL_FINGERDOWN¶: User has touched input device.

csdl2.SDL_FINGERUP¶: User stopped touching input device.

csdl2.SDL_FINGERMOTION¶: User is dragging finger on input device.

csdl2.SDL_DOLLARGESTURE¶: User made a dollar gesture.

csdl2.SDL_DOLLARRECORD¶: When recording a gesture with SDL_RecordGesture, the user made a dollar gesture that was recorded.

csdl2.SDL_MULTIGESTURE¶: User made a gesture with multiple fingers.

csdl2.SDL_CLIPBOARDUPDATE¶: The clipboard changed.

csdl2.SDL_DROPFILE¶: The system requests a file open.

csdl2.SDL_USEREVENT¶
csdl2.SDL_LASTEVENT¶: Events SDL_USEREVENT through SDL_LASTEVENT are for your use, and should be allocated with SDL_RegisterEvents

csdl2.SDL_PumpEvents() → None¶

Pumps the event loop, gathering events from the input devices.

This function updates the event queue and internal input device state. Without calling this function, no input events will ever be placed on the queue.

SDL_PollEvent() and SDL_WaitEvent() implicitly call this function. If you are not polling or waiting for events using these functions, you must explicitly call SDL_PumpEvents() to force an event queue update.

This should only be run in the thread that sets the video mode.

csdl2.SDL_PeepEvents(events, numevents: int, action: int, minType: int, maxType: int) → int¶

If action is SDL_ADDEVENT, up to numevents events will be added to the back of the event queue. Returns the number of events added.

If action is SDL_PEEKEVENT, up to numevents events from the front of the event queue, within minType and maxType, will be returned in events, but will not be removed from the queue. Returns number of events peeked.

If action is SDL_GETEVENT, up to numevents events from the front of the event queue, within minType and maxType, will be returned in events, and will be removed from the queue. Returns number of events retrieved.

Parameters:

events (SDL_Event) – Either a SDL_Event object, or a buffer of equivalent size.
numevents (int) – If action is SDL_ADDEVENT, the number of events to add to the event queue. If action is SDL_PEEKEVENT or SDL_GETEVENT, the maximum number of events to retrieve.
action (int) – One of SDL_ADDEVENT, SDL_PEEKEVENT or SDL_GETEVENT.
minType (int) – minimum value of the event type to be considered. SDL_FIRSTEVENT is a safe choice.
maxType (int) – maximum value of the event type to be considered. SDL_LASTEVENT is a safe choice.

Returns:

Number of events added to the event queue for SDL_ADDEVENT, number of events retrieved from the event queue for SDL_PEEKEVENT and SDL_GETEVENT.

csdl2.SDL_ADDEVENT¶
csdl2.SDL_PEEKEVENT¶
csdl2.SDL_GETEVENT¶: Possible actions for SDL_PeepEvents().

csdl2.SDL_FlushEvents(minType: int, maxType: int) → None¶

Removes all events from the event queue within the specified minType and maxType.

To clear all events, set minType to SDL_FIRSTEVENT and maxType to SDL_LASTEVENT. To clear all user events, set minType to SDL_USEREVENT and maxType to SDL_LASTEVENT.

This function only affects currently queued events. If you wish to make sure that all pending OS events are flushed, you can call SDL_PumpEvents() on the main thread immediately before SDL_FlushEvents().

Parameters:	minType (int) – minimum event type to be cleared. maxType (int) – maximum event type to be cleared.

csdl2.SDL_PollEvent(event) → bool¶

Polls for currently pending events.

Parameters:	event (SDL_Event or None) – If not None, the next event is removed from the queue and stored in it. If None, no event will be removed from the queue.
Returns:	True if there are events in the queue, False otherwise.

csdl2.SDL_PushEvent(event) → bool¶

Copies event into the event queue.

Parameters:	event (SDL_Event) – Event to be copied into the event queue. Either a `SDL_Event` instance, or a buffer of equivalent size.
Returns:	True on success, False if the event was filtered.

Note

For pushing application-specific events, please use SDL_RegisterEvents() to get an event type that does not conflict with other code that also wants its own custom event types.

Mouse motion events¶

A SDL_MOUSEMOTION event occurs whenever a user moves the mouse within any window or when SDL_WarpMouseInWindow() is called.

class csdl2.SDL_MouseMotionEvent¶

A structure that contains mouse motion event information.

SDL_MouseMotionEvent is a member of the SDL_Event union and is used when an event of type SDL_MOUSEMOTION is reported. You would access it through the SDL_Event.motion attribute.

type¶: The event type. This should be SDL_MOUSEMOTION.

timestamp¶: Timestamp of the event.

windowID¶: The window with mouse focus, if any.

which¶: The mouse instance ID. This may be SDL_TOUCH_MOUSEID, for events that were generated by a touch input device, and not a real mouse. You might want to ignore such events, if your application already handles the SDL_FINGERMOTION event.

state¶: A 32-bit bitmask of the current button state and is the same as that returned by SDL_GetMouseState(). You can test different buttons by using the masks SDL_BUTTON_LMASK, SDL_BUTTON_MMASK, SDL_BUTTON_RMASK, SDL_BUTTON_X1MASK and SDL_BUTTON_X2MASK.

x¶: X coordinate, relative to window.

y¶: Y coordinate, relative to window.

xrel¶: Motion in the X direction, relative to the last SDL_MOUSEMOTION event. If relative mouse mode is enabled with SDL_SetRelativeMouseMode(), relative movement will still be reported even when the cursor reached the edge of the screen.

yrel¶: Motion in the Y direction, relative to the last SDL_MOUSEMOTION event. If relative mouse mode is enabled with SDL_SetRelativeMouseMode(), relative movement will still be reported even when the cursor reached the edge of the screen.