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. IfNone
, will return True on any keypress. Defaults toNone
. - 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 toNone
. - 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: - events (list of
-
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 toNone
. - 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: - events (list of
-
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 toNone
. - 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: - events (list of
-
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 withtext_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