SDL  2.0
SDL_keyboard.h
Go to the documentation of this file.
1 /*
2  Simple DirectMedia Layer
3  Copyright (C) 1997-2021 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 "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  * \brief The SDL keysym structure, used in key events.
44  *
45  * \note If you are looking for translated character input, see the ::SDL_TEXTINPUT event.
46  */
47 typedef struct SDL_Keysym
48 {
49  SDL_Scancode scancode; /**< SDL physical key code - see ::SDL_Scancode for details */
50  SDL_Keycode sym; /**< SDL virtual key code - see ::SDL_Keycode for details */
51  Uint16 mod; /**< current key modifiers */
53 } SDL_Keysym;
54 
55 /* Function prototypes */
56 
57 /**
58  * Query the window which currently has keyboard focus.
59  *
60  * \returns the window with keyboard focus.
61  */
62 extern DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void);
63 
64 /**
65  * Get a snapshot of the current state of the keyboard.
66  *
67  * The pointer returned is a pointer to an internal SDL array. It will be
68  * valid for the whole lifetime of the application and should not be freed by
69  * the caller.
70  *
71  * A array element with a value of 1 means that the key is pressed and a value
72  * of 0 means that it is not. Indexes into this array are obtained by using
73  * SDL_Scancode values.
74  *
75  * Use SDL_PumpEvents() to update the state array.
76  *
77  * This function gives you the current state after all events have been
78  * processed, so if a key or button has been pressed and released before you
79  * process events, then the pressed state will never show up in the
80  * SDL_GetKeyboardState() calls.
81  *
82  * Note: This function doesn't take into account whether shift has been
83  * pressed or not.
84  *
85  * \param numkeys if non-NULL, receives the length of the returned array
86  * \returns a pointer to an array of key states.
87  *
88  * \sa SDL_PumpEvents
89  */
90 extern DECLSPEC const Uint8 *SDLCALL SDL_GetKeyboardState(int *numkeys);
91 
92 /**
93  * Get the current key modifier state for the keyboard.
94  *
95  * \returns an OR'd combination of the modifier keys for the keyboard. See
96  * SDL_Keymod for details.
97  *
98  * \sa SDL_GetKeyboardState
99  * \sa SDL_SetModState
100  */
101 extern DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void);
102 
103 /**
104  * Set the current key modifier state for the keyboard.
105  *
106  * The inverse of SDL_GetModState(), SDL_SetModState() allows you to impose
107  * modifier key states on your application. Simply pass your desired modifier
108  * states into `modstate`. This value may be a bitwise, OR'd combination of
109  * SDL_Keymod values.
110  *
111  * This does not change the keyboard state, only the key modifier flags that
112  * SDL reports.
113  *
114  * \param modstate the desired SDL_Keymod for the keyboard
115  *
116  * \sa SDL_GetModState
117  */
118 extern DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate);
119 
120 /**
121  * Get the key code corresponding to the given scancode according to the
122  * current keyboard layout.
123  *
124  * See SDL_Keycode for details.
125  *
126  * \param scancode the desired SDL_Scancode to query
127  * \returns the SDL_Keycode that corresponds to the given SDL_Scancode.
128  *
129  * \sa SDL_GetKeyName
130  * \sa SDL_GetScancodeFromKey
131  */
133 
134 /**
135  * Get the scancode corresponding to the given key code according to the
136  * current keyboard layout.
137  *
138  * See SDL_Scancode for details.
139  *
140  * \param key the desired SDL_Keycode to query
141  * \returns the SDL_Scancode that corresponds to the given SDL_Keycode.
142  *
143  * \sa SDL_GetKeyFromScancode
144  * \sa SDL_GetScancodeName
145  */
146 extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromKey(SDL_Keycode key);
147 
148 /**
149  * Get a human-readable name for a scancode.
150  *
151  * See SDL_Scancode for details.
152  *
153  * **Warning**: The returned name is by design not stable across platforms,
154  * e.g. the name for `SDL_SCANCODE_LGUI` is "Left GUI" under Linux but "Left
155  * Windows" under Microsoft Windows, and some scancodes like
156  * `SDL_SCANCODE_NONUSBACKSLASH` don't have any name at all. There are even
157  * scancodes that share names, e.g. `SDL_SCANCODE_RETURN` and
158  * `SDL_SCANCODE_RETURN2` (both called "Return"). This function is therefore
159  * unsuitable for creating a stable cross-platform two-way mapping between
160  * strings and scancodes.
161  *
162  * \param scancode the desired SDL_Scancode to query
163  * \returns a pointer to the name for the scancode. If the scancode doesn't
164  * have a name this function returns an empty string ("").
165  *
166  * \since This function is available since SDL 2.0.0.
167  *
168  * \sa SDL_GetScancodeFromKey
169  * \sa SDL_GetScancodeFromName
170  */
171 extern DECLSPEC const char *SDLCALL SDL_GetScancodeName(SDL_Scancode scancode);
172 
173 /**
174  * Get a scancode from a human-readable name.
175  *
176  * \param name the human-readable scancode name
177  * \returns the SDL_Scancode, or `SDL_SCANCODE_UNKNOWN` if the name wasn't
178  * recognized; call SDL_GetError() for more information.
179  *
180  * \since This function is available since SDL 2.0.0.
181  *
182  * \sa SDL_GetKeyFromName
183  * \sa SDL_GetScancodeFromKey
184  * \sa SDL_GetScancodeName
185  */
186 extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *name);
187 
188 /**
189  * Get a human-readable name for a key.
190  *
191  * See SDL_Scancode and SDL_Keycode for details.
192  *
193  * \param key the desired SDL_Keycode to query
194  * \returns a pointer to a UTF-8 string that stays valid at least until the
195  * next call to this function. If you need it around any longer, you
196  * must copy it. If the key doesn't have a name, this function
197  * returns an empty string ("").
198  *
199  * \sa SDL_GetKeyFromName
200  * \sa SDL_GetKeyFromScancode
201  * \sa SDL_GetScancodeFromKey
202  */
203 extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDL_Keycode key);
204 
205 /**
206  * Get a key code from a human-readable name.
207  *
208  * \param name the human-readable key name
209  * \returns key code, or `SDLK_UNKNOWN` if the name wasn't recognized; call
210  * SDL_GetError() for more information.
211  *
212  * \sa SDL_GetKeyFromScancode
213  * \sa SDL_GetKeyName
214  * \sa SDL_GetScancodeFromName
215  */
216 extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromName(const char *name);
217 
218 /**
219  * Start accepting Unicode text input events.
220  *
221  * This function will start accepting Unicode text input events in the focused
222  * SDL window, and start emitting SDL_TextInputEvent (SDL_TEXTINPUT) and
223  * SDL_TextEditingEvent (SDL_TEXTEDITING) events. Please use this function in
224  * pair with SDL_StopTextInput().
225  *
226  * On some platforms using this function activates the screen keyboard.
227  *
228  * \sa SDL_SetTextInputRect
229  * \sa SDL_StopTextInput
230  */
231 extern DECLSPEC void SDLCALL SDL_StartTextInput(void);
232 
233 /**
234  * Check whether or not Unicode text input events are enabled.
235  *
236  * \returns SDL_TRUE if text input events are enabled else SDL_FALSE.
237  *
238  * \since This function is available since SDL 2.0.0.
239  *
240  * \sa SDL_StartTextInput
241  */
242 extern DECLSPEC SDL_bool SDLCALL SDL_IsTextInputActive(void);
243 
244 /**
245  * Stop receiving any text input events.
246  *
247  * \sa SDL_StartTextInput
248  */
249 extern DECLSPEC void SDLCALL SDL_StopTextInput(void);
250 
251 /**
252  * Set the rectangle used to type Unicode text inputs.
253  *
254  * \param rect the SDL_Rect structure representing the rectangle to receive
255  * text (ignored if NULL)
256  *
257  * \sa SDL_StartTextInput
258  */
259 extern DECLSPEC void SDLCALL SDL_SetTextInputRect(SDL_Rect *rect);
260 
261 /**
262  * Check whether the platform has screen keyboard support.
263  *
264  * \returns SDL_TRUE if the platform has some screen keyboard support or
265  * SDL_FALSE if not.
266  *
267  * \since This function is available since SDL 2.0.0.
268  *
269  * \sa SDL_StartTextInput
270  * \sa SDL_IsScreenKeyboardShown
271  */
272 extern DECLSPEC SDL_bool SDLCALL SDL_HasScreenKeyboardSupport(void);
273 
274 /**
275  * Check whether the screen keyboard is shown for given window.
276  *
277  * \param window the window for which screen keyboard should be queried
278  * \returns SDL_TRUE if screen keyboard is shown or SDL_FALSE if not.
279  *
280  * \since This function is available since SDL 2.0.0.
281  *
282  * \sa SDL_HasScreenKeyboardSupport
283  */
284 extern DECLSPEC SDL_bool SDLCALL SDL_IsScreenKeyboardShown(SDL_Window *window);
285 
286 /* Ends C function definitions when using C++ */
287 #ifdef __cplusplus
288 }
289 #endif
290 #include "close_code.h"
291 
292 #endif /* SDL_keyboard_h_ */
293 
294 /* vi: set ts=4 sw=4 expandtab: */
SDL_Keycode SDL_GetKeyFromName(const char *name)
SDL_Scancode SDL_GetScancodeFromName(const char *name)
const char * SDL_GetKeyName(SDL_Keycode key)
SDL_bool
Definition: SDL_stdinc.h:167
Uint32 unused
Definition: SDL_keyboard.h:52
void SDL_SetModState(SDL_Keymod modstate)
SDL_Scancode scancode
Definition: SDL_keyboard.h:49
The SDL keysym structure, used in key events.
Definition: SDL_keyboard.h:47
uint32_t Uint32
Definition: SDL_stdinc.h:209
Sint32 SDL_Keycode
The SDL virtual key representation.
Definition: SDL_keycode.h:45
SDL_bool SDL_IsTextInputActive(void)
uint16_t Uint16
Definition: SDL_stdinc.h:197
SDL_Window * SDL_GetKeyboardFocus(void)
SDL_Keymod
Enumeration of valid key mods (possibly OR&#39;d together).
Definition: SDL_keycode.h:327
Uint16 mod
Definition: SDL_keyboard.h:51
struct SDL_Window SDL_Window
The type used to identify a window.
Definition: SDL_video.h:95
void SDL_StartTextInput(void)
SDL_bool SDL_HasScreenKeyboardSupport(void)
SDL_Keymod SDL_GetModState(void)
SDL_Keycode SDL_GetKeyFromScancode(SDL_Scancode scancode)
void SDL_StopTextInput(void)
SDL_Keycode sym
Definition: SDL_keyboard.h:50
const Uint8 * SDL_GetKeyboardState(int *numkeys)
void SDL_SetTextInputRect(SDL_Rect *rect)
uint8_t Uint8
Definition: SDL_stdinc.h:185
SDL_Scancode
The SDL keyboard scancode representation.
Definition: SDL_scancode.h:43
const char * SDL_GetScancodeName(SDL_Scancode scancode)
SDL_bool SDL_IsScreenKeyboardShown(SDL_Window *window)
SDL_Scancode SDL_GetScancodeFromKey(SDL_Keycode key)