sdl2.ext.input - Handling SDL2 Input Events¶

This module provides a range of Pythonic functions for handling and processing SDL input events (e.g. key presses, mouse clicks, unicode text input) as retrieved from get_events().

The key_pressed() function allows for easily checking whether a given key has been pressed (or released). Likewise, mouse_clicked() lets you handle mouse button press and release events. If you want to check the locations of mouse clicks, get_clicks() returns the pixel coordinates for all clicks (if any) in a given list of events.

For handling text entry in PySDL2 (including unicode characters), get_text_input() returns all text input in a given list of events as a unicode string. Note that text input events are disabled by default in SDL, but can easily be enabled/disabled using start_text_input() and stop_text_input().

sdl2.ext.input.key_pressed(events, key=None, mod=None, released=False)[source]¶

Checks for key press events in a given event queue.

By default, this function will return True if any key has been pressed. However, you can also check a specific key by providing its name (e.g. ‘up’) or SDL keycode (e.g. sdl2.SDLK_up) to the ‘key’ argument.

This function is meant to be used with get_events():

response = None
while not response:
    q = get_events() # Fetch latest SDL input events
    if key_pressed(q, 'z'):
        response = 'left'
    elif key_pressed(q, '/'):
        response = 'right'

Additionally, you can check if the key has been pressed while holding one or more modifier keys (e.g. control + q to quit the program) by providing the name(s) (e.g. ‘ctrl’) or SDL bitmask(s) (e.g. sdl2.KMOD_LCTRL) of the modifiers to the ‘mod’ argument:

q = get_events()
if key_pressed(q, 'q', mod='ctrl'):
    exit_app()
elif key_pressed(q, 'd', mod=['ctrl', 'shift']):
    debug_mode = True

Valid modifier names include ‘ctrl’ and ‘control’ for the Control keys, ‘alt’ and ‘option’ for the Alt keys, ‘gui’, ‘command’, and ‘super’ for the Command/Win/Super keys, and ‘shift’ for the shift keys. A full list of SDL modifier bitmasks can be found here: https://wiki.libsdl.org/SDL2/SDL_Keymod

For a comprehensive list of valid key names, see the ‘Name’ column of the following table: https://wiki.libsdl.org/SDL2/SDL_Scancode

For a comprehensive list of valid SDL keycodes, consult the following table: https://wiki.libsdl.org/SDL_Keycode

Parameters:	events (list of `sdl2.SDL_Event`) – A list of SDL events to check for matching key presses (or releases). key (str or `sdl2.SDL_Keycode`, optional) – The name or SDL keycode of the key to check. If `None`, will return True on any keypress. Defaults to `None`. mod (str or list, optional) – The key modifiers (if any) to require for the key press (e.g. ‘ctrl’ for Control-Q). Has no effect if `key` is not specified. Defaults to `None`. released (bool, optional) – If True, will check for key release events instead of key presses. Defaults to False.
Returns:	True if key has been pressed, otherwise False.
Return type:	bool

sdl2.ext.input.mouse_clicked(events, button=None, released=False)[source]¶

Checks for any mouse clicks in a given event queue.

This function is meant to be used with get_events():

response = None
while not response:
    q = get_events() # Fetch latest SDL input events
    if mouse_clicked(q, 'left'):
        response = 'left'
    elif mouse_clicked(q, 'right'):
        response = 'right'

By default, this function checks for clicks from any button. However, you can also check for clicks from a specific button by specifying one of the following strings or SDL constants for the button argument:

SDL Constant	String
`SDL_BUTTON_LEFT`	`'left'`
`SDL_BUTTON_RIGHT`	`'right'`
`SDL_BUTTON_MIDDLE`	`'middle'`
`SDL_BUTTON_X1`	`'x1'`
`SDL_BUTTON_X2`	`'x2'`

Parameters:	events (list of `sdl2.SDL_Event`) – A list of SDL events to check for mouse click events. button (str or int, optional) – The name or SDL constant of the mouse button to listen for. If `None`, all mouse buttons will . Defaults to `None`. released (bool, optional) – If True, will check the queue for mouse button release events instead of mouse button down events. Defaults to False.
Returns:	True if the mouse has been clicked, otherwise False.
Return type:	bool

sdl2.ext.input.get_clicks(events, button=None, released=False)[source]¶

Returns the (x, y) coordinates of the mouse clicks in an event queue.

By default, this function returns clicks from any button. However, you can also return clicks from a specific button only by specifying a string or SDL button constant (see mouse_clicked() for details).

Parameters:	events (list of `sdl2.SDL_Event`) – A list of SDL events to check for mouse click events. button (str or int, optional) – The name or SDL constant of the mouse button to listen for. If `None`, will return clicks from any mouse button. Defaults to `None`. released (bool, optional) – If True, will return the coordinates for mouse button release events instead of mouse button click events. Defaults to False.
Returns:	A list of the (x, y) coordinates for each matching click event in the queue.
Return type:	list

sdl2.ext.input.start_text_input()[source]¶: Enables SDL unicode text input events.

sdl2.ext.input.stop_text_input()[source]¶: Disables SDL unicode text input events.

sdl2.ext.input.text_input_enabled()[source]¶

Checks whether SDL text input events are currently enabled.

Returns:	True if text input events are enabled, otherwise False.
Return type:	bool

sdl2.ext.input.get_text_input(events)[source]¶

Returns the text input events from a queue as a unicode string.

Note that SDL text input events need to be enabled for this function to work. This can be toggled with start_text_input() / stop_text_input() and queried with text_input_enabled():

start_text_input()

response = u""
while True:
    q = get_events()
    if key_pressed(q, 'return'):
        break
    response += get_text_input(q)
    draw_text(response)

stop_text_input()

If there are no text input events in the given event queue, an empty unicode string will be returned.

Parameters:	events (list of `sdl2.SDL_Event`) – A list of SDL events to check for unicode text input (`SDL_TEXTINPUT`) events.
Returns:	A UTF8-encoded unicode string containing all text input from the queue.
Return type:	str