# 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)

  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)

  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)

  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.get_text_input(events)

  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

sdl2.ext.input.start_text_input()

  Enables SDL unicode text input events.

sdl2.ext.input.stop_text_input()

  Disables SDL unicode text input events.

sdl2.ext.input.text_input_enabled()

  Checks whether SDL text input events are currently enabled.

  Returns:

    True if text input events are enabled, otherwise False.

  Return type:

    bool