Add new function get_key_state

Author: a-hurst

doc/news.rst

@@ -9,7 +9,8 @@ New Features:
 
 * Updated to wrap new function added in SDL_image 2.8.0 (PR #274).
 * Updated to wrap new hints added in SDL 2.28.2 and 2.28.5 (PR #274).
-
+* Added a new function :func:`~sdl2.ext.get_key_state` for checking if a given
+  key is currently down or up independently of the SDL event queue.
 
 Fixed Bugs:
 

sdl2/ext/input.py

@@ -1,22 +1,24 @@
+from ctypes import c_int, byref
 from ..stdinc import SDL_TRUE
 from ..keyboard import (
     SDL_GetKeyFromName, SDL_GetKeyName, SDL_StartTextInput, SDL_StopTextInput,
-    SDL_IsTextInputActive,
+    SDL_IsTextInputActive, SDL_GetKeyboardState, SDL_GetScancodeFromName,
 )
+from ..scancode import SDL_SCANCODE_UNKNOWN, SDL_NUM_SCANCODES
 from ..keycode import KMOD_ALT, KMOD_CTRL, KMOD_GUI, KMOD_SHIFT
 from ..mouse import (
     SDL_BUTTON_LEFT, SDL_BUTTON_RIGHT, SDL_BUTTON_MIDDLE,
     SDL_BUTTON_X1, SDL_BUTTON_X2,
 )
 from ..events import (
     SDL_KEYDOWN, SDL_KEYUP, SDL_MOUSEBUTTONDOWN, SDL_MOUSEBUTTONUP,
-    SDL_TEXTINPUT,
+    SDL_TEXTINPUT, SDL_PumpEvents,
 )
 
 from .compat import _is_text, byteify, isiterable
 
 __all__ = [
-    "key_pressed", "mouse_clicked", "get_clicks", "get_text_input",
+    "key_pressed", "get_key_state", "mouse_clicked", "get_clicks", "get_text_input",
     "start_text_input", "stop_text_input", "text_input_enabled",  
 ]
 
@@ -197,6 +199,53 @@ def key_pressed(events, key=None, mod=None, released=False):
     return pressed
 
 
+def get_key_state(key):
+    """Checks the current state (pressed or released) of a given keyboard key.
+
+    Unlike :func:`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
+
+    Args:
+        key (int or str): The name (or SDL scancode) of the key to check.
+
+    Returns:
+        int: 1 if the key is currently pressed, otherwise 0.
+
+    """
+    # If key given as string, get the corresponding scancode
+    if _is_text(key):
+        scancode = SDL_GetScancodeFromName(byteify(key))
+        if scancode == SDL_SCANCODE_UNKNOWN:
+            e = "'{0}' is not a valid name for an SDL scancode."
+            raise ValueError(e.format(key))
+    else:
+        if key <= 0 or key >= SDL_NUM_SCANCODES:
+            e = "'{0}' is not a valid SDL scancode constant."
+            raise ValueError(e.format(key))
+        scancode = key
+
+    # Check for and return the current key state
+    SDL_PumpEvents()
+    numkeys = c_int(0)
+    keys = SDL_GetKeyboardState(byref(numkeys))
+    return keys[scancode]
+
+
 def mouse_clicked(events, button=None, released=False):
     """Checks for any mouse clicks in a given event queue.
 

sdl2/test/sdl2ext_input_test.py

@@ -1,5 +1,6 @@
 # -*- coding: utf-8 -*-
 import pytest
+from ..scancode import SDL_SCANCODE_SPACE, SDL_SCANCODE_A
 from ..keycode import SDLK_a, KMOD_LSHIFT, KMOD_RCTRL
 from ..mouse import SDL_BUTTON_LEFT
 from ..events import (
@@ -113,6 +114,21 @@ def test_key_pressed():
         sdl2ext.key_pressed(q, key=-100)
 
 
+def test_get_key_state():
+    # NOTE: Can't fake key status for tests, so just test API
+    assert sdl2ext.get_key_state('space') in (0, 1)
+    assert sdl2ext.get_key_state('a') in (0, 1)
+    assert sdl2ext.get_key_state(SDL_SCANCODE_SPACE) in (0, 1)
+    assert sdl2ext.get_key_state(SDL_SCANCODE_A) in (0, 1)
+    # Test exception on bad key names/scancodes
+    with pytest.raises(ValueError):
+        sdl2ext.get_key_state('nope')
+    with pytest.raises(ValueError):
+        sdl2ext.get_key_state(0)
+    with pytest.raises(ValueError):
+        sdl2ext.get_key_state(1000)
+
+
 def test_mouse_clicked():
     # Test with empty queue
     assert sdl2ext.mouse_clicked([]) == False