SDL 3.0
SDL_keyboard.h
Go to the documentation of this file.
1/*
2 Simple DirectMedia Layer
3 Copyright (C) 1997-2024 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 * SDL keyboard management.
26 */
27
28#ifndef SDL_keyboard_h_
29#define SDL_keyboard_h_
30
31#include <SDL3/SDL_stdinc.h>
32#include <SDL3/SDL_error.h>
33#include <SDL3/SDL_keycode.h>
34#include <SDL3/SDL_video.h>
35
36#include <SDL3/SDL_begin_code.h>
37/* Set up for C function definitions, even when using C++ */
38#ifdef __cplusplus
39extern "C" {
40#endif
41
42/**
43 * This is a unique ID for a keyboard for the time it is connected to the
44 * system, and is never reused for the lifetime of the application.
45 *
46 * If the keyboard is disconnected and reconnected, it will get a new ID.
47 *
48 * The ID value starts at 1 and increments from there. The value 0 is an
49 * invalid ID.
50 *
51 * \since This datatype is available since SDL 3.0.0.
52 */
54
55/* Function prototypes */
56
57/**
58 * Return whether a keyboard is currently connected.
59 *
60 * \returns SDL_TRUE if a keyboard is connected, SDL_FALSE otherwise.
61 *
62 * \since This function is available since SDL 3.0.0.
63 *
64 * \sa SDL_GetKeyboards
65 */
66extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasKeyboard(void);
67
68/**
69 * Get a list of currently connected keyboards.
70 *
71 * Note that this will include any device or virtual driver that includes
72 * keyboard functionality, including some mice, KVM switches, motherboard
73 * power buttons, etc. You should wait for input from a device before you
74 * consider it actively in use.
75 *
76 * \param count a pointer filled in with the number of keyboards returned, may
77 * be NULL.
78 * \returns a 0 terminated array of keyboards instance IDs or NULL on failure;
79 * call SDL_GetError() for more information. This should be freed
80 * with SDL_free() when it is no longer needed.
81 *
82 * \since This function is available since SDL 3.0.0.
83 *
84 * \sa SDL_GetKeyboardNameForID
85 * \sa SDL_HasKeyboard
86 */
87extern SDL_DECLSPEC SDL_KeyboardID * SDLCALL SDL_GetKeyboards(int *count);
88
89/**
90 * Get the name of a keyboard.
91 *
92 * This function returns "" if the keyboard doesn't have a name.
93 *
94 * \param instance_id the keyboard instance ID.
95 * \returns the name of the selected keyboard or NULL on failure; call
96 * SDL_GetError() for more information.
97 *
98 * \since This function is available since SDL 3.0.0.
99 *
100 * \sa SDL_GetKeyboards
101 */
102extern SDL_DECLSPEC const char * SDLCALL SDL_GetKeyboardNameForID(SDL_KeyboardID instance_id);
103
104/**
105 * Query the window which currently has keyboard focus.
106 *
107 * \returns the window with keyboard focus.
108 *
109 * \since This function is available since SDL 3.0.0.
110 */
111extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void);
112
113/**
114 * Get a snapshot of the current state of the keyboard.
115 *
116 * The pointer returned is a pointer to an internal SDL array. It will be
117 * valid for the whole lifetime of the application and should not be freed by
118 * the caller.
119 *
120 * A array element with a value of 1 means that the key is pressed and a value
121 * of 0 means that it is not. Indexes into this array are obtained by using
122 * SDL_Scancode values.
123 *
124 * Use SDL_PumpEvents() to update the state array.
125 *
126 * This function gives you the current state after all events have been
127 * processed, so if a key or button has been pressed and released before you
128 * process events, then the pressed state will never show up in the
129 * SDL_GetKeyboardState() calls.
130 *
131 * Note: This function doesn't take into account whether shift has been
132 * pressed or not.
133 *
134 * \param numkeys if non-NULL, receives the length of the returned array.
135 * \returns a pointer to an array of key states.
136 *
137 * \since This function is available since SDL 3.0.0.
138 *
139 * \sa SDL_PumpEvents
140 * \sa SDL_ResetKeyboard
141 */
142extern SDL_DECLSPEC const Uint8 * SDLCALL SDL_GetKeyboardState(int *numkeys);
143
144/**
145 * Clear the state of the keyboard.
146 *
147 * This function will generate key up events for all pressed keys.
148 *
149 * \since This function is available since SDL 3.0.0.
150 *
151 * \sa SDL_GetKeyboardState
152 */
153extern SDL_DECLSPEC void SDLCALL SDL_ResetKeyboard(void);
154
155/**
156 * Get the current key modifier state for the keyboard.
157 *
158 * \returns an OR'd combination of the modifier keys for the keyboard. See
159 * SDL_Keymod for details.
160 *
161 * \since This function is available since SDL 3.0.0.
162 *
163 * \sa SDL_GetKeyboardState
164 * \sa SDL_SetModState
165 */
166extern SDL_DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void);
167
168/**
169 * Set the current key modifier state for the keyboard.
170 *
171 * The inverse of SDL_GetModState(), SDL_SetModState() allows you to impose
172 * modifier key states on your application. Simply pass your desired modifier
173 * states into `modstate`. This value may be a bitwise, OR'd combination of
174 * SDL_Keymod values.
175 *
176 * This does not change the keyboard state, only the key modifier flags that
177 * SDL reports.
178 *
179 * \param modstate the desired SDL_Keymod for the keyboard.
180 *
181 * \since This function is available since SDL 3.0.0.
182 *
183 * \sa SDL_GetModState
184 */
185extern SDL_DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate);
186
187/**
188 * Get the key code corresponding to the given scancode according to a default
189 * en_US keyboard layout.
190 *
191 * See SDL_Keycode for details.
192 *
193 * \param scancode the desired SDL_Scancode to query.
194 * \param modstate the modifier state to use when translating the scancode to
195 * a keycode.
196 * \returns the SDL_Keycode that corresponds to the given SDL_Scancode.
197 *
198 * \since This function is available since SDL 3.0.0.
199 *
200 * \sa SDL_GetKeyName
201 * \sa SDL_GetScancodeFromKey
202 */
203extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetDefaultKeyFromScancode(SDL_Scancode scancode, SDL_Keymod modstate);
204
205/**
206 * Get the key code corresponding to the given scancode according to the
207 * current keyboard layout.
208 *
209 * See SDL_Keycode for details.
210 *
211 * \param scancode the desired SDL_Scancode to query.
212 * \param modstate the modifier state to use when translating the scancode to
213 * a keycode.
214 * \returns the SDL_Keycode that corresponds to the given SDL_Scancode.
215 *
216 * \since This function is available since SDL 3.0.0.
217 *
218 * \sa SDL_GetDefaultKeyFromScancode
219 * \sa SDL_GetKeyName
220 * \sa SDL_GetScancodeFromKey
221 */
222extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode, SDL_Keymod modstate);
223
224/**
225 * Get the scancode corresponding to the given key code according to a default
226 * en_US keyboard layout.
227 *
228 * Note that there may be multiple scancode+modifier states that can generate
229 * this keycode, this will just return the first one found.
230 *
231 * \param key the desired SDL_Keycode to query.
232 * \param modstate a pointer to the modifier state that would be used when the
233 * scancode generates this key, may be NULL.
234 * \returns the SDL_Scancode that corresponds to the given SDL_Keycode.
235 *
236 * \since This function is available since SDL 3.0.0.
237 *
238 * \sa SDL_GetScancodeFromKey
239 * \sa SDL_GetScancodeName
240 */
241extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetDefaultScancodeFromKey(SDL_Keycode key, SDL_Keymod *modstate);
242
243/**
244 * Get the scancode corresponding to the given key code according to the
245 * current keyboard layout.
246 *
247 * Note that there may be multiple scancode+modifier states that can generate
248 * this keycode, this will just return the first one found.
249 *
250 * \param key the desired SDL_Keycode to query.
251 * \param modstate a pointer to the modifier state that would be used when the
252 * scancode generates this key, may be NULL.
253 * \returns the SDL_Scancode that corresponds to the given SDL_Keycode.
254 *
255 * \since This function is available since SDL 3.0.0.
256 *
257 * \sa SDL_GetDefaultScancodeFromKey
258 * \sa SDL_GetKeyFromScancode
259 * \sa SDL_GetScancodeName
260 */
261extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromKey(SDL_Keycode key, SDL_Keymod *modstate);
262
263/**
264 * Set a human-readable name for a scancode.
265 *
266 * \param scancode the desired SDL_Scancode.
267 * \param name the name to use for the scancode, encoded as UTF-8. The string
268 * is not copied, so the pointer given to this function must stay
269 * valid while SDL is being used.
270 * \returns 0 on success or a negative error code on failure; call
271 * SDL_GetError() for more information.
272 *
273 * \since This function is available since SDL 3.0.0.
274 *
275 * \sa SDL_GetScancodeName
276 */
277extern SDL_DECLSPEC int SDLCALL SDL_SetScancodeName(SDL_Scancode scancode, const char *name);
278
279/**
280 * Get a human-readable name for a scancode.
281 *
282 * **Warning**: The returned name is by design not stable across platforms,
283 * e.g. the name for `SDL_SCANCODE_LGUI` is "Left GUI" under Linux but "Left
284 * Windows" under Microsoft Windows, and some scancodes like
285 * `SDL_SCANCODE_NONUSBACKSLASH` don't have any name at all. There are even
286 * scancodes that share names, e.g. `SDL_SCANCODE_RETURN` and
287 * `SDL_SCANCODE_RETURN2` (both called "Return"). This function is therefore
288 * unsuitable for creating a stable cross-platform two-way mapping between
289 * strings and scancodes.
290 *
291 * \param scancode the desired SDL_Scancode to query.
292 * \returns a pointer to the name for the scancode. If the scancode doesn't
293 * have a name this function returns an empty string ("").
294 *
295 * \since This function is available since SDL 3.0.0.
296 *
297 * \sa SDL_GetScancodeFromKey
298 * \sa SDL_GetScancodeFromName
299 * \sa SDL_SetScancodeName
300 */
301extern SDL_DECLSPEC const char * SDLCALL SDL_GetScancodeName(SDL_Scancode scancode);
302
303/**
304 * Get a scancode from a human-readable name.
305 *
306 * \param name the human-readable scancode name.
307 * \returns the SDL_Scancode, or `SDL_SCANCODE_UNKNOWN` if the name wasn't
308 * recognized; call SDL_GetError() for more information.
309 *
310 * \since This function is available since SDL 3.0.0.
311 *
312 * \sa SDL_GetKeyFromName
313 * \sa SDL_GetScancodeFromKey
314 * \sa SDL_GetScancodeName
315 */
316extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *name);
317
318/**
319 * Get a human-readable name for a key.
320 *
321 * Both lowercase and uppercase alphabetic keycodes have uppercase names, e.g.
322 * SDL_Keycode 'a' and 'A' both have the name "A".
323 *
324 * If the key doesn't have a name, this function returns an empty string ("").
325 *
326 * \param key the desired SDL_Keycode to query.
327 * \returns a UTF-8 encoded string of the key name.
328 *
329 * \since This function is available since SDL 3.0.0.
330 *
331 * \sa SDL_GetKeyFromName
332 * \sa SDL_GetKeyFromScancode
333 * \sa SDL_GetScancodeFromKey
334 */
335extern SDL_DECLSPEC const char * SDLCALL SDL_GetKeyName(SDL_Keycode key);
336
337/**
338 * Get a key code from a human-readable name.
339 *
340 * \param name the human-readable key name.
341 * \returns key code, or `SDLK_UNKNOWN` if the name wasn't recognized; call
342 * SDL_GetError() for more information.
343 *
344 * \since This function is available since SDL 3.0.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.
362 *
363 * \param window the window to enable text input.
364 * \returns 0 on success or a negative error code on failure; call
365 * SDL_GetError() for more information.
366 *
367 * \since This function is available since SDL 3.0.0.
368 *
369 * \sa SDL_SetTextInputArea
370 * \sa SDL_StopTextInput
371 * \sa SDL_TextInputActive
372 */
373extern SDL_DECLSPEC int SDLCALL SDL_StartTextInput(SDL_Window *window);
374
375/**
376 * Check whether or not Unicode text input events are enabled for a window.
377 *
378 * \param window the window to check.
379 * \returns SDL_TRUE if text input events are enabled else SDL_FALSE.
380 *
381 * \since This function is available since SDL 3.0.0.
382 *
383 * \sa SDL_StartTextInput
384 */
385extern SDL_DECLSPEC SDL_bool SDLCALL SDL_TextInputActive(SDL_Window *window);
386
387/**
388 * Stop receiving any text input events in a window.
389 *
390 * If SDL_StartTextInput() showed the screen keyboard, this function will hide
391 * it.
392 *
393 * \param window the window to disable text input.
394 * \returns 0 on success or a negative error code on failure; call
395 * SDL_GetError() for more information.
396 *
397 * \since This function is available since SDL 3.0.0.
398 *
399 * \sa SDL_StartTextInput
400 */
401extern SDL_DECLSPEC int SDLCALL SDL_StopTextInput(SDL_Window *window);
402
403/**
404 * Dismiss the composition window/IME without disabling the subsystem.
405 *
406 * \param window the window to affect.
407 * \returns 0 on success or a negative error code on failure; call
408 * SDL_GetError() for more information.
409 *
410 * \since This function is available since SDL 3.0.0.
411 *
412 * \sa SDL_StartTextInput
413 * \sa SDL_StopTextInput
414 */
415extern SDL_DECLSPEC int SDLCALL SDL_ClearComposition(SDL_Window *window);
416
417/**
418 * Set the area used to type Unicode text input.
419 *
420 * Native input methods may place a window with word suggestions near the
421 * cursor, without covering the text being entered.
422 *
423 * \param window the window for which to set the text input area.
424 * \param rect the SDL_Rect representing the text input area, in window
425 * coordinates, or NULL to clear it.
426 * \param cursor the offset of the current cursor location relative to
427 * `rect->x`, in window coordinates.
428 * \returns 0 on success or a negative error code on failure; call
429 * SDL_GetError() for more information.
430 *
431 * \since This function is available since SDL 3.0.0.
432 *
433 * \sa SDL_GetTextInputArea
434 * \sa SDL_StartTextInput
435 */
436extern SDL_DECLSPEC int SDLCALL SDL_SetTextInputArea(SDL_Window *window, const SDL_Rect *rect, int cursor);
437
438/**
439 * Get the area used to type Unicode text input.
440 *
441 * This returns the values previously set by SDL_SetTextInputArea().
442 *
443 * \param window the window for which to query the text input area.
444 * \param rect a pointer to an SDL_Rect filled in with the text input area,
445 * may be NULL.
446 * \param cursor a pointer to the offset of the current cursor location
447 * relative to `rect->x`, may be NULL.
448 * \returns 0 on success or a negative error code on failure; call
449 * SDL_GetError() for more information.
450 *
451 * \since This function is available since SDL 3.0.0.
452 *
453 * \sa SDL_SetTextInputArea
454 */
455extern SDL_DECLSPEC int SDLCALL SDL_GetTextInputArea(SDL_Window *window, SDL_Rect *rect, int *cursor);
456
457/**
458 * Check whether the platform has screen keyboard support.
459 *
460 * \returns SDL_TRUE if the platform has some screen keyboard support or
461 * SDL_FALSE if not.
462 *
463 * \since This function is available since SDL 3.0.0.
464 *
465 * \sa SDL_StartTextInput
466 * \sa SDL_ScreenKeyboardShown
467 */
468extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasScreenKeyboardSupport(void);
469
470/**
471 * Check whether the screen keyboard is shown for given window.
472 *
473 * \param window the window for which screen keyboard should be queried.
474 * \returns SDL_TRUE if screen keyboard is shown or SDL_FALSE if not.
475 *
476 * \since This function is available since SDL 3.0.0.
477 *
478 * \sa SDL_HasScreenKeyboardSupport
479 */
480extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ScreenKeyboardShown(SDL_Window *window);
481
482/* Ends C function definitions when using C++ */
483#ifdef __cplusplus
484}
485#endif
486#include <SDL3/SDL_close_code.h>
487
488#endif /* SDL_keyboard_h_ */
SDL_Scancode SDL_GetScancodeFromName(const char *name)
SDL_bool SDL_HasScreenKeyboardSupport(void)
int SDL_SetScancodeName(SDL_Scancode scancode, const char *name)
SDL_bool SDL_ScreenKeyboardShown(SDL_Window *window)
int SDL_GetTextInputArea(SDL_Window *window, SDL_Rect *rect, int *cursor)
SDL_Keymod SDL_GetModState(void)
SDL_Scancode SDL_GetScancodeFromKey(SDL_Keycode key, SDL_Keymod *modstate)
Uint32 SDL_KeyboardID
const char * SDL_GetKeyboardNameForID(SDL_KeyboardID instance_id)
int SDL_ClearComposition(SDL_Window *window)
SDL_bool SDL_HasKeyboard(void)
SDL_Keycode SDL_GetKeyFromScancode(SDL_Scancode scancode, SDL_Keymod modstate)
int SDL_SetTextInputArea(SDL_Window *window, const SDL_Rect *rect, int cursor)
void SDL_ResetKeyboard(void)
SDL_Scancode SDL_GetDefaultScancodeFromKey(SDL_Keycode key, SDL_Keymod *modstate)
SDL_Window * SDL_GetKeyboardFocus(void)
SDL_bool SDL_TextInputActive(SDL_Window *window)
SDL_Keycode SDL_GetDefaultKeyFromScancode(SDL_Scancode scancode, SDL_Keymod modstate)
int SDL_StartTextInput(SDL_Window *window)
const Uint8 * SDL_GetKeyboardState(int *numkeys)
void SDL_SetModState(SDL_Keymod modstate)
const char * SDL_GetKeyName(SDL_Keycode key)
int SDL_StopTextInput(SDL_Window *window)
SDL_Keycode SDL_GetKeyFromName(const char *name)
SDL_KeyboardID * SDL_GetKeyboards(int *count)
const char * SDL_GetScancodeName(SDL_Scancode scancode)
Uint16 SDL_Keymod
Uint32 SDL_Keycode
Definition SDL_keycode.h:47
SDL_Scancode
uint8_t Uint8
Definition SDL_stdinc.h:229
int SDL_bool
Definition SDL_stdinc.h:213
uint32_t Uint32
Definition SDL_stdinc.h:265
struct SDL_Window SDL_Window
Definition SDL_video.h:127