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:
bool
- sdl2.ext.input.get_key_state(key)[source]
Checks the current state (pressed or released) of a given keyboard key.
Unlike
key_pressed()
, which checks an SDL event queue for key down and key up events, this function checks the current state of a given key directly. This can be helpful in certain situations, such as ignoring repeated keydown events from a held key:key_released = False while True: q = pump(True) if not key_released: # Ignore repeated keydown events from held down space bar by # requiring key be 'up' on at least one loop before a response # can be registered if get_key_state('space') == 0: key_released = True else: if key_pressed('space', queue=q): break
- Parameters:
key (int or str) – The name (or SDL scancode) of the key to check.
- Returns:
1 if the key is currently pressed, otherwise 0.
- Return type:
int
- 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:
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 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:
list
- 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