1.. include:: common.txt 2 3:mod:`pygame.key` 4================= 5 6.. module:: pygame.key 7 :synopsis: pygame module to work with the keyboard 8 9| :sl:`pygame module to work with the keyboard` 10 11This module contains functions for dealing with the keyboard. 12 13The :mod:`pygame.event` queue gets ``pygame.KEYDOWN`` and ``pygame.KEYUP`` 14events when the keyboard buttons are pressed and released. Both events have 15``key`` and ``mod`` attributes. 16 17 * ``key``: an :ref:`integer ID <key-constants-label>` representing every key 18 on the keyboard 19 * ``mod``: a bitmask of all the :ref:`modifier keys <key-modifiers-label>` 20 that were in a pressed state when the event occurred 21 22The ``pygame.KEYDOWN`` event has the additional attributes ``unicode`` and 23``scancode``. 24 25 * ``unicode``: a single character string that is the fully translated 26 character entered, this takes into account the shift and composition keys 27 * ``scancode``: the platform-specific key code, which could be different from 28 keyboard to keyboard, but is useful for key selection of weird keys like 29 the multimedia keys 30 31.. versionadded:: 2.0.0 32 The ``pygame.TEXTINPUT`` event is preferred to the ``unicode`` attribute 33 of ``pygame.KEYDOWN``. The attribute ``text`` contains the input. 34 35 36.. _key-constants-label: 37 38The following is a list of all the constants (from :mod:`pygame.locals`) used to 39represent keyboard keys. 40 41Portability note: The integers for key constants differ between pygame 1 and 2. 42Always use key constants (``K_a``) rather than integers directly (``97``) so 43that your key handling code works well on both pygame 1 and pygame 2. 44 45 46:: 47 48 pygame 49 Constant ASCII Description 50 --------------------------------- 51 K_BACKSPACE \b backspace 52 K_TAB \t tab 53 K_CLEAR clear 54 K_RETURN \r return 55 K_PAUSE pause 56 K_ESCAPE ^[ escape 57 K_SPACE space 58 K_EXCLAIM ! exclaim 59 K_QUOTEDBL " quotedbl 60 K_HASH # hash 61 K_DOLLAR $ dollar 62 K_AMPERSAND & ampersand 63 K_QUOTE quote 64 K_LEFTPAREN ( left parenthesis 65 K_RIGHTPAREN ) right parenthesis 66 K_ASTERISK * asterisk 67 K_PLUS + plus sign 68 K_COMMA , comma 69 K_MINUS - minus sign 70 K_PERIOD . period 71 K_SLASH / forward slash 72 K_0 0 0 73 K_1 1 1 74 K_2 2 2 75 K_3 3 3 76 K_4 4 4 77 K_5 5 5 78 K_6 6 6 79 K_7 7 7 80 K_8 8 8 81 K_9 9 9 82 K_COLON : colon 83 K_SEMICOLON ; semicolon 84 K_LESS < less-than sign 85 K_EQUALS = equals sign 86 K_GREATER > greater-than sign 87 K_QUESTION ? question mark 88 K_AT @ at 89 K_LEFTBRACKET [ left bracket 90 K_BACKSLASH \ backslash 91 K_RIGHTBRACKET ] right bracket 92 K_CARET ^ caret 93 K_UNDERSCORE _ underscore 94 K_BACKQUOTE ` grave 95 K_a a a 96 K_b b b 97 K_c c c 98 K_d d d 99 K_e e e 100 K_f f f 101 K_g g g 102 K_h h h 103 K_i i i 104 K_j j j 105 K_k k k 106 K_l l l 107 K_m m m 108 K_n n n 109 K_o o o 110 K_p p p 111 K_q q q 112 K_r r r 113 K_s s s 114 K_t t t 115 K_u u u 116 K_v v v 117 K_w w w 118 K_x x x 119 K_y y y 120 K_z z z 121 K_DELETE delete 122 K_KP0 keypad 0 123 K_KP1 keypad 1 124 K_KP2 keypad 2 125 K_KP3 keypad 3 126 K_KP4 keypad 4 127 K_KP5 keypad 5 128 K_KP6 keypad 6 129 K_KP7 keypad 7 130 K_KP8 keypad 8 131 K_KP9 keypad 9 132 K_KP_PERIOD . keypad period 133 K_KP_DIVIDE / keypad divide 134 K_KP_MULTIPLY * keypad multiply 135 K_KP_MINUS - keypad minus 136 K_KP_PLUS + keypad plus 137 K_KP_ENTER \r keypad enter 138 K_KP_EQUALS = keypad equals 139 K_UP up arrow 140 K_DOWN down arrow 141 K_RIGHT right arrow 142 K_LEFT left arrow 143 K_INSERT insert 144 K_HOME home 145 K_END end 146 K_PAGEUP page up 147 K_PAGEDOWN page down 148 K_F1 F1 149 K_F2 F2 150 K_F3 F3 151 K_F4 F4 152 K_F5 F5 153 K_F6 F6 154 K_F7 F7 155 K_F8 F8 156 K_F9 F9 157 K_F10 F10 158 K_F11 F11 159 K_F12 F12 160 K_F13 F13 161 K_F14 F14 162 K_F15 F15 163 K_NUMLOCK numlock 164 K_CAPSLOCK capslock 165 K_SCROLLOCK scrollock 166 K_RSHIFT right shift 167 K_LSHIFT left shift 168 K_RCTRL right control 169 K_LCTRL left control 170 K_RALT right alt 171 K_LALT left alt 172 K_RMETA right meta 173 K_LMETA left meta 174 K_LSUPER left Windows key 175 K_RSUPER right Windows key 176 K_MODE mode shift 177 K_HELP help 178 K_PRINT print screen 179 K_SYSREQ sysrq 180 K_BREAK break 181 K_MENU menu 182 K_POWER power 183 K_EURO Euro 184 K_AC_BACK Android back button 185 186 187.. _key-modifiers-label: 188 189The keyboard also has a list of modifier states (from :mod:`pygame.locals`) that 190can be assembled by bitwise-ORing them together. 191 192:: 193 194 pygame 195 Constant Description 196 ------------------------- 197 KMOD_NONE no modifier keys pressed 198 KMOD_LSHIFT left shift 199 KMOD_RSHIFT right shift 200 KMOD_SHIFT left shift or right shift or both 201 KMOD_LCTRL left control 202 KMOD_RCTRL right control 203 KMOD_CTRL left control or right control or both 204 KMOD_LALT left alt 205 KMOD_RALT right alt 206 KMOD_ALT left alt or right alt or both 207 KMOD_LMETA left meta 208 KMOD_RMETA right meta 209 KMOD_META left meta or right meta or both 210 KMOD_CAPS caps lock 211 KMOD_NUM num lock 212 KMOD_MODE AltGr 213 214 215The modifier information is contained in the ``mod`` attribute of the 216``pygame.KEYDOWN`` and ``pygame.KEYUP`` events. The ``mod`` attribute is a 217bitmask of all the modifier keys that were in a pressed state when the event 218occurred. The modifier information can be decoded using a bitwise AND (except 219for ``KMOD_NONE``, which should be compared using equals ``==``). For example: 220 221:: 222 223 for event in pygame.event.get(): 224 if event.type == pygame.KEYDOWN or event.type == pygame.KEYUP: 225 if event.mod == pygame.KMOD_NONE: 226 print('No modifier keys were in a pressed state when this ' 227 'event occurred.') 228 else: 229 if event.mod & pygame.KMOD_LSHIFT: 230 print('Left shift was in a pressed state when this event ' 231 'occurred.') 232 if event.mod & pygame.KMOD_RSHIFT: 233 print('Right shift was in a pressed state when this event ' 234 'occurred.') 235 if event.mod & pygame.KMOD_SHIFT: 236 print('Left shift or right shift or both were in a ' 237 'pressed state when this event occurred.') 238 239 240 241.. function:: get_focused 242 243 | :sl:`true if the display is receiving keyboard input from the system` 244 | :sg:`get_focused() -> bool` 245 246 Returns ``True`` when the display window has keyboard focus from the 247 system. If the display needs to ensure it does not lose keyboard focus, it 248 can use :func:`pygame.event.set_grab()` to grab all input. 249 250 .. ## pygame.key.get_focused ## 251 252.. function:: get_pressed 253 254 | :sl:`get the state of all keyboard buttons` 255 | :sg:`get_pressed() -> bools` 256 257 Returns a sequence of boolean values representing the state of every key on 258 the keyboard. Use the key constant values to index the array. A ``True`` 259 value means the that button is pressed. 260 261 .. note:: 262 Getting the list of pushed buttons with this function is not the proper 263 way to handle text entry from the user. There is no way to know the order 264 of keys pressed, and rapidly pushed keys can be completely unnoticed 265 between two calls to ``pygame.key.get_pressed()``. There is also no way to 266 translate these pushed keys into a fully translated character value. See 267 the ``pygame.KEYDOWN`` events on the :mod:`pygame.event` queue for this 268 functionality. 269 270 .. ## pygame.key.get_pressed ## 271 272.. function:: get_mods 273 274 | :sl:`determine which modifier keys are being held` 275 | :sg:`get_mods() -> int` 276 277 Returns a single integer representing a bitmask of all the modifier keys 278 being held. Using bitwise operators you can test if specific 279 :ref:`modifier keys <key-modifiers-label>` are pressed. 280 281 .. ## pygame.key.get_mods ## 282 283.. function:: set_mods 284 285 | :sl:`temporarily set which modifier keys are pressed` 286 | :sg:`set_mods(int) -> None` 287 288 Create a bitmask of the :ref:`modifier key constants <key-modifiers-label>` 289 you want to impose on your program. 290 291 .. ## pygame.key.set_mods ## 292 293.. function:: set_repeat 294 295 | :sl:`control how held keys are repeated` 296 | :sg:`set_repeat() -> None` 297 | :sg:`set_repeat(delay) -> None` 298 | :sg:`set_repeat(delay, interval) -> None` 299 300 When the keyboard repeat is enabled, keys that are held down will generate 301 multiple ``pygame.KEYDOWN`` events. The ``delay`` parameter is the number of 302 milliseconds before the first repeated ``pygame.KEYDOWN`` event will be sent. 303 After that, another ``pygame.KEYDOWN`` event will be sent every ``interval`` 304 milliseconds. If a ``delay`` value is provided and an ``interval`` value is 305 not provided or is 0, then the ``interval`` will be set to the same value as 306 ``delay``. 307 308 To disable key repeat call this function with no arguments or with ``delay`` 309 set to 0. 310 311 When pygame is initialized the key repeat is disabled. 312 313 :raises ValueError: if ``delay`` or ``interval`` is < 0 314 315 .. versionchanged:: 2.0.0 A ``ValueError`` is now raised (instead of a 316 ``pygame.error``) if ``delay`` or ``interval`` is < 0. 317 318 .. ## pygame.key.set_repeat ## 319 320.. function:: get_repeat 321 322 | :sl:`see how held keys are repeated` 323 | :sg:`get_repeat() -> (delay, interval)` 324 325 Get the ``delay`` and ``interval`` keyboard repeat values. Refer to 326 :func:`pygame.key.set_repeat()` for a description of these values. 327 328 .. versionadded:: 1.8 329 330 .. ## pygame.key.get_repeat ## 331 332.. function:: name 333 334 | :sl:`get the name of a key identifier` 335 | :sg:`name(key) -> string` 336 337 Get the descriptive name of the button from a keyboard button id constant. 338 339 .. ## pygame.key.name ## 340 341.. function:: key_code 342 343 | :sl:`get the key identifier from a key name` 344 | :sg:`key_code(name=string) -> int` 345 346 Get the key identifier code from the descriptive name of the key. This 347 returns an integer matching one of the K_* keycodes. For example: 348 349 :: 350 351 >>> pygame.key.key_code("return") == pygame.K_RETURN 352 True 353 >>> pygame.key.key_code("0") == pygame.K_0 354 True 355 >>> pygame.key.key_code("space") == pygame.K_SPACE 356 True 357 358 :raises ValueError: if the key name is not known. 359 :raises NotImplementedError: if used with SDL 1. 360 361 .. ## pygame.key.key_code ## 362 363 .. versionadded:: 2.0.0 364 365 .. ## pygame.key.key_code ## 366 367.. function:: start_text_input 368 369 | :sl:`start handling Unicode text input events` 370 | :sg:`start_text_input() -> None` 371 372 Start receiving ``pygame.TEXTEDITING`` and ``pygame.TEXTINPUT`` 373 events. If applicable, show the on-screen keyboard or IME editor. 374 375 For many languages, key presses will automatically generate a 376 corresponding ``pygame.TEXTINPUT`` event. Special keys like 377 escape or function keys, and certain key combinations will not 378 generate ``pygame.TEXTINPUT`` events. 379 380 In other languages, entering a single symbol may require multiple 381 key presses, or a language-specific user interface. In this case, 382 ``pygame.TEXTINPUT`` events are preferable to ``pygame.KEYDOWN`` 383 events for text input. 384 385 A ``pygame.TEXTEDITING`` event is received when an IME composition 386 is started or changed. It contains the composition ``text``, ``length``, 387 and editing ``start`` position within the composition (attributes 388 ``text``, ``length``, and ``start``, respectively). 389 When the composition is committed (or non-IME input is received), 390 a ``pygame.TEXTINPUT`` event is generated. 391 392 Text input events handling is on by default. 393 394 .. versionadded:: 2.0.0 395 396 .. ## pygame.key.start_text_input ## 397 398.. function:: stop_text_input 399 400 | :sl:`stop handling Unicode text input events` 401 | :sg:`stop_text_input() -> None` 402 403 Stop receiving ``pygame.TEXTEDITING`` and ``pygame.TEXTINPUT`` 404 events. If an on-screen keyboard or IME editor was shown with 405 ``pygame.key.start_text_input()``, hide it again. 406 407 Text input events handling is on by default. 408 409 To avoid triggering the IME editor or the on-screen keyboard 410 when the user is holding down a key during gameplay, text input 411 should be disabled once text entry is finished, or when the user 412 clicks outside of a text box. 413 414 .. versionadded:: 2.0.0 415 416 .. ## pygame.key.stop_text_input ## 417 418.. function:: set_text_input_rect 419 420 | :sl:`controls the position of the candidate list` 421 | :sg:`set_text_input_rect(Rect) -> None` 422 423 This sets the rectangle used for typing with an IME. 424 It controls where the candidate list will open, if supported. 425 426 .. versionadded:: 2.0.0 427 428 .. ## pygame.key.set_text_input_rect ## 429 430.. ## pygame.key ## 431