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