1 /* 2 Simple DirectMedia Layer 3 Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org> 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 * Include file for SDL keyboard event handling 26 */ 27 28 #ifndef SDL_keyboard_h_ 29 #define SDL_keyboard_h_ 30 31 #include "SDL_stdinc.h" 32 #include "SDL_error.h" 33 #include "SDL_keycode.h" 34 #include "SDL_video.h" 35 36 #include "begin_code.h" 37 /* Set up for C function definitions, even when using C++ */ 38 #ifdef __cplusplus 39 extern "C" { 40 #endif 41 42 /** 43 * The SDL keysym structure, used in key events. 44 * 45 * If you are looking for translated character input, see the SDL_TEXTINPUT 46 * event. 47 */ 48 typedef struct SDL_Keysym 49 { 50 SDL_Scancode scancode; /**< SDL physical key code - see SDL_Scancode for details */ 51 SDL_Keycode sym; /**< SDL virtual key code - see SDL_Keycode for details */ 52 Uint16 mod; /**< current key modifiers */ 53 Uint32 unused; 54 } SDL_Keysym; 55 56 /* Function prototypes */ 57 58 /** 59 * Query the window which currently has keyboard focus. 60 * 61 * \returns the window with keyboard focus. 62 * 63 * \since This function is available since SDL 2.0.0. 64 */ 65 extern DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void); 66 67 /** 68 * Get a snapshot of the current state of the keyboard. 69 * 70 * The pointer returned is a pointer to an internal SDL array. It will be 71 * valid for the whole lifetime of the application and should not be freed by 72 * the caller. 73 * 74 * A array element with a value of 1 means that the key is pressed and a value 75 * of 0 means that it is not. Indexes into this array are obtained by using 76 * SDL_Scancode values. 77 * 78 * Use SDL_PumpEvents() to update the state array. 79 * 80 * This function gives you the current state after all events have been 81 * processed, so if a key or button has been pressed and released before you 82 * process events, then the pressed state will never show up in the 83 * SDL_GetKeyboardState() calls. 84 * 85 * Note: This function doesn't take into account whether shift has been 86 * pressed or not. 87 * 88 * \param numkeys if non-NULL, receives the length of the returned array. 89 * \returns a pointer to an array of key states. 90 * 91 * \since This function is available since SDL 2.0.0. 92 * 93 * \sa SDL_PumpEvents 94 * \sa SDL_ResetKeyboard 95 */ 96 extern DECLSPEC const Uint8 *SDLCALL SDL_GetKeyboardState(int *numkeys); 97 98 /** 99 * Clear the state of the keyboard 100 * 101 * This function will generate key up events for all pressed keys. 102 * 103 * \since This function is available since SDL 2.24.0. 104 * 105 * \sa SDL_GetKeyboardState 106 */ 107 extern DECLSPEC void SDLCALL SDL_ResetKeyboard(void); 108 109 /** 110 * Get the current key modifier state for the keyboard. 111 * 112 * \returns an OR'd combination of the modifier keys for the keyboard. See 113 * SDL_Keymod for details. 114 * 115 * \since This function is available since SDL 2.0.0. 116 * 117 * \sa SDL_GetKeyboardState 118 * \sa SDL_SetModState 119 */ 120 extern DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void); 121 122 /** 123 * Set the current key modifier state for the keyboard. 124 * 125 * The inverse of SDL_GetModState(), SDL_SetModState() allows you to impose 126 * modifier key states on your application. Simply pass your desired modifier 127 * states into `modstate`. This value may be a bitwise, OR'd combination of 128 * SDL_Keymod values. 129 * 130 * This does not change the keyboard state, only the key modifier flags that 131 * SDL reports. 132 * 133 * \param modstate the desired SDL_Keymod for the keyboard. 134 * 135 * \since This function is available since SDL 2.0.0. 136 * 137 * \sa SDL_GetModState 138 */ 139 extern DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate); 140 141 /** 142 * Get the key code corresponding to the given scancode according to the 143 * current keyboard layout. 144 * 145 * See SDL_Keycode for details. 146 * 147 * \param scancode the desired SDL_Scancode to query. 148 * \returns the SDL_Keycode that corresponds to the given SDL_Scancode. 149 * 150 * \since This function is available since SDL 2.0.0. 151 * 152 * \sa SDL_GetKeyName 153 * \sa SDL_GetScancodeFromKey 154 */ 155 extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode); 156 157 /** 158 * Get the scancode corresponding to the given key code according to the 159 * current keyboard layout. 160 * 161 * See SDL_Scancode for details. 162 * 163 * \param key the desired SDL_Keycode to query. 164 * \returns the SDL_Scancode that corresponds to the given SDL_Keycode. 165 * 166 * \since This function is available since SDL 2.0.0. 167 * 168 * \sa SDL_GetKeyFromScancode 169 * \sa SDL_GetScancodeName 170 */ 171 extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromKey(SDL_Keycode key); 172 173 /** 174 * Get a human-readable name for a scancode. 175 * 176 * See SDL_Scancode for details. 177 * 178 * **Warning**: The returned name is by design not stable across platforms, 179 * e.g. the name for `SDL_SCANCODE_LGUI` is "Left GUI" under Linux but "Left 180 * Windows" under Microsoft Windows, and some scancodes like 181 * `SDL_SCANCODE_NONUSBACKSLASH` don't have any name at all. There are even 182 * scancodes that share names, e.g. `SDL_SCANCODE_RETURN` and 183 * `SDL_SCANCODE_RETURN2` (both called "Return"). This function is therefore 184 * unsuitable for creating a stable cross-platform two-way mapping between 185 * strings and scancodes. 186 * 187 * \param scancode the desired SDL_Scancode to query. 188 * \returns a pointer to the name for the scancode. If the scancode doesn't 189 * have a name this function returns an empty string (""). 190 * 191 * \since This function is available since SDL 2.0.0. 192 * 193 * \sa SDL_GetScancodeFromKey 194 * \sa SDL_GetScancodeFromName 195 */ 196 extern DECLSPEC const char *SDLCALL SDL_GetScancodeName(SDL_Scancode scancode); 197 198 /** 199 * Get a scancode from a human-readable name. 200 * 201 * \param name the human-readable scancode name. 202 * \returns the SDL_Scancode, or `SDL_SCANCODE_UNKNOWN` if the name wasn't 203 * recognized; call SDL_GetError() for more information. 204 * 205 * \since This function is available since SDL 2.0.0. 206 * 207 * \sa SDL_GetKeyFromName 208 * \sa SDL_GetScancodeFromKey 209 * \sa SDL_GetScancodeName 210 */ 211 extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *name); 212 213 /** 214 * Get a human-readable name for a key. 215 * 216 * See SDL_Scancode and SDL_Keycode for details. 217 * 218 * \param key the desired SDL_Keycode to query. 219 * \returns a pointer to a UTF-8 string that stays valid at least until the 220 * next call to this function. If you need it around any longer, you 221 * must copy it. If the key doesn't have a name, this function 222 * returns an empty string (""). 223 * 224 * \since This function is available since SDL 2.0.0. 225 * 226 * \sa SDL_GetKeyFromName 227 * \sa SDL_GetKeyFromScancode 228 * \sa SDL_GetScancodeFromKey 229 */ 230 extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDL_Keycode key); 231 232 /** 233 * Get a key code from a human-readable name. 234 * 235 * \param name the human-readable key name. 236 * \returns key code, or `SDLK_UNKNOWN` if the name wasn't recognized; call 237 * SDL_GetError() for more information. 238 * 239 * \since This function is available since SDL 2.0.0. 240 * 241 * \sa SDL_GetKeyFromScancode 242 * \sa SDL_GetKeyName 243 * \sa SDL_GetScancodeFromName 244 */ 245 extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name); 246 247 /** 248 * Start accepting Unicode text input events. 249 * 250 * This function will start accepting Unicode text input events in the focused 251 * SDL window, and start emitting SDL_TextInputEvent (SDL_TEXTINPUT) and 252 * SDL_TextEditingEvent (SDL_TEXTEDITING) events. Please use this function in 253 * pair with SDL_StopTextInput(). 254 * 255 * On some platforms using this function activates the screen keyboard. 256 * 257 * On desktop platforms, SDL_StartTextInput() is implicitly called on SDL 258 * video subsystem initialization which will cause SDL_TextInputEvent and 259 * SDL_TextEditingEvent to begin emitting. 260 * 261 * \since This function is available since SDL 2.0.0. 262 * 263 * \sa SDL_SetTextInputRect 264 * \sa SDL_StopTextInput 265 */ 266 extern DECLSPEC void SDLCALL SDL_StartTextInput(void); 267 268 /** 269 * Check whether or not Unicode text input events are enabled. 270 * 271 * \returns SDL_TRUE if text input events are enabled else SDL_FALSE. 272 * 273 * \since This function is available since SDL 2.0.0. 274 * 275 * \sa SDL_StartTextInput 276 */ 277 extern DECLSPEC SDL_bool SDLCALL SDL_IsTextInputActive(void); 278 279 /** 280 * Stop receiving any text input events. 281 * 282 * \since This function is available since SDL 2.0.0. 283 * 284 * \sa SDL_StartTextInput 285 */ 286 extern DECLSPEC void SDLCALL SDL_StopTextInput(void); 287 288 /** 289 * Dismiss the composition window/IME without disabling the subsystem. 290 * 291 * \since This function is available since SDL 2.0.22. 292 * 293 * \sa SDL_StartTextInput 294 * \sa SDL_StopTextInput 295 */ 296 extern DECLSPEC void SDLCALL SDL_ClearComposition(void); 297 298 /** 299 * Returns if an IME Composite or Candidate window is currently shown. 300 * 301 * \since This function is available since SDL 2.0.22. 302 */ 303 extern DECLSPEC SDL_bool SDLCALL SDL_IsTextInputShown(void); 304 305 /** 306 * Set the rectangle used to type Unicode text inputs. 307 * 308 * Native input methods will place a window with word suggestions near it, 309 * without covering the text being inputted. 310 * 311 * To start text input in a given location, this function is intended to be 312 * called before SDL_StartTextInput, although some platforms support moving 313 * the rectangle even while text input (and a composition) is active. 314 * 315 * Note: If you want to use the system native IME window, try setting hint 316 * **SDL_HINT_IME_SHOW_UI** to **1**, otherwise this function won't give you 317 * any feedback. 318 * 319 * \param rect the SDL_Rect structure representing the rectangle to receive 320 * text (ignored if NULL). 321 * 322 * \since This function is available since SDL 2.0.0. 323 * 324 * \sa SDL_StartTextInput 325 */ 326 extern DECLSPEC void SDLCALL SDL_SetTextInputRect(const SDL_Rect *rect); 327 328 /** 329 * Check whether the platform has screen keyboard support. 330 * 331 * \returns SDL_TRUE if the platform has some screen keyboard support or 332 * SDL_FALSE if not. 333 * 334 * \since This function is available since SDL 2.0.0. 335 * 336 * \sa SDL_StartTextInput 337 * \sa SDL_IsScreenKeyboardShown 338 */ 339 extern DECLSPEC SDL_bool SDLCALL SDL_HasScreenKeyboardSupport(void); 340 341 /** 342 * Check whether the screen keyboard is shown for given window. 343 * 344 * \param window the window for which screen keyboard should be queried. 345 * \returns SDL_TRUE if screen keyboard is shown or SDL_FALSE if not. 346 * 347 * \since This function is available since SDL 2.0.0. 348 * 349 * \sa SDL_HasScreenKeyboardSupport 350 */ 351 extern DECLSPEC SDL_bool SDLCALL SDL_IsScreenKeyboardShown(SDL_Window *window); 352 353 /* Ends C function definitions when using C++ */ 354 #ifdef __cplusplus 355 } 356 #endif 357 #include "close_code.h" 358 359 #endif /* SDL_keyboard_h_ */ 360 361 /* vi: set ts=4 sw=4 expandtab: */