|
1
|
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 * SDL keyboard management.
|
|
|
26 *
|
|
|
27 * Please refer to the Best Keyboard Practices document for details on how
|
|
|
28 * best to accept keyboard input in various types of programs:
|
|
|
29 *
|
|
|
30 * https://wiki.libsdl.org/SDL3/BestKeyboardPractices
|
|
|
31 */
|
|
|
32
|
|
|
33 #ifndef SDL_keyboard_h_
|
|
|
34 #define SDL_keyboard_h_
|
|
|
35
|
|
|
36 #include <SDL3/SDL_stdinc.h>
|
|
|
37 #include <SDL3/SDL_error.h>
|
|
|
38 #include <SDL3/SDL_keycode.h>
|
|
|
39 #include <SDL3/SDL_properties.h>
|
|
|
40 #include <SDL3/SDL_rect.h>
|
|
|
41 #include <SDL3/SDL_scancode.h>
|
|
|
42 #include <SDL3/SDL_video.h>
|
|
|
43
|
|
|
44 #include <SDL3/SDL_begin_code.h>
|
|
|
45 /* Set up for C function definitions, even when using C++ */
|
|
|
46 #ifdef __cplusplus
|
|
|
47 extern "C" {
|
|
|
48 #endif
|
|
|
49
|
|
|
50 /**
|
|
|
51 * This is a unique ID for a keyboard for the time it is connected to the
|
|
|
52 * system, and is never reused for the lifetime of the application.
|
|
|
53 *
|
|
|
54 * If the keyboard is disconnected and reconnected, it will get a new ID.
|
|
|
55 *
|
|
|
56 * The value 0 is an invalid ID.
|
|
|
57 *
|
|
|
58 * \since This datatype is available since SDL 3.2.0.
|
|
|
59 */
|
|
|
60 typedef Uint32 SDL_KeyboardID;
|
|
|
61
|
|
|
62 /* Function prototypes */
|
|
|
63
|
|
|
64 /**
|
|
|
65 * Return whether a keyboard is currently connected.
|
|
|
66 *
|
|
|
67 * \returns true if a keyboard is connected, false otherwise.
|
|
|
68 *
|
|
|
69 * \threadsafety This function should only be called on the main thread.
|
|
|
70 *
|
|
|
71 * \since This function is available since SDL 3.2.0.
|
|
|
72 *
|
|
|
73 * \sa SDL_GetKeyboards
|
|
|
74 */
|
|
|
75 extern SDL_DECLSPEC bool SDLCALL SDL_HasKeyboard(void);
|
|
|
76
|
|
|
77 /**
|
|
|
78 * Get a list of currently connected keyboards.
|
|
|
79 *
|
|
|
80 * Note that this will include any device or virtual driver that includes
|
|
|
81 * keyboard functionality, including some mice, KVM switches, motherboard
|
|
|
82 * power buttons, etc. You should wait for input from a device before you
|
|
|
83 * consider it actively in use.
|
|
|
84 *
|
|
|
85 * \param count a pointer filled in with the number of keyboards returned, may
|
|
|
86 * be NULL.
|
|
|
87 * \returns a 0 terminated array of keyboards instance IDs or NULL on failure;
|
|
|
88 * call SDL_GetError() for more information. This should be freed
|
|
|
89 * with SDL_free() when it is no longer needed.
|
|
|
90 *
|
|
|
91 * \threadsafety This function should only be called on the main thread.
|
|
|
92 *
|
|
|
93 * \since This function is available since SDL 3.2.0.
|
|
|
94 *
|
|
|
95 * \sa SDL_GetKeyboardNameForID
|
|
|
96 * \sa SDL_HasKeyboard
|
|
|
97 */
|
|
|
98 extern SDL_DECLSPEC SDL_KeyboardID * SDLCALL SDL_GetKeyboards(int *count);
|
|
|
99
|
|
|
100 /**
|
|
|
101 * Get the name of a keyboard.
|
|
|
102 *
|
|
|
103 * This function returns "" if the keyboard doesn't have a name.
|
|
|
104 *
|
|
|
105 * \param instance_id the keyboard instance ID.
|
|
|
106 * \returns the name of the selected keyboard or NULL on failure; call
|
|
|
107 * SDL_GetError() for more information.
|
|
|
108 *
|
|
|
109 * \threadsafety This function should only be called on the main thread.
|
|
|
110 *
|
|
|
111 * \since This function is available since SDL 3.2.0.
|
|
|
112 *
|
|
|
113 * \sa SDL_GetKeyboards
|
|
|
114 */
|
|
|
115 extern SDL_DECLSPEC const char * SDLCALL SDL_GetKeyboardNameForID(SDL_KeyboardID instance_id);
|
|
|
116
|
|
|
117 /**
|
|
|
118 * Query the window which currently has keyboard focus.
|
|
|
119 *
|
|
|
120 * \returns the window with keyboard focus.
|
|
|
121 *
|
|
|
122 * \threadsafety This function should only be called on the main thread.
|
|
|
123 *
|
|
|
124 * \since This function is available since SDL 3.2.0.
|
|
|
125 */
|
|
|
126 extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void);
|
|
|
127
|
|
|
128 /**
|
|
|
129 * Get a snapshot of the current state of the keyboard.
|
|
|
130 *
|
|
|
131 * The pointer returned is a pointer to an internal SDL array. It will be
|
|
|
132 * valid for the whole lifetime of the application and should not be freed by
|
|
|
133 * the caller.
|
|
|
134 *
|
|
|
135 * A array element with a value of true means that the key is pressed and a
|
|
|
136 * value of false means that it is not. Indexes into this array are obtained
|
|
|
137 * by using SDL_Scancode values.
|
|
|
138 *
|
|
|
139 * Use SDL_PumpEvents() to update the state array.
|
|
|
140 *
|
|
|
141 * This function gives you the current state after all events have been
|
|
|
142 * processed, so if a key or button has been pressed and released before you
|
|
|
143 * process events, then the pressed state will never show up in the
|
|
|
144 * SDL_GetKeyboardState() calls.
|
|
|
145 *
|
|
|
146 * Note: This function doesn't take into account whether shift has been
|
|
|
147 * pressed or not.
|
|
|
148 *
|
|
|
149 * \param numkeys if non-NULL, receives the length of the returned array.
|
|
|
150 * \returns a pointer to an array of key states.
|
|
|
151 *
|
|
|
152 * \threadsafety It is safe to call this function from any thread.
|
|
|
153 *
|
|
|
154 * \since This function is available since SDL 3.2.0.
|
|
|
155 *
|
|
|
156 * \sa SDL_PumpEvents
|
|
|
157 * \sa SDL_ResetKeyboard
|
|
|
158 */
|
|
|
159 extern SDL_DECLSPEC const bool * SDLCALL SDL_GetKeyboardState(int *numkeys);
|
|
|
160
|
|
|
161 /**
|
|
|
162 * Clear the state of the keyboard.
|
|
|
163 *
|
|
|
164 * This function will generate key up events for all pressed keys.
|
|
|
165 *
|
|
|
166 * \threadsafety This function should only be called on the main thread.
|
|
|
167 *
|
|
|
168 * \since This function is available since SDL 3.2.0.
|
|
|
169 *
|
|
|
170 * \sa SDL_GetKeyboardState
|
|
|
171 */
|
|
|
172 extern SDL_DECLSPEC void SDLCALL SDL_ResetKeyboard(void);
|
|
|
173
|
|
|
174 /**
|
|
|
175 * Get the current key modifier state for the keyboard.
|
|
|
176 *
|
|
|
177 * \returns an OR'd combination of the modifier keys for the keyboard.
|
|
|
178 *
|
|
|
179 * \threadsafety It is safe to call this function from any thread.
|
|
|
180 *
|
|
|
181 * \since This function is available since SDL 3.2.0.
|
|
|
182 *
|
|
|
183 * \sa SDL_GetKeyboardState
|
|
|
184 * \sa SDL_SetModState
|
|
|
185 */
|
|
|
186 extern SDL_DECLSPEC SDL_Keymod SDLCALL SDL_GetModState(void);
|
|
|
187
|
|
|
188 /**
|
|
|
189 * Set the current key modifier state for the keyboard.
|
|
|
190 *
|
|
|
191 * The inverse of SDL_GetModState(), SDL_SetModState() allows you to impose
|
|
|
192 * modifier key states on your application. Simply pass your desired modifier
|
|
|
193 * states into `modstate`. This value may be a bitwise, OR'd combination of
|
|
|
194 * SDL_Keymod values.
|
|
|
195 *
|
|
|
196 * This does not change the keyboard state, only the key modifier flags that
|
|
|
197 * SDL reports.
|
|
|
198 *
|
|
|
199 * \param modstate the desired SDL_Keymod for the keyboard.
|
|
|
200 *
|
|
|
201 * \threadsafety It is safe to call this function from any thread.
|
|
|
202 *
|
|
|
203 * \since This function is available since SDL 3.2.0.
|
|
|
204 *
|
|
|
205 * \sa SDL_GetModState
|
|
|
206 */
|
|
|
207 extern SDL_DECLSPEC void SDLCALL SDL_SetModState(SDL_Keymod modstate);
|
|
|
208
|
|
|
209 /**
|
|
|
210 * Get the key code corresponding to the given scancode according to the
|
|
|
211 * current keyboard layout.
|
|
|
212 *
|
|
|
213 * If you want to get the keycode as it would be delivered in key events,
|
|
|
214 * including options specified in SDL_HINT_KEYCODE_OPTIONS, then you should
|
|
|
215 * pass `key_event` as true. Otherwise this function simply translates the
|
|
|
216 * scancode based on the given modifier state.
|
|
|
217 *
|
|
|
218 * \param scancode the desired SDL_Scancode to query.
|
|
|
219 * \param modstate the modifier state to use when translating the scancode to
|
|
|
220 * a keycode.
|
|
|
221 * \param key_event true if the keycode will be used in key events.
|
|
|
222 * \returns the SDL_Keycode that corresponds to the given SDL_Scancode.
|
|
|
223 *
|
|
|
224 * \threadsafety This function is not thread safe.
|
|
|
225 *
|
|
|
226 * \since This function is available since SDL 3.2.0.
|
|
|
227 *
|
|
|
228 * \sa SDL_GetKeyName
|
|
|
229 * \sa SDL_GetScancodeFromKey
|
|
|
230 */
|
|
|
231 extern SDL_DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode, SDL_Keymod modstate, bool key_event);
|
|
|
232
|
|
|
233 /**
|
|
|
234 * Get the scancode corresponding to the given key code according to the
|
|
|
235 * current keyboard layout.
|
|
|
236 *
|
|
|
237 * Note that there may be multiple scancode+modifier states that can generate
|
|
|
238 * this keycode, this will just return the first one found.
|
|
|
239 *
|
|
|
240 * \param key the desired SDL_Keycode to query.
|
|
|
241 * \param modstate a pointer to the modifier state that would be used when the
|
|
|
242 * scancode generates this key, may be NULL.
|
|
|
243 * \returns the SDL_Scancode that corresponds to the given SDL_Keycode.
|
|
|
244 *
|
|
|
245 * \threadsafety This function is not thread safe.
|
|
|
246 *
|
|
|
247 * \since This function is available since SDL 3.2.0.
|
|
|
248 *
|
|
|
249 * \sa SDL_GetKeyFromScancode
|
|
|
250 * \sa SDL_GetScancodeName
|
|
|
251 */
|
|
|
252 extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromKey(SDL_Keycode key, SDL_Keymod *modstate);
|
|
|
253
|
|
|
254 /**
|
|
|
255 * Set a human-readable name for a scancode.
|
|
|
256 *
|
|
|
257 * \param scancode the desired SDL_Scancode.
|
|
|
258 * \param name the name to use for the scancode, encoded as UTF-8. The string
|
|
|
259 * is not copied, so the pointer given to this function must stay
|
|
|
260 * valid while SDL is being used.
|
|
|
261 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
262 * information.
|
|
|
263 *
|
|
|
264 * \threadsafety This function is not thread safe.
|
|
|
265 *
|
|
|
266 * \since This function is available since SDL 3.2.0.
|
|
|
267 *
|
|
|
268 * \sa SDL_GetScancodeName
|
|
|
269 */
|
|
|
270 extern SDL_DECLSPEC bool SDLCALL SDL_SetScancodeName(SDL_Scancode scancode, const char *name);
|
|
|
271
|
|
|
272 /**
|
|
|
273 * Get a human-readable name for a scancode.
|
|
|
274 *
|
|
|
275 * **Warning**: The returned name is by design not stable across platforms,
|
|
|
276 * e.g. the name for `SDL_SCANCODE_LGUI` is "Left GUI" under Linux but "Left
|
|
|
277 * Windows" under Microsoft Windows, and some scancodes like
|
|
|
278 * `SDL_SCANCODE_NONUSBACKSLASH` don't have any name at all. There are even
|
|
|
279 * scancodes that share names, e.g. `SDL_SCANCODE_RETURN` and
|
|
|
280 * `SDL_SCANCODE_RETURN2` (both called "Return"). This function is therefore
|
|
|
281 * unsuitable for creating a stable cross-platform two-way mapping between
|
|
|
282 * strings and scancodes.
|
|
|
283 *
|
|
|
284 * \param scancode the desired SDL_Scancode to query.
|
|
|
285 * \returns a pointer to the name for the scancode. If the scancode doesn't
|
|
|
286 * have a name this function returns an empty string ("").
|
|
|
287 *
|
|
|
288 * \threadsafety This function is not thread safe.
|
|
|
289 *
|
|
|
290 * \since This function is available since SDL 3.2.0.
|
|
|
291 *
|
|
|
292 * \sa SDL_GetScancodeFromKey
|
|
|
293 * \sa SDL_GetScancodeFromName
|
|
|
294 * \sa SDL_SetScancodeName
|
|
|
295 */
|
|
|
296 extern SDL_DECLSPEC const char * SDLCALL SDL_GetScancodeName(SDL_Scancode scancode);
|
|
|
297
|
|
|
298 /**
|
|
|
299 * Get a scancode from a human-readable name.
|
|
|
300 *
|
|
|
301 * \param name the human-readable scancode name.
|
|
|
302 * \returns the SDL_Scancode, or `SDL_SCANCODE_UNKNOWN` if the name wasn't
|
|
|
303 * recognized; call SDL_GetError() for more information.
|
|
|
304 *
|
|
|
305 * \threadsafety This function is not thread safe.
|
|
|
306 *
|
|
|
307 * \since This function is available since SDL 3.2.0.
|
|
|
308 *
|
|
|
309 * \sa SDL_GetKeyFromName
|
|
|
310 * \sa SDL_GetScancodeFromKey
|
|
|
311 * \sa SDL_GetScancodeName
|
|
|
312 */
|
|
|
313 extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *name);
|
|
|
314
|
|
|
315 /**
|
|
|
316 * Get a human-readable name for a key.
|
|
|
317 *
|
|
|
318 * If the key doesn't have a name, this function returns an empty string ("").
|
|
|
319 *
|
|
|
320 * Letters will be presented in their uppercase form, if applicable.
|
|
|
321 *
|
|
|
322 * \param key the desired SDL_Keycode to query.
|
|
|
323 * \returns a UTF-8 encoded string of the key name.
|
|
|
324 *
|
|
|
325 * \threadsafety This function is not thread safe.
|
|
|
326 *
|
|
|
327 * \since This function is available since SDL 3.2.0.
|
|
|
328 *
|
|
|
329 * \sa SDL_GetKeyFromName
|
|
|
330 * \sa SDL_GetKeyFromScancode
|
|
|
331 * \sa SDL_GetScancodeFromKey
|
|
|
332 */
|
|
|
333 extern SDL_DECLSPEC const char * SDLCALL SDL_GetKeyName(SDL_Keycode key);
|
|
|
334
|
|
|
335 /**
|
|
|
336 * Get a key code from a human-readable name.
|
|
|
337 *
|
|
|
338 * \param name the human-readable key name.
|
|
|
339 * \returns key code, or `SDLK_UNKNOWN` if the name wasn't recognized; call
|
|
|
340 * SDL_GetError() for more information.
|
|
|
341 *
|
|
|
342 * \threadsafety This function is not thread safe.
|
|
|
343 *
|
|
|
344 * \since This function is available since SDL 3.2.0.
|
|
|
345 *
|
|
|
346 * \sa SDL_GetKeyFromScancode
|
|
|
347 * \sa SDL_GetKeyName
|
|
|
348 * \sa SDL_GetScancodeFromName
|
|
|
349 */
|
|
|
350 extern 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 and/or
|
|
|
362 * activates an IME, which can prevent some key press events from being passed
|
|
|
363 * through.
|
|
|
364 *
|
|
|
365 * \param window the window to enable text input.
|
|
|
366 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
367 * information.
|
|
|
368 *
|
|
|
369 * \threadsafety This function should only be called on the main thread.
|
|
|
370 *
|
|
|
371 * \since This function is available since SDL 3.2.0.
|
|
|
372 *
|
|
|
373 * \sa SDL_SetTextInputArea
|
|
|
374 * \sa SDL_StartTextInputWithProperties
|
|
|
375 * \sa SDL_StopTextInput
|
|
|
376 * \sa SDL_TextInputActive
|
|
|
377 */
|
|
|
378 extern SDL_DECLSPEC bool SDLCALL SDL_StartTextInput(SDL_Window *window);
|
|
|
379
|
|
|
380 /**
|
|
|
381 * Text input type.
|
|
|
382 *
|
|
|
383 * These are the valid values for SDL_PROP_TEXTINPUT_TYPE_NUMBER. Not every
|
|
|
384 * value is valid on every platform, but where a value isn't supported, a
|
|
|
385 * reasonable fallback will be used.
|
|
|
386 *
|
|
|
387 * \since This enum is available since SDL 3.2.0.
|
|
|
388 *
|
|
|
389 * \sa SDL_StartTextInputWithProperties
|
|
|
390 */
|
|
|
391 typedef enum SDL_TextInputType
|
|
|
392 {
|
|
|
393 SDL_TEXTINPUT_TYPE_TEXT, /**< The input is text */
|
|
|
394 SDL_TEXTINPUT_TYPE_TEXT_NAME, /**< The input is a person's name */
|
|
|
395 SDL_TEXTINPUT_TYPE_TEXT_EMAIL, /**< The input is an e-mail address */
|
|
|
396 SDL_TEXTINPUT_TYPE_TEXT_USERNAME, /**< The input is a username */
|
|
|
397 SDL_TEXTINPUT_TYPE_TEXT_PASSWORD_HIDDEN, /**< The input is a secure password that is hidden */
|
|
|
398 SDL_TEXTINPUT_TYPE_TEXT_PASSWORD_VISIBLE, /**< The input is a secure password that is visible */
|
|
|
399 SDL_TEXTINPUT_TYPE_NUMBER, /**< The input is a number */
|
|
|
400 SDL_TEXTINPUT_TYPE_NUMBER_PASSWORD_HIDDEN, /**< The input is a secure PIN that is hidden */
|
|
|
401 SDL_TEXTINPUT_TYPE_NUMBER_PASSWORD_VISIBLE /**< The input is a secure PIN that is visible */
|
|
|
402 } SDL_TextInputType;
|
|
|
403
|
|
|
404 /**
|
|
|
405 * Auto capitalization type.
|
|
|
406 *
|
|
|
407 * These are the valid values for SDL_PROP_TEXTINPUT_CAPITALIZATION_NUMBER.
|
|
|
408 * Not every value is valid on every platform, but where a value isn't
|
|
|
409 * supported, a reasonable fallback will be used.
|
|
|
410 *
|
|
|
411 * \since This enum is available since SDL 3.2.0.
|
|
|
412 *
|
|
|
413 * \sa SDL_StartTextInputWithProperties
|
|
|
414 */
|
|
|
415 typedef enum SDL_Capitalization
|
|
|
416 {
|
|
|
417 SDL_CAPITALIZE_NONE, /**< No auto-capitalization will be done */
|
|
|
418 SDL_CAPITALIZE_SENTENCES, /**< The first letter of sentences will be capitalized */
|
|
|
419 SDL_CAPITALIZE_WORDS, /**< The first letter of words will be capitalized */
|
|
|
420 SDL_CAPITALIZE_LETTERS /**< All letters will be capitalized */
|
|
|
421 } SDL_Capitalization;
|
|
|
422
|
|
|
423 /**
|
|
|
424 * Start accepting Unicode text input events in a window, with properties
|
|
|
425 * describing the input.
|
|
|
426 *
|
|
|
427 * This function will enable text input (SDL_EVENT_TEXT_INPUT and
|
|
|
428 * SDL_EVENT_TEXT_EDITING events) in the specified window. Please use this
|
|
|
429 * function paired with SDL_StopTextInput().
|
|
|
430 *
|
|
|
431 * Text input events are not received by default.
|
|
|
432 *
|
|
|
433 * On some platforms using this function shows the screen keyboard and/or
|
|
|
434 * activates an IME, which can prevent some key press events from being passed
|
|
|
435 * through.
|
|
|
436 *
|
|
|
437 * These are the supported properties:
|
|
|
438 *
|
|
|
439 * - `SDL_PROP_TEXTINPUT_TYPE_NUMBER` - an SDL_TextInputType value that
|
|
|
440 * describes text being input, defaults to SDL_TEXTINPUT_TYPE_TEXT.
|
|
|
441 * - `SDL_PROP_TEXTINPUT_CAPITALIZATION_NUMBER` - an SDL_Capitalization value
|
|
|
442 * that describes how text should be capitalized, defaults to
|
|
|
443 * SDL_CAPITALIZE_SENTENCES for normal text entry, SDL_CAPITALIZE_WORDS for
|
|
|
444 * SDL_TEXTINPUT_TYPE_TEXT_NAME, and SDL_CAPITALIZE_NONE for e-mail
|
|
|
445 * addresses, usernames, and passwords.
|
|
|
446 * - `SDL_PROP_TEXTINPUT_AUTOCORRECT_BOOLEAN` - true to enable auto completion
|
|
|
447 * and auto correction, defaults to true.
|
|
|
448 * - `SDL_PROP_TEXTINPUT_MULTILINE_BOOLEAN` - true if multiple lines of text
|
|
|
449 * are allowed. This defaults to true if SDL_HINT_RETURN_KEY_HIDES_IME is
|
|
|
450 * "0" or is not set, and defaults to false if SDL_HINT_RETURN_KEY_HIDES_IME
|
|
|
451 * is "1".
|
|
|
452 *
|
|
|
453 * On Android you can directly specify the input type:
|
|
|
454 *
|
|
|
455 * - `SDL_PROP_TEXTINPUT_ANDROID_INPUTTYPE_NUMBER` - the text input type to
|
|
|
456 * use, overriding other properties. This is documented at
|
|
|
457 * https://developer.android.com/reference/android/text/InputType
|
|
|
458 *
|
|
|
459 * \param window the window to enable text input.
|
|
|
460 * \param props the properties to use.
|
|
|
461 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
462 * information.
|
|
|
463 *
|
|
|
464 * \threadsafety This function should only be called on the main thread.
|
|
|
465 *
|
|
|
466 * \since This function is available since SDL 3.2.0.
|
|
|
467 *
|
|
|
468 * \sa SDL_SetTextInputArea
|
|
|
469 * \sa SDL_StartTextInput
|
|
|
470 * \sa SDL_StopTextInput
|
|
|
471 * \sa SDL_TextInputActive
|
|
|
472 */
|
|
|
473 extern SDL_DECLSPEC bool SDLCALL SDL_StartTextInputWithProperties(SDL_Window *window, SDL_PropertiesID props);
|
|
|
474
|
|
|
475 #define SDL_PROP_TEXTINPUT_TYPE_NUMBER "SDL.textinput.type"
|
|
|
476 #define SDL_PROP_TEXTINPUT_CAPITALIZATION_NUMBER "SDL.textinput.capitalization"
|
|
|
477 #define SDL_PROP_TEXTINPUT_AUTOCORRECT_BOOLEAN "SDL.textinput.autocorrect"
|
|
|
478 #define SDL_PROP_TEXTINPUT_MULTILINE_BOOLEAN "SDL.textinput.multiline"
|
|
|
479 #define SDL_PROP_TEXTINPUT_ANDROID_INPUTTYPE_NUMBER "SDL.textinput.android.inputtype"
|
|
|
480
|
|
|
481 /**
|
|
|
482 * Check whether or not Unicode text input events are enabled for a window.
|
|
|
483 *
|
|
|
484 * \param window the window to check.
|
|
|
485 * \returns true if text input events are enabled else false.
|
|
|
486 *
|
|
|
487 * \threadsafety This function should only be called on the main thread.
|
|
|
488 *
|
|
|
489 * \since This function is available since SDL 3.2.0.
|
|
|
490 *
|
|
|
491 * \sa SDL_StartTextInput
|
|
|
492 */
|
|
|
493 extern SDL_DECLSPEC bool SDLCALL SDL_TextInputActive(SDL_Window *window);
|
|
|
494
|
|
|
495 /**
|
|
|
496 * Stop receiving any text input events in a window.
|
|
|
497 *
|
|
|
498 * If SDL_StartTextInput() showed the screen keyboard, this function will hide
|
|
|
499 * it.
|
|
|
500 *
|
|
|
501 * \param window the window to disable text input.
|
|
|
502 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
503 * information.
|
|
|
504 *
|
|
|
505 * \threadsafety This function should only be called on the main thread.
|
|
|
506 *
|
|
|
507 * \since This function is available since SDL 3.2.0.
|
|
|
508 *
|
|
|
509 * \sa SDL_StartTextInput
|
|
|
510 */
|
|
|
511 extern SDL_DECLSPEC bool SDLCALL SDL_StopTextInput(SDL_Window *window);
|
|
|
512
|
|
|
513 /**
|
|
|
514 * Dismiss the composition window/IME without disabling the subsystem.
|
|
|
515 *
|
|
|
516 * \param window the window to affect.
|
|
|
517 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
518 * information.
|
|
|
519 *
|
|
|
520 * \threadsafety This function should only be called on the main thread.
|
|
|
521 *
|
|
|
522 * \since This function is available since SDL 3.2.0.
|
|
|
523 *
|
|
|
524 * \sa SDL_StartTextInput
|
|
|
525 * \sa SDL_StopTextInput
|
|
|
526 */
|
|
|
527 extern SDL_DECLSPEC bool SDLCALL SDL_ClearComposition(SDL_Window *window);
|
|
|
528
|
|
|
529 /**
|
|
|
530 * Set the area used to type Unicode text input.
|
|
|
531 *
|
|
|
532 * Native input methods may place a window with word suggestions near the
|
|
|
533 * cursor, without covering the text being entered.
|
|
|
534 *
|
|
|
535 * \param window the window for which to set the text input area.
|
|
|
536 * \param rect the SDL_Rect representing the text input area, in window
|
|
|
537 * coordinates, or NULL to clear it.
|
|
|
538 * \param cursor the offset of the current cursor location relative to
|
|
|
539 * `rect->x`, in window coordinates.
|
|
|
540 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
541 * information.
|
|
|
542 *
|
|
|
543 * \threadsafety This function should only be called on the main thread.
|
|
|
544 *
|
|
|
545 * \since This function is available since SDL 3.2.0.
|
|
|
546 *
|
|
|
547 * \sa SDL_GetTextInputArea
|
|
|
548 * \sa SDL_StartTextInput
|
|
|
549 */
|
|
|
550 extern SDL_DECLSPEC bool SDLCALL SDL_SetTextInputArea(SDL_Window *window, const SDL_Rect *rect, int cursor);
|
|
|
551
|
|
|
552 /**
|
|
|
553 * Get the area used to type Unicode text input.
|
|
|
554 *
|
|
|
555 * This returns the values previously set by SDL_SetTextInputArea().
|
|
|
556 *
|
|
|
557 * \param window the window for which to query the text input area.
|
|
|
558 * \param rect a pointer to an SDL_Rect filled in with the text input area,
|
|
|
559 * may be NULL.
|
|
|
560 * \param cursor a pointer to the offset of the current cursor location
|
|
|
561 * relative to `rect->x`, may be NULL.
|
|
|
562 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
563 * information.
|
|
|
564 *
|
|
|
565 * \threadsafety This function should only be called on the main thread.
|
|
|
566 *
|
|
|
567 * \since This function is available since SDL 3.2.0.
|
|
|
568 *
|
|
|
569 * \sa SDL_SetTextInputArea
|
|
|
570 */
|
|
|
571 extern SDL_DECLSPEC bool SDLCALL SDL_GetTextInputArea(SDL_Window *window, SDL_Rect *rect, int *cursor);
|
|
|
572
|
|
|
573 /**
|
|
|
574 * Check whether the platform has screen keyboard support.
|
|
|
575 *
|
|
|
576 * \returns true if the platform has some screen keyboard support or false if
|
|
|
577 * not.
|
|
|
578 *
|
|
|
579 * \threadsafety This function should only be called on the main thread.
|
|
|
580 *
|
|
|
581 * \since This function is available since SDL 3.2.0.
|
|
|
582 *
|
|
|
583 * \sa SDL_StartTextInput
|
|
|
584 * \sa SDL_ScreenKeyboardShown
|
|
|
585 */
|
|
|
586 extern SDL_DECLSPEC bool SDLCALL SDL_HasScreenKeyboardSupport(void);
|
|
|
587
|
|
|
588 /**
|
|
|
589 * Check whether the screen keyboard is shown for given window.
|
|
|
590 *
|
|
|
591 * \param window the window for which screen keyboard should be queried.
|
|
|
592 * \returns true if screen keyboard is shown or false if not.
|
|
|
593 *
|
|
|
594 * \threadsafety This function should only be called on the main thread.
|
|
|
595 *
|
|
|
596 * \since This function is available since SDL 3.2.0.
|
|
|
597 *
|
|
|
598 * \sa SDL_HasScreenKeyboardSupport
|
|
|
599 */
|
|
|
600 extern SDL_DECLSPEC bool SDLCALL SDL_ScreenKeyboardShown(SDL_Window *window);
|
|
|
601
|
|
|
602 /* Ends C function definitions when using C++ */
|
|
|
603 #ifdef __cplusplus
|
|
|
604 }
|
|
|
605 #endif
|
|
|
606 #include <SDL3/SDL_close_code.h>
|
|
|
607
|
|
|
608 #endif /* SDL_keyboard_h_ */
|
