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