Atlas - SDL_keyboard.h
Home / ext / SDL / include / SDL3 Lines: 1 | Size: 21492 bytes [Download] [Show on GitHub] [Search similar files] [Raw] [Raw (proxy)][FILE BEGIN]1/* 2 Simple DirectMedia Layer 3 Copyright (C) 1997-2025 Sam Lantinga <[email protected]> 4 5 This software is provided 'as-is', without any express or implied 6 warranty. In no event will the authors be held liable for any damages 7 arising from the use of this software. 8 9 Permission is granted to anyone to use this software for any purpose, 10 including commercial applications, and to alter it and redistribute it 11 freely, subject to the following restrictions: 12 13 1. The origin of this software must not be misrepresented; you must not 14 claim that you wrote the original software. If you use this software 15 in a product, an acknowledgment in the product documentation would be 16 appreciated but is not required. 17 2. Altered source versions must be plainly marked as such, and must not be 18 misrepresented as being the original software. 19 3. This notice may not be removed or altered from any source distribution. 20*/ 21 22/** 23 * # CategoryKeyboard 24 * 25 * SDL keyboard management. 26 * 27 * Please refer to the Best Keyboard Practices document for details on how 28 * best to accept keyboard input in various types of programs: 29 * 30 * https://wiki.libsdl.org/SDL3/BestKeyboardPractices 31 */ 32 33#ifndef SDL_keyboard_h_ 34#define SDL_keyboard_h_ 35 36#include <SDL3/SDL_stdinc.h> 37#include <SDL3/SDL_error.h> 38#include <SDL3/SDL_keycode.h> 39#include <SDL3/SDL_properties.h> 40#include <SDL3/SDL_rect.h> 41#include <SDL3/SDL_scancode.h> 42#include <SDL3/SDL_video.h> 43 44#include <SDL3/SDL_begin_code.h> 45/* Set up for C function definitions, even when using C++ */ 46#ifdef __cplusplus 47extern "C" { 48#endif 49 50/** 51 * This is a unique ID for a keyboard for the time it is connected to the 52 * system, and is never reused for the lifetime of the application. 53 * 54 * If the keyboard is disconnected and reconnected, it will get a new ID. 55 * 56 * The value 0 is an invalid ID. 57 * 58 * \since This datatype is available since SDL 3.2.0. 59 */ 60typedef Uint32 SDL_KeyboardID; 61 62/* Function prototypes */ 63 64/** 65 * Return whether a keyboard is currently connected. 66 * 67 * \returns true if a keyboard is connected, false otherwise. 68 * 69 * \threadsafety This function should only be called on the main thread. 70 * 71 * \since This function is available since SDL 3.2.0. 72 * 73 * \sa SDL_GetKeyboards 74 */ 75extern SDL_DECLSPEC bool SDLCALL SDL_HasKeyboard(void); 76 77/** 78 * Get a list of currently connected keyboards. 79 * 80 * Note that this will include any device or virtual driver that includes 81 * keyboard functionality, including some mice, KVM switches, motherboard 82 * power buttons, etc. You should wait for input from a device before you 83 * consider it actively in use. 84 * 85 * \param count a pointer filled in with the number of keyboards returned, may 86 * be NULL. 87 * \returns a 0 terminated array of keyboards instance IDs or NULL on failure; 88 * call SDL_GetError() for more information. This should be freed 89 * with SDL_free() when it is no longer needed. 90 * 91 * \threadsafety This function should only be called on the main thread. 92 * 93 * \since This function is available since SDL 3.2.0. 94 * 95 * \sa SDL_GetKeyboardNameForID 96 * \sa SDL_HasKeyboard 97 */ 98extern SDL_DECLSPEC SDL_KeyboardID * SDLCALL SDL_GetKeyboards(int *count); 99 100/** 101 * Get the name of a keyboard. 102 * 103 * This function returns "" if the keyboard doesn't have a name. 104 * 105 * \param instance_id the keyboard instance ID. 106 * \returns the name of the selected keyboard or NULL on failure; call 107 * SDL_GetError() for more information. 108 * 109 * \threadsafety This function should only be called on the main thread. 110 * 111 * \since This function is available since SDL 3.2.0. 112 * 113 * \sa SDL_GetKeyboards 114 */ 115extern SDL_DECLSPEC const char * SDLCALL SDL_GetKeyboardNameForID(SDL_KeyboardID instance_id); 116 117/** 118 * Query the window which currently has keyboard focus. 119 * 120 * \returns the window with keyboard focus. 121 * 122 * \threadsafety This function should only be called on the main thread. 123 * 124 * \since This function is available since SDL 3.2.0. 125 */ 126extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void); 127 128/** 129 * Get a snapshot of the current state of the keyboard. 130 * 131 * The pointer returned is a pointer to an internal SDL array. It will be 132 * valid for the whole lifetime of the application and should not be freed by 133 * the caller. 134 * 135 * A array element with a value of true means that the key is pressed and a 136 * value of false means that it is not. Indexes into this array are obtained 137 * by using SDL_Scancode values. 138 * 139 * Use SDL_PumpEvents() to update the state array. 140 * 141 * This function gives you the current state after all events have been 142 * processed, so if a key or button has been pressed and released before you 143 * process events, then the pressed state will never show up in the 144 * SDL_GetKeyboardState() calls. 145 * 146 * Note: This function doesn't take into account whether shift has been 147 * pressed or not. 148 * 149 * \param numkeys if non-NULL, receives the length of the returned array. 150 * \returns a pointer to an array of key states. 151 * 152 * \threadsafety It is safe to call this function from any thread. 153 * 154 * \since This function is available since SDL 3.2.0. 155 * 156 * \sa SDL_PumpEvents 157 * \sa SDL_ResetKeyboard 158 */ 159extern SDL_DECLSPEC const bool * SDLCALL SDL_GetKeyboardState(int *numkeys); 160 161/** 162 * Clear the state of the keyboard. 163 * 164 * This function will generate key up events for all pressed keys. 165 * 166 * \threadsafety This function should only be called on the main thread. 167 * 168 * \since This function is available since SDL 3.2.0. 169 * 170 * \sa SDL_GetKeyboardState 171 */ 172extern SDL_DECLSPEC void SDLCALL SDL_ResetKeyboard(void); 173 174/** 175 * Get the current key modifier state for the keyboard. 176 * 177 * \returns an OR'd combination of the modifier keys for the keyboard. 178 * 179 * \threadsafety It is safe to call this function from any thread. 180 * 181 * \since This function is available since SDL 3.2.0. 182 * 183 * \sa SDL_GetKeyboardState 184 * \sa SDL_SetModState 185 */ 186extern SDL_DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void); 187 188/** 189 * Set the current key modifier state for the keyboard. 190 * 191 * The inverse of SDL_GetModState(), SDL_SetModState() allows you to impose 192 * modifier key states on your application. Simply pass your desired modifier 193 * states into `modstate`. This value may be a bitwise, OR'd combination of 194 * SDL_Keymod values. 195 * 196 * This does not change the keyboard state, only the key modifier flags that 197 * SDL reports. 198 * 199 * \param modstate the desired SDL_Keymod for the keyboard. 200 * 201 * \threadsafety It is safe to call this function from any thread. 202 * 203 * \since This function is available since SDL 3.2.0. 204 * 205 * \sa SDL_GetModState 206 */ 207extern SDL_DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate); 208 209/** 210 * Get the key code corresponding to the given scancode according to the 211 * current keyboard layout. 212 * 213 * If you want to get the keycode as it would be delivered in key events, 214 * including options specified in SDL_HINT_KEYCODE_OPTIONS, then you should 215 * pass `key_event` as true. Otherwise this function simply translates the 216 * scancode based on the given modifier state. 217 * 218 * \param scancode the desired SDL_Scancode to query. 219 * \param modstate the modifier state to use when translating the scancode to 220 * a keycode. 221 * \param key_event true if the keycode will be used in key events. 222 * \returns the SDL_Keycode that corresponds to the given SDL_Scancode. 223 * 224 * \threadsafety This function is not thread safe. 225 * 226 * \since This function is available since SDL 3.2.0. 227 * 228 * \sa SDL_GetKeyName 229 * \sa SDL_GetScancodeFromKey 230 */ 231extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode, SDL_Keymod modstate, bool key_event); 232 233/** 234 * Get the scancode corresponding to the given key code according to the 235 * current keyboard layout. 236 * 237 * Note that there may be multiple scancode+modifier states that can generate 238 * this keycode, this will just return the first one found. 239 * 240 * \param key the desired SDL_Keycode to query. 241 * \param modstate a pointer to the modifier state that would be used when the 242 * scancode generates this key, may be NULL. 243 * \returns the SDL_Scancode that corresponds to the given SDL_Keycode. 244 * 245 * \threadsafety This function is not thread safe. 246 * 247 * \since This function is available since SDL 3.2.0. 248 * 249 * \sa SDL_GetKeyFromScancode 250 * \sa SDL_GetScancodeName 251 */ 252extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromKey(SDL_Keycode key, SDL_Keymod *modstate); 253 254/** 255 * Set a human-readable name for a scancode. 256 * 257 * \param scancode the desired SDL_Scancode. 258 * \param name the name to use for the scancode, encoded as UTF-8. The string 259 * is not copied, so the pointer given to this function must stay 260 * valid while SDL is being used. 261 * \returns true on success or false on failure; call SDL_GetError() for more 262 * information. 263 * 264 * \threadsafety This function is not thread safe. 265 * 266 * \since This function is available since SDL 3.2.0. 267 * 268 * \sa SDL_GetScancodeName 269 */ 270extern SDL_DECLSPEC bool SDLCALL SDL_SetScancodeName(SDL_Scancode scancode, const char *name); 271 272/** 273 * Get a human-readable name for a scancode. 274 * 275 * **Warning**: The returned name is by design not stable across platforms, 276 * e.g. the name for `SDL_SCANCODE_LGUI` is "Left GUI" under Linux but "Left 277 * Windows" under Microsoft Windows, and some scancodes like 278 * `SDL_SCANCODE_NONUSBACKSLASH` don't have any name at all. There are even 279 * scancodes that share names, e.g. `SDL_SCANCODE_RETURN` and 280 * `SDL_SCANCODE_RETURN2` (both called "Return"). This function is therefore 281 * unsuitable for creating a stable cross-platform two-way mapping between 282 * strings and scancodes. 283 * 284 * \param scancode the desired SDL_Scancode to query. 285 * \returns a pointer to the name for the scancode. If the scancode doesn't 286 * have a name this function returns an empty string (""). 287 * 288 * \threadsafety This function is not thread safe. 289 * 290 * \since This function is available since SDL 3.2.0. 291 * 292 * \sa SDL_GetScancodeFromKey 293 * \sa SDL_GetScancodeFromName 294 * \sa SDL_SetScancodeName 295 */ 296extern SDL_DECLSPEC const char * SDLCALL SDL_GetScancodeName(SDL_Scancode scancode); 297 298/** 299 * Get a scancode from a human-readable name. 300 * 301 * \param name the human-readable scancode name. 302 * \returns the SDL_Scancode, or `SDL_SCANCODE_UNKNOWN` if the name wasn't 303 * recognized; call SDL_GetError() for more information. 304 * 305 * \threadsafety This function is not thread safe. 306 * 307 * \since This function is available since SDL 3.2.0. 308 * 309 * \sa SDL_GetKeyFromName 310 * \sa SDL_GetScancodeFromKey 311 * \sa SDL_GetScancodeName 312 */ 313extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *name); 314 315/** 316 * Get a human-readable name for a key. 317 * 318 * If the key doesn't have a name, this function returns an empty string (""). 319 * 320 * Letters will be presented in their uppercase form, if applicable. 321 * 322 * \param key the desired SDL_Keycode to query. 323 * \returns a UTF-8 encoded string of the key name. 324 * 325 * \threadsafety This function is not thread safe. 326 * 327 * \since This function is available since SDL 3.2.0. 328 * 329 * \sa SDL_GetKeyFromName 330 * \sa SDL_GetKeyFromScancode 331 * \sa SDL_GetScancodeFromKey 332 */ 333extern SDL_DECLSPEC const char * SDLCALL SDL_GetKeyName(SDL_Keycode key); 334 335/** 336 * Get a key code from a human-readable name. 337 * 338 * \param name the human-readable key name. 339 * \returns key code, or `SDLK_UNKNOWN` if the name wasn't recognized; call 340 * SDL_GetError() for more information. 341 * 342 * \threadsafety This function is not thread safe. 343 * 344 * \since This function is available since SDL 3.2.0. 345 * 346 * \sa SDL_GetKeyFromScancode 347 * \sa SDL_GetKeyName 348 * \sa SDL_GetScancodeFromName 349 */ 350extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name); 351 352/** 353 * Start accepting Unicode text input events in a window. 354 * 355 * This function will enable text input (SDL_EVENT_TEXT_INPUT and 356 * SDL_EVENT_TEXT_EDITING events) in the specified window. Please use this 357 * function paired with SDL_StopTextInput(). 358 * 359 * Text input events are not received by default. 360 * 361 * On some platforms using this function shows the screen keyboard and/or 362 * activates an IME, which can prevent some key press events from being passed 363 * through. 364 * 365 * \param window the window to enable text input. 366 * \returns true on success or false on failure; call SDL_GetError() for more 367 * information. 368 * 369 * \threadsafety This function should only be called on the main thread. 370 * 371 * \since This function is available since SDL 3.2.0. 372 * 373 * \sa SDL_SetTextInputArea 374 * \sa SDL_StartTextInputWithProperties 375 * \sa SDL_StopTextInput 376 * \sa SDL_TextInputActive 377 */ 378extern SDL_DECLSPEC bool SDLCALL SDL_StartTextInput(SDL_Window *window); 379 380/** 381 * Text input type. 382 * 383 * These are the valid values for SDL_PROP_TEXTINPUT_TYPE_NUMBER. Not every 384 * value is valid on every platform, but where a value isn't supported, a 385 * reasonable fallback will be used. 386 * 387 * \since This enum is available since SDL 3.2.0. 388 * 389 * \sa SDL_StartTextInputWithProperties 390 */ 391typedef enum SDL_TextInputType 392{ 393 SDL_TEXTINPUT_TYPE_TEXT, /**< The input is text */ 394 SDL_TEXTINPUT_TYPE_TEXT_NAME, /**< The input is a person's name */ 395 SDL_TEXTINPUT_TYPE_TEXT_EMAIL, /**< The input is an e-mail address */ 396 SDL_TEXTINPUT_TYPE_TEXT_USERNAME, /**< The input is a username */ 397 SDL_TEXTINPUT_TYPE_TEXT_PASSWORD_HIDDEN, /**< The input is a secure password that is hidden */ 398 SDL_TEXTINPUT_TYPE_TEXT_PASSWORD_VISIBLE, /**< The input is a secure password that is visible */ 399 SDL_TEXTINPUT_TYPE_NUMBER, /**< The input is a number */ 400 SDL_TEXTINPUT_TYPE_NUMBER_PASSWORD_HIDDEN, /**< The input is a secure PIN that is hidden */ 401 SDL_TEXTINPUT_TYPE_NUMBER_PASSWORD_VISIBLE /**< The input is a secure PIN that is visible */ 402} SDL_TextInputType; 403 404/** 405 * Auto capitalization type. 406 * 407 * These are the valid values for SDL_PROP_TEXTINPUT_CAPITALIZATION_NUMBER. 408 * Not every value is valid on every platform, but where a value isn't 409 * supported, a reasonable fallback will be used. 410 * 411 * \since This enum is available since SDL 3.2.0. 412 * 413 * \sa SDL_StartTextInputWithProperties 414 */ 415typedef enum SDL_Capitalization 416{ 417 SDL_CAPITALIZE_NONE, /**< No auto-capitalization will be done */ 418 SDL_CAPITALIZE_SENTENCES, /**< The first letter of sentences will be capitalized */ 419 SDL_CAPITALIZE_WORDS, /**< The first letter of words will be capitalized */ 420 SDL_CAPITALIZE_LETTERS /**< All letters will be capitalized */ 421} SDL_Capitalization; 422 423/** 424 * Start accepting Unicode text input events in a window, with properties 425 * describing the input. 426 * 427 * This function will enable text input (SDL_EVENT_TEXT_INPUT and 428 * SDL_EVENT_TEXT_EDITING events) in the specified window. Please use this 429 * function paired with SDL_StopTextInput(). 430 * 431 * Text input events are not received by default. 432 * 433 * On some platforms using this function shows the screen keyboard and/or 434 * activates an IME, which can prevent some key press events from being passed 435 * through. 436 * 437 * These are the supported properties: 438 * 439 * - `SDL_PROP_TEXTINPUT_TYPE_NUMBER` - an SDL_TextInputType value that 440 * describes text being input, defaults to SDL_TEXTINPUT_TYPE_TEXT. 441 * - `SDL_PROP_TEXTINPUT_CAPITALIZATION_NUMBER` - an SDL_Capitalization value 442 * that describes how text should be capitalized, defaults to 443 * SDL_CAPITALIZE_SENTENCES for normal text entry, SDL_CAPITALIZE_WORDS for 444 * SDL_TEXTINPUT_TYPE_TEXT_NAME, and SDL_CAPITALIZE_NONE for e-mail 445 * addresses, usernames, and passwords. 446 * - `SDL_PROP_TEXTINPUT_AUTOCORRECT_BOOLEAN` - true to enable auto completion 447 * and auto correction, defaults to true. 448 * - `SDL_PROP_TEXTINPUT_MULTILINE_BOOLEAN` - true if multiple lines of text 449 * are allowed. This defaults to true if SDL_HINT_RETURN_KEY_HIDES_IME is 450 * "0" or is not set, and defaults to false if SDL_HINT_RETURN_KEY_HIDES_IME 451 * is "1". 452 * 453 * On Android you can directly specify the input type: 454 * 455 * - `SDL_PROP_TEXTINPUT_ANDROID_INPUTTYPE_NUMBER` - the text input type to 456 * use, overriding other properties. This is documented at 457 * https://developer.android.com/reference/android/text/InputType 458 * 459 * \param window the window to enable text input. 460 * \param props the properties to use. 461 * \returns true on success or false on failure; call SDL_GetError() for more 462 * information. 463 * 464 * \threadsafety This function should only be called on the main thread. 465 * 466 * \since This function is available since SDL 3.2.0. 467 * 468 * \sa SDL_SetTextInputArea 469 * \sa SDL_StartTextInput 470 * \sa SDL_StopTextInput 471 * \sa SDL_TextInputActive 472 */ 473extern SDL_DECLSPEC bool SDLCALL SDL_StartTextInputWithProperties(SDL_Window *window, SDL_PropertiesID props); 474 475#define SDL_PROP_TEXTINPUT_TYPE_NUMBER "SDL.textinput.type" 476#define SDL_PROP_TEXTINPUT_CAPITALIZATION_NUMBER "SDL.textinput.capitalization" 477#define SDL_PROP_TEXTINPUT_AUTOCORRECT_BOOLEAN "SDL.textinput.autocorrect" 478#define SDL_PROP_TEXTINPUT_MULTILINE_BOOLEAN "SDL.textinput.multiline" 479#define SDL_PROP_TEXTINPUT_ANDROID_INPUTTYPE_NUMBER "SDL.textinput.android.inputtype" 480 481/** 482 * Check whether or not Unicode text input events are enabled for a window. 483 * 484 * \param window the window to check. 485 * \returns true if text input events are enabled else false. 486 * 487 * \threadsafety This function should only be called on the main thread. 488 * 489 * \since This function is available since SDL 3.2.0. 490 * 491 * \sa SDL_StartTextInput 492 */ 493extern SDL_DECLSPEC bool SDLCALL SDL_TextInputActive(SDL_Window *window); 494 495/** 496 * Stop receiving any text input events in a window. 497 * 498 * If SDL_StartTextInput() showed the screen keyboard, this function will hide 499 * it. 500 * 501 * \param window the window to disable text input. 502 * \returns true on success or false on failure; call SDL_GetError() for more 503 * information. 504 * 505 * \threadsafety This function should only be called on the main thread. 506 * 507 * \since This function is available since SDL 3.2.0. 508 * 509 * \sa SDL_StartTextInput 510 */ 511extern SDL_DECLSPEC bool SDLCALL SDL_StopTextInput(SDL_Window *window); 512 513/** 514 * Dismiss the composition window/IME without disabling the subsystem. 515 * 516 * \param window the window to affect. 517 * \returns true on success or false on failure; call SDL_GetError() for more 518 * information. 519 * 520 * \threadsafety This function should only be called on the main thread. 521 * 522 * \since This function is available since SDL 3.2.0. 523 * 524 * \sa SDL_StartTextInput 525 * \sa SDL_StopTextInput 526 */ 527extern SDL_DECLSPEC bool SDLCALL SDL_ClearComposition(SDL_Window *window); 528 529/** 530 * Set the area used to type Unicode text input. 531 * 532 * Native input methods may place a window with word suggestions near the 533 * cursor, without covering the text being entered. 534 * 535 * \param window the window for which to set the text input area. 536 * \param rect the SDL_Rect representing the text input area, in window 537 * coordinates, or NULL to clear it. 538 * \param cursor the offset of the current cursor location relative to 539 * `rect->x`, in window coordinates. 540 * \returns true on success or false on failure; call SDL_GetError() for more 541 * information. 542 * 543 * \threadsafety This function should only be called on the main thread. 544 * 545 * \since This function is available since SDL 3.2.0. 546 * 547 * \sa SDL_GetTextInputArea 548 * \sa SDL_StartTextInput 549 */ 550extern SDL_DECLSPEC bool SDLCALL SDL_SetTextInputArea(SDL_Window *window, const SDL_Rect *rect, int cursor); 551 552/** 553 * Get the area used to type Unicode text input. 554 * 555 * This returns the values previously set by SDL_SetTextInputArea(). 556 * 557 * \param window the window for which to query the text input area. 558 * \param rect a pointer to an SDL_Rect filled in with the text input area, 559 * may be NULL. 560 * \param cursor a pointer to the offset of the current cursor location 561 * relative to `rect->x`, may be NULL. 562 * \returns true on success or false on failure; call SDL_GetError() for more 563 * information. 564 * 565 * \threadsafety This function should only be called on the main thread. 566 * 567 * \since This function is available since SDL 3.2.0. 568 * 569 * \sa SDL_SetTextInputArea 570 */ 571extern SDL_DECLSPEC bool SDLCALL SDL_GetTextInputArea(SDL_Window *window, SDL_Rect *rect, int *cursor); 572 573/** 574 * Check whether the platform has screen keyboard support. 575 * 576 * \returns true if the platform has some screen keyboard support or false if 577 * not. 578 * 579 * \threadsafety This function should only be called on the main thread. 580 * 581 * \since This function is available since SDL 3.2.0. 582 * 583 * \sa SDL_StartTextInput 584 * \sa SDL_ScreenKeyboardShown 585 */ 586extern SDL_DECLSPEC bool SDLCALL SDL_HasScreenKeyboardSupport(void); 587 588/** 589 * Check whether the screen keyboard is shown for given window. 590 * 591 * \param window the window for which screen keyboard should be queried. 592 * \returns true if screen keyboard is shown or false if not. 593 * 594 * \threadsafety This function should only be called on the main thread. 595 * 596 * \since This function is available since SDL 3.2.0. 597 * 598 * \sa SDL_HasScreenKeyboardSupport 599 */ 600extern SDL_DECLSPEC bool SDLCALL SDL_ScreenKeyboardShown(SDL_Window *window); 601 602/* Ends C function definitions when using C++ */ 603#ifdef __cplusplus 604} 605#endif 606#include <SDL3/SDL_close_code.h> 607 608#endif /* SDL_keyboard_h_ */ 609[FILE END](C) 2025 0x4248 (C) 2025 4248 Media and 4248 Systems, All part of 0x4248 See LICENCE files for more information. Not all files are by 0x4248 always check Licencing.