sdl3_sys/generated/
keyboard.rs

1//! SDL keyboard management.
2//!
3//! Please refer to the Best Keyboard Practices document for details on how
4//! best to accept keyboard input in various types of programs:
5//!
6//! <https://wiki.libsdl.org/SDL3/BestKeyboardPractices>
7
8use super::stdinc::*;
9
10use super::error::*;
11
12use super::keycode::*;
13
14use super::properties::*;
15
16use super::rect::*;
17
18use super::scancode::*;
19
20use super::video::*;
21
22/// This is a unique ID for a keyboard for the time it is connected to the
23/// system, and is never reused for the lifetime of the application.
24///
25/// If the keyboard is disconnected and reconnected, it will get a new ID.
26///
27/// The value 0 is an invalid ID.
28///
29/// ## Availability
30/// This datatype is available since SDL 3.2.0.
31#[repr(transparent)]
32#[derive(Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
33#[cfg_attr(feature = "debug-impls", derive(Debug))]
34pub struct SDL_KeyboardID(pub Uint32);
35
36impl ::core::cmp::PartialEq<Uint32> for SDL_KeyboardID {
37    #[inline(always)]
38    fn eq(&self, other: &Uint32) -> bool {
39        &self.0 == other
40    }
41}
42
43impl ::core::cmp::PartialEq<SDL_KeyboardID> for Uint32 {
44    #[inline(always)]
45    fn eq(&self, other: &SDL_KeyboardID) -> bool {
46        self == &other.0
47    }
48}
49
50impl From<SDL_KeyboardID> for Uint32 {
51    #[inline(always)]
52    fn from(value: SDL_KeyboardID) -> Self {
53        value.0
54    }
55}
56
57#[cfg(feature = "metadata")]
58impl sdl3_sys::metadata::GroupMetadata for SDL_KeyboardID {
59    const GROUP_METADATA: &'static sdl3_sys::metadata::Group =
60        &crate::metadata::keyboard::METADATA_SDL_KeyboardID;
61}
62
63unsafe extern "C" {
64    /// Return whether a keyboard is currently connected.
65    ///
66    /// ## Return value
67    /// Returns true if a keyboard is connected, false otherwise.
68    ///
69    /// ## Thread safety
70    /// This function should only be called on the main thread.
71    ///
72    /// ## Availability
73    /// This function is available since SDL 3.2.0.
74    ///
75    /// ## See also
76    /// - [`SDL_GetKeyboards`]
77    pub fn SDL_HasKeyboard() -> ::core::primitive::bool;
78}
79
80unsafe extern "C" {
81    /// Get a list of currently connected keyboards.
82    ///
83    /// Note that this will include any device or virtual driver that includes
84    /// keyboard functionality, including some mice, KVM switches, motherboard
85    /// power buttons, etc. You should wait for input from a device before you
86    /// consider it actively in use.
87    ///
88    /// ## Parameters
89    /// - `count`: a pointer filled in with the number of keyboards returned, may
90    ///   be NULL.
91    ///
92    /// ## Return value
93    /// Returns a 0 terminated array of keyboards instance IDs or NULL on failure;
94    ///   call [`SDL_GetError()`] for more information. This should be freed
95    ///   with [`SDL_free()`] when it is no longer needed.
96    ///
97    /// ## Thread safety
98    /// This function should only be called on the main thread.
99    ///
100    /// ## Availability
101    /// This function is available since SDL 3.2.0.
102    ///
103    /// ## See also
104    /// - [`SDL_GetKeyboardNameForID`]
105    /// - [`SDL_HasKeyboard`]
106    pub fn SDL_GetKeyboards(count: *mut ::core::ffi::c_int) -> *mut SDL_KeyboardID;
107}
108
109unsafe extern "C" {
110    /// Get the name of a keyboard.
111    ///
112    /// This function returns "" if the keyboard doesn't have a name.
113    ///
114    /// ## Parameters
115    /// - `instance_id`: the keyboard instance ID.
116    ///
117    /// ## Return value
118    /// Returns the name of the selected keyboard or NULL on failure; call
119    ///   [`SDL_GetError()`] for more information.
120    ///
121    /// ## Thread safety
122    /// This function should only be called on the main thread.
123    ///
124    /// ## Availability
125    /// This function is available since SDL 3.2.0.
126    ///
127    /// ## See also
128    /// - [`SDL_GetKeyboards`]
129    pub fn SDL_GetKeyboardNameForID(instance_id: SDL_KeyboardID) -> *const ::core::ffi::c_char;
130}
131
132unsafe extern "C" {
133    /// Query the window which currently has keyboard focus.
134    ///
135    /// ## Return value
136    /// Returns the window with keyboard focus.
137    ///
138    /// ## Thread safety
139    /// This function should only be called on the main thread.
140    ///
141    /// ## Availability
142    /// This function is available since SDL 3.2.0.
143    pub fn SDL_GetKeyboardFocus() -> *mut SDL_Window;
144}
145
146unsafe extern "C" {
147    /// Get a snapshot of the current state of the keyboard.
148    ///
149    /// The pointer returned is a pointer to an internal SDL array. It will be
150    /// valid for the whole lifetime of the application and should not be freed by
151    /// the caller.
152    ///
153    /// A array element with a value of true means that the key is pressed and a
154    /// value of false means that it is not. Indexes into this array are obtained
155    /// by using [`SDL_Scancode`] values.
156    ///
157    /// Use [`SDL_PumpEvents()`] to update the state array.
158    ///
159    /// This function gives you the current state after all events have been
160    /// processed, so if a key or button has been pressed and released before you
161    /// process events, then the pressed state will never show up in the
162    /// [`SDL_GetKeyboardState()`] calls.
163    ///
164    /// Note: This function doesn't take into account whether shift has been
165    /// pressed or not.
166    ///
167    /// ## Parameters
168    /// - `numkeys`: if non-NULL, receives the length of the returned array.
169    ///
170    /// ## Return value
171    /// Returns a pointer to an array of key states.
172    ///
173    /// ## Thread safety
174    /// It is safe to call this function from any thread.
175    ///
176    /// ## Availability
177    /// This function is available since SDL 3.2.0.
178    ///
179    /// ## See also
180    /// - [`SDL_PumpEvents`]
181    /// - [`SDL_ResetKeyboard`]
182    pub fn SDL_GetKeyboardState(numkeys: *mut ::core::ffi::c_int)
183    -> *const ::core::primitive::bool;
184}
185
186unsafe extern "C" {
187    /// Clear the state of the keyboard.
188    ///
189    /// This function will generate key up events for all pressed keys.
190    ///
191    /// ## Thread safety
192    /// This function should only be called on the main thread.
193    ///
194    /// ## Availability
195    /// This function is available since SDL 3.2.0.
196    ///
197    /// ## See also
198    /// - [`SDL_GetKeyboardState`]
199    pub fn SDL_ResetKeyboard();
200}
201
202unsafe extern "C" {
203    /// Get the current key modifier state for the keyboard.
204    ///
205    /// ## Return value
206    /// Returns an OR'd combination of the modifier keys for the keyboard.
207    ///
208    /// ## Thread safety
209    /// It is safe to call this function from any thread.
210    ///
211    /// ## Availability
212    /// This function is available since SDL 3.2.0.
213    ///
214    /// ## See also
215    /// - [`SDL_GetKeyboardState`]
216    /// - [`SDL_SetModState`]
217    pub fn SDL_GetModState() -> SDL_Keymod;
218}
219
220unsafe extern "C" {
221    /// Set the current key modifier state for the keyboard.
222    ///
223    /// The inverse of [`SDL_GetModState()`], [`SDL_SetModState()`] allows you to impose
224    /// modifier key states on your application. Simply pass your desired modifier
225    /// states into `modstate`. This value may be a bitwise, OR'd combination of
226    /// [`SDL_Keymod`] values.
227    ///
228    /// This does not change the keyboard state, only the key modifier flags that
229    /// SDL reports.
230    ///
231    /// ## Parameters
232    /// - `modstate`: the desired [`SDL_Keymod`] for the keyboard.
233    ///
234    /// ## Thread safety
235    /// It is safe to call this function from any thread.
236    ///
237    /// ## Availability
238    /// This function is available since SDL 3.2.0.
239    ///
240    /// ## See also
241    /// - [`SDL_GetModState`]
242    pub fn SDL_SetModState(modstate: SDL_Keymod);
243}
244
245unsafe extern "C" {
246    /// Get the key code corresponding to the given scancode according to the
247    /// current keyboard layout.
248    ///
249    /// If you want to get the keycode as it would be delivered in key events,
250    /// including options specified in [`SDL_HINT_KEYCODE_OPTIONS`], then you should
251    /// pass `key_event` as true. Otherwise this function simply translates the
252    /// scancode based on the given modifier state.
253    ///
254    /// ## Parameters
255    /// - `scancode`: the desired [`SDL_Scancode`] to query.
256    /// - `modstate`: the modifier state to use when translating the scancode to
257    ///   a keycode.
258    /// - `key_event`: true if the keycode will be used in key events.
259    ///
260    /// ## Return value
261    /// Returns the [`SDL_Keycode`] that corresponds to the given [`SDL_Scancode`].
262    ///
263    /// ## Thread safety
264    /// This function is not thread safe.
265    ///
266    /// ## Availability
267    /// This function is available since SDL 3.2.0.
268    ///
269    /// ## See also
270    /// - [`SDL_GetKeyName`]
271    /// - [`SDL_GetScancodeFromKey`]
272    pub fn SDL_GetKeyFromScancode(
273        scancode: SDL_Scancode,
274        modstate: SDL_Keymod,
275        key_event: ::core::primitive::bool,
276    ) -> SDL_Keycode;
277}
278
279unsafe extern "C" {
280    /// Get the scancode corresponding to the given key code according to the
281    /// current keyboard layout.
282    ///
283    /// Note that there may be multiple scancode+modifier states that can generate
284    /// this keycode, this will just return the first one found.
285    ///
286    /// ## Parameters
287    /// - `key`: the desired [`SDL_Keycode`] to query.
288    /// - `modstate`: a pointer to the modifier state that would be used when the
289    ///   scancode generates this key, may be NULL.
290    ///
291    /// ## Return value
292    /// Returns the [`SDL_Scancode`] that corresponds to the given [`SDL_Keycode`].
293    ///
294    /// ## Thread safety
295    /// This function is not thread safe.
296    ///
297    /// ## Availability
298    /// This function is available since SDL 3.2.0.
299    ///
300    /// ## See also
301    /// - [`SDL_GetKeyFromScancode`]
302    /// - [`SDL_GetScancodeName`]
303    pub fn SDL_GetScancodeFromKey(key: SDL_Keycode, modstate: *mut SDL_Keymod) -> SDL_Scancode;
304}
305
306unsafe extern "C" {
307    /// Set a human-readable name for a scancode.
308    ///
309    /// ## Parameters
310    /// - `scancode`: the desired [`SDL_Scancode`].
311    /// - `name`: the name to use for the scancode, encoded as UTF-8. The string
312    ///   is not copied, so the pointer given to this function must stay
313    ///   valid while SDL is being used.
314    ///
315    /// ## Return value
316    /// Returns true on success or false on failure; call [`SDL_GetError()`] for more
317    ///   information.
318    ///
319    /// ## Thread safety
320    /// This function is not thread safe.
321    ///
322    /// ## Availability
323    /// This function is available since SDL 3.2.0.
324    ///
325    /// ## See also
326    /// - [`SDL_GetScancodeName`]
327    pub fn SDL_SetScancodeName(
328        scancode: SDL_Scancode,
329        name: *const ::core::ffi::c_char,
330    ) -> ::core::primitive::bool;
331}
332
333unsafe extern "C" {
334    /// Get a human-readable name for a scancode.
335    ///
336    /// **Warning**: The returned name is by design not stable across platforms,
337    /// e.g. the name for [`SDL_SCANCODE_LGUI`] is "Left GUI" under Linux but "Left
338    /// Windows" under Microsoft Windows, and some scancodes like
339    /// [`SDL_SCANCODE_NONUSBACKSLASH`] don't have any name at all. There are even
340    /// scancodes that share names, e.g. [`SDL_SCANCODE_RETURN`] and
341    /// [`SDL_SCANCODE_RETURN2`] (both called "Return"). This function is therefore
342    /// unsuitable for creating a stable cross-platform two-way mapping between
343    /// strings and scancodes.
344    ///
345    /// ## Parameters
346    /// - `scancode`: the desired [`SDL_Scancode`] to query.
347    ///
348    /// ## Return value
349    /// Returns a pointer to the name for the scancode. If the scancode doesn't
350    ///   have a name this function returns an empty string ("").
351    ///
352    /// ## Thread safety
353    /// This function is not thread safe.
354    ///
355    /// ## Availability
356    /// This function is available since SDL 3.2.0.
357    ///
358    /// ## See also
359    /// - [`SDL_GetScancodeFromKey`]
360    /// - [`SDL_GetScancodeFromName`]
361    /// - [`SDL_SetScancodeName`]
362    pub fn SDL_GetScancodeName(scancode: SDL_Scancode) -> *const ::core::ffi::c_char;
363}
364
365unsafe extern "C" {
366    /// Get a scancode from a human-readable name.
367    ///
368    /// ## Parameters
369    /// - `name`: the human-readable scancode name.
370    ///
371    /// ## Return value
372    /// Returns the [`SDL_Scancode`], or [`SDL_SCANCODE_UNKNOWN`] if the name wasn't
373    ///   recognized; call [`SDL_GetError()`] for more information.
374    ///
375    /// ## Thread safety
376    /// This function is not thread safe.
377    ///
378    /// ## Availability
379    /// This function is available since SDL 3.2.0.
380    ///
381    /// ## See also
382    /// - [`SDL_GetKeyFromName`]
383    /// - [`SDL_GetScancodeFromKey`]
384    /// - [`SDL_GetScancodeName`]
385    pub fn SDL_GetScancodeFromName(name: *const ::core::ffi::c_char) -> SDL_Scancode;
386}
387
388unsafe extern "C" {
389    /// Get a human-readable name for a key.
390    ///
391    /// If the key doesn't have a name, this function returns an empty string ("").
392    ///
393    /// Letters will be presented in their uppercase form, if applicable.
394    ///
395    /// ## Parameters
396    /// - `key`: the desired [`SDL_Keycode`] to query.
397    ///
398    /// ## Return value
399    /// Returns a UTF-8 encoded string of the key name.
400    ///
401    /// ## Thread safety
402    /// This function is not thread safe.
403    ///
404    /// ## Availability
405    /// This function is available since SDL 3.2.0.
406    ///
407    /// ## See also
408    /// - [`SDL_GetKeyFromName`]
409    /// - [`SDL_GetKeyFromScancode`]
410    /// - [`SDL_GetScancodeFromKey`]
411    pub fn SDL_GetKeyName(key: SDL_Keycode) -> *const ::core::ffi::c_char;
412}
413
414unsafe extern "C" {
415    /// Get a key code from a human-readable name.
416    ///
417    /// ## Parameters
418    /// - `name`: the human-readable key name.
419    ///
420    /// ## Return value
421    /// Returns key code, or `SDLK_UNKNOWN` if the name wasn't recognized; call
422    ///   [`SDL_GetError()`] for more information.
423    ///
424    /// ## Thread safety
425    /// This function is not thread safe.
426    ///
427    /// ## Availability
428    /// This function is available since SDL 3.2.0.
429    ///
430    /// ## See also
431    /// - [`SDL_GetKeyFromScancode`]
432    /// - [`SDL_GetKeyName`]
433    /// - [`SDL_GetScancodeFromName`]
434    pub fn SDL_GetKeyFromName(name: *const ::core::ffi::c_char) -> SDL_Keycode;
435}
436
437unsafe extern "C" {
438    /// Start accepting Unicode text input events in a window.
439    ///
440    /// This function will enable text input ([`SDL_EVENT_TEXT_INPUT`] and
441    /// [`SDL_EVENT_TEXT_EDITING`] events) in the specified window. Please use this
442    /// function paired with [`SDL_StopTextInput()`].
443    ///
444    /// Text input events are not received by default.
445    ///
446    /// On some platforms using this function shows the screen keyboard and/or
447    /// activates an IME, which can prevent some key press events from being passed
448    /// through.
449    ///
450    /// ## Parameters
451    /// - `window`: the window to enable text input.
452    ///
453    /// ## Return value
454    /// Returns true on success or false on failure; call [`SDL_GetError()`] for more
455    ///   information.
456    ///
457    /// ## Thread safety
458    /// This function should only be called on the main thread.
459    ///
460    /// ## Availability
461    /// This function is available since SDL 3.2.0.
462    ///
463    /// ## See also
464    /// - [`SDL_SetTextInputArea`]
465    /// - [`SDL_StartTextInputWithProperties`]
466    /// - [`SDL_StopTextInput`]
467    /// - [`SDL_TextInputActive`]
468    pub fn SDL_StartTextInput(window: *mut SDL_Window) -> ::core::primitive::bool;
469}
470
471/// Text input type.
472///
473/// These are the valid values for [`SDL_PROP_TEXTINPUT_TYPE_NUMBER`]. Not every
474/// value is valid on every platform, but where a value isn't supported, a
475/// reasonable fallback will be used.
476///
477/// ## Availability
478/// This enum is available since SDL 3.2.0.
479///
480/// ## See also
481/// - [`SDL_StartTextInputWithProperties`]
482///
483/// ## Known values (`sdl3-sys`)
484/// | Associated constant | Global constant | Description |
485/// | ------------------- | --------------- | ----------- |
486/// | [`TEXT`](SDL_TextInputType::TEXT) | [`SDL_TEXTINPUT_TYPE_TEXT`] | The input is text |
487/// | [`TEXT_NAME`](SDL_TextInputType::TEXT_NAME) | [`SDL_TEXTINPUT_TYPE_TEXT_NAME`] | The input is a person's name |
488/// | [`TEXT_EMAIL`](SDL_TextInputType::TEXT_EMAIL) | [`SDL_TEXTINPUT_TYPE_TEXT_EMAIL`] | The input is an e-mail address |
489/// | [`TEXT_USERNAME`](SDL_TextInputType::TEXT_USERNAME) | [`SDL_TEXTINPUT_TYPE_TEXT_USERNAME`] | The input is a username |
490/// | [`TEXT_PASSWORD_HIDDEN`](SDL_TextInputType::TEXT_PASSWORD_HIDDEN) | [`SDL_TEXTINPUT_TYPE_TEXT_PASSWORD_HIDDEN`] | The input is a secure password that is hidden |
491/// | [`TEXT_PASSWORD_VISIBLE`](SDL_TextInputType::TEXT_PASSWORD_VISIBLE) | [`SDL_TEXTINPUT_TYPE_TEXT_PASSWORD_VISIBLE`] | The input is a secure password that is visible |
492/// | [`NUMBER`](SDL_TextInputType::NUMBER) | [`SDL_TEXTINPUT_TYPE_NUMBER`] | The input is a number |
493/// | [`NUMBER_PASSWORD_HIDDEN`](SDL_TextInputType::NUMBER_PASSWORD_HIDDEN) | [`SDL_TEXTINPUT_TYPE_NUMBER_PASSWORD_HIDDEN`] | The input is a secure PIN that is hidden |
494/// | [`NUMBER_PASSWORD_VISIBLE`](SDL_TextInputType::NUMBER_PASSWORD_VISIBLE) | [`SDL_TEXTINPUT_TYPE_NUMBER_PASSWORD_VISIBLE`] | The input is a secure PIN that is visible |
495#[repr(transparent)]
496#[derive(Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
497pub struct SDL_TextInputType(pub ::core::ffi::c_int);
498
499impl ::core::cmp::PartialEq<::core::ffi::c_int> for SDL_TextInputType {
500    #[inline(always)]
501    fn eq(&self, other: &::core::ffi::c_int) -> bool {
502        &self.0 == other
503    }
504}
505
506impl ::core::cmp::PartialEq<SDL_TextInputType> for ::core::ffi::c_int {
507    #[inline(always)]
508    fn eq(&self, other: &SDL_TextInputType) -> bool {
509        self == &other.0
510    }
511}
512
513impl From<SDL_TextInputType> for ::core::ffi::c_int {
514    #[inline(always)]
515    fn from(value: SDL_TextInputType) -> Self {
516        value.0
517    }
518}
519
520#[cfg(feature = "debug-impls")]
521impl ::core::fmt::Debug for SDL_TextInputType {
522    fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
523        #[allow(unreachable_patterns)]
524        f.write_str(match *self {
525            Self::TEXT => "SDL_TEXTINPUT_TYPE_TEXT",
526            Self::TEXT_NAME => "SDL_TEXTINPUT_TYPE_TEXT_NAME",
527            Self::TEXT_EMAIL => "SDL_TEXTINPUT_TYPE_TEXT_EMAIL",
528            Self::TEXT_USERNAME => "SDL_TEXTINPUT_TYPE_TEXT_USERNAME",
529            Self::TEXT_PASSWORD_HIDDEN => "SDL_TEXTINPUT_TYPE_TEXT_PASSWORD_HIDDEN",
530            Self::TEXT_PASSWORD_VISIBLE => "SDL_TEXTINPUT_TYPE_TEXT_PASSWORD_VISIBLE",
531            Self::NUMBER => "SDL_TEXTINPUT_TYPE_NUMBER",
532            Self::NUMBER_PASSWORD_HIDDEN => "SDL_TEXTINPUT_TYPE_NUMBER_PASSWORD_HIDDEN",
533            Self::NUMBER_PASSWORD_VISIBLE => "SDL_TEXTINPUT_TYPE_NUMBER_PASSWORD_VISIBLE",
534
535            _ => return write!(f, "SDL_TextInputType({})", self.0),
536        })
537    }
538}
539
540impl SDL_TextInputType {
541    /// The input is text
542    pub const TEXT: Self = Self((0 as ::core::ffi::c_int));
543    /// The input is a person's name
544    pub const TEXT_NAME: Self = Self((1 as ::core::ffi::c_int));
545    /// The input is an e-mail address
546    pub const TEXT_EMAIL: Self = Self((2 as ::core::ffi::c_int));
547    /// The input is a username
548    pub const TEXT_USERNAME: Self = Self((3 as ::core::ffi::c_int));
549    /// The input is a secure password that is hidden
550    pub const TEXT_PASSWORD_HIDDEN: Self = Self((4 as ::core::ffi::c_int));
551    /// The input is a secure password that is visible
552    pub const TEXT_PASSWORD_VISIBLE: Self = Self((5 as ::core::ffi::c_int));
553    /// The input is a number
554    pub const NUMBER: Self = Self((6 as ::core::ffi::c_int));
555    /// The input is a secure PIN that is hidden
556    pub const NUMBER_PASSWORD_HIDDEN: Self = Self((7 as ::core::ffi::c_int));
557    /// The input is a secure PIN that is visible
558    pub const NUMBER_PASSWORD_VISIBLE: Self = Self((8 as ::core::ffi::c_int));
559}
560
561/// The input is text
562pub const SDL_TEXTINPUT_TYPE_TEXT: SDL_TextInputType = SDL_TextInputType::TEXT;
563/// The input is a person's name
564pub const SDL_TEXTINPUT_TYPE_TEXT_NAME: SDL_TextInputType = SDL_TextInputType::TEXT_NAME;
565/// The input is an e-mail address
566pub const SDL_TEXTINPUT_TYPE_TEXT_EMAIL: SDL_TextInputType = SDL_TextInputType::TEXT_EMAIL;
567/// The input is a username
568pub const SDL_TEXTINPUT_TYPE_TEXT_USERNAME: SDL_TextInputType = SDL_TextInputType::TEXT_USERNAME;
569/// The input is a secure password that is hidden
570pub const SDL_TEXTINPUT_TYPE_TEXT_PASSWORD_HIDDEN: SDL_TextInputType =
571    SDL_TextInputType::TEXT_PASSWORD_HIDDEN;
572/// The input is a secure password that is visible
573pub const SDL_TEXTINPUT_TYPE_TEXT_PASSWORD_VISIBLE: SDL_TextInputType =
574    SDL_TextInputType::TEXT_PASSWORD_VISIBLE;
575/// The input is a number
576pub const SDL_TEXTINPUT_TYPE_NUMBER: SDL_TextInputType = SDL_TextInputType::NUMBER;
577/// The input is a secure PIN that is hidden
578pub const SDL_TEXTINPUT_TYPE_NUMBER_PASSWORD_HIDDEN: SDL_TextInputType =
579    SDL_TextInputType::NUMBER_PASSWORD_HIDDEN;
580/// The input is a secure PIN that is visible
581pub const SDL_TEXTINPUT_TYPE_NUMBER_PASSWORD_VISIBLE: SDL_TextInputType =
582    SDL_TextInputType::NUMBER_PASSWORD_VISIBLE;
583
584#[cfg(feature = "metadata")]
585impl sdl3_sys::metadata::GroupMetadata for SDL_TextInputType {
586    const GROUP_METADATA: &'static sdl3_sys::metadata::Group =
587        &crate::metadata::keyboard::METADATA_SDL_TextInputType;
588}
589
590/// Auto capitalization type.
591///
592/// These are the valid values for [`SDL_PROP_TEXTINPUT_CAPITALIZATION_NUMBER`].
593/// Not every value is valid on every platform, but where a value isn't
594/// supported, a reasonable fallback will be used.
595///
596/// ## Availability
597/// This enum is available since SDL 3.2.0.
598///
599/// ## See also
600/// - [`SDL_StartTextInputWithProperties`]
601///
602/// ## Known values (`sdl3-sys`)
603/// | Associated constant | Global constant | Description |
604/// | ------------------- | --------------- | ----------- |
605/// | [`NONE`](SDL_Capitalization::NONE) | [`SDL_CAPITALIZE_NONE`] | No auto-capitalization will be done |
606/// | [`SENTENCES`](SDL_Capitalization::SENTENCES) | [`SDL_CAPITALIZE_SENTENCES`] | The first letter of sentences will be capitalized |
607/// | [`WORDS`](SDL_Capitalization::WORDS) | [`SDL_CAPITALIZE_WORDS`] | The first letter of words will be capitalized |
608/// | [`LETTERS`](SDL_Capitalization::LETTERS) | [`SDL_CAPITALIZE_LETTERS`] | All letters will be capitalized |
609#[repr(transparent)]
610#[derive(Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
611pub struct SDL_Capitalization(pub ::core::ffi::c_int);
612
613impl ::core::cmp::PartialEq<::core::ffi::c_int> for SDL_Capitalization {
614    #[inline(always)]
615    fn eq(&self, other: &::core::ffi::c_int) -> bool {
616        &self.0 == other
617    }
618}
619
620impl ::core::cmp::PartialEq<SDL_Capitalization> for ::core::ffi::c_int {
621    #[inline(always)]
622    fn eq(&self, other: &SDL_Capitalization) -> bool {
623        self == &other.0
624    }
625}
626
627impl From<SDL_Capitalization> for ::core::ffi::c_int {
628    #[inline(always)]
629    fn from(value: SDL_Capitalization) -> Self {
630        value.0
631    }
632}
633
634#[cfg(feature = "debug-impls")]
635impl ::core::fmt::Debug for SDL_Capitalization {
636    fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
637        #[allow(unreachable_patterns)]
638        f.write_str(match *self {
639            Self::NONE => "SDL_CAPITALIZE_NONE",
640            Self::SENTENCES => "SDL_CAPITALIZE_SENTENCES",
641            Self::WORDS => "SDL_CAPITALIZE_WORDS",
642            Self::LETTERS => "SDL_CAPITALIZE_LETTERS",
643
644            _ => return write!(f, "SDL_Capitalization({})", self.0),
645        })
646    }
647}
648
649impl SDL_Capitalization {
650    /// No auto-capitalization will be done
651    pub const NONE: Self = Self((0 as ::core::ffi::c_int));
652    /// The first letter of sentences will be capitalized
653    pub const SENTENCES: Self = Self((1 as ::core::ffi::c_int));
654    /// The first letter of words will be capitalized
655    pub const WORDS: Self = Self((2 as ::core::ffi::c_int));
656    /// All letters will be capitalized
657    pub const LETTERS: Self = Self((3 as ::core::ffi::c_int));
658}
659
660/// No auto-capitalization will be done
661pub const SDL_CAPITALIZE_NONE: SDL_Capitalization = SDL_Capitalization::NONE;
662/// The first letter of sentences will be capitalized
663pub const SDL_CAPITALIZE_SENTENCES: SDL_Capitalization = SDL_Capitalization::SENTENCES;
664/// The first letter of words will be capitalized
665pub const SDL_CAPITALIZE_WORDS: SDL_Capitalization = SDL_Capitalization::WORDS;
666/// All letters will be capitalized
667pub const SDL_CAPITALIZE_LETTERS: SDL_Capitalization = SDL_Capitalization::LETTERS;
668
669#[cfg(feature = "metadata")]
670impl sdl3_sys::metadata::GroupMetadata for SDL_Capitalization {
671    const GROUP_METADATA: &'static sdl3_sys::metadata::Group =
672        &crate::metadata::keyboard::METADATA_SDL_Capitalization;
673}
674
675unsafe extern "C" {
676    /// Start accepting Unicode text input events in a window, with properties
677    /// describing the input.
678    ///
679    /// This function will enable text input ([`SDL_EVENT_TEXT_INPUT`] and
680    /// [`SDL_EVENT_TEXT_EDITING`] events) in the specified window. Please use this
681    /// function paired with [`SDL_StopTextInput()`].
682    ///
683    /// Text input events are not received by default.
684    ///
685    /// On some platforms using this function shows the screen keyboard and/or
686    /// activates an IME, which can prevent some key press events from being passed
687    /// through.
688    ///
689    /// These are the supported properties:
690    ///
691    /// - [`SDL_PROP_TEXTINPUT_TYPE_NUMBER`] - an [`SDL_TextInputType`] value that
692    ///   describes text being input, defaults to [`SDL_TEXTINPUT_TYPE_TEXT`].
693    /// - [`SDL_PROP_TEXTINPUT_CAPITALIZATION_NUMBER`] - an [`SDL_Capitalization`] value
694    ///   that describes how text should be capitalized, defaults to
695    ///   [`SDL_CAPITALIZE_SENTENCES`] for normal text entry, [`SDL_CAPITALIZE_WORDS`] for
696    ///   [`SDL_TEXTINPUT_TYPE_TEXT_NAME`], and [`SDL_CAPITALIZE_NONE`] for e-mail
697    ///   addresses, usernames, and passwords.
698    /// - [`SDL_PROP_TEXTINPUT_AUTOCORRECT_BOOLEAN`] - true to enable auto completion
699    ///   and auto correction, defaults to true.
700    /// - [`SDL_PROP_TEXTINPUT_MULTILINE_BOOLEAN`] - true if multiple lines of text
701    ///   are allowed. This defaults to true if [`SDL_HINT_RETURN_KEY_HIDES_IME`] is
702    ///   "0" or is not set, and defaults to false if [`SDL_HINT_RETURN_KEY_HIDES_IME`]
703    ///   is "1".
704    ///
705    /// On Android you can directly specify the input type:
706    ///
707    /// - [`SDL_PROP_TEXTINPUT_ANDROID_INPUTTYPE_NUMBER`] - the text input type to
708    ///   use, overriding other properties. This is documented at
709    ///   <https://developer.android.com/reference/android/text/InputType>
710    ///
711    /// ## Parameters
712    /// - `window`: the window to enable text input.
713    /// - `props`: the properties to use.
714    ///
715    /// ## Return value
716    /// Returns true on success or false on failure; call [`SDL_GetError()`] for more
717    ///   information.
718    ///
719    /// ## Thread safety
720    /// This function should only be called on the main thread.
721    ///
722    /// ## Availability
723    /// This function is available since SDL 3.2.0.
724    ///
725    /// ## See also
726    /// - [`SDL_SetTextInputArea`]
727    /// - [`SDL_StartTextInput`]
728    /// - [`SDL_StopTextInput`]
729    /// - [`SDL_TextInputActive`]
730    pub fn SDL_StartTextInputWithProperties(
731        window: *mut SDL_Window,
732        props: SDL_PropertiesID,
733    ) -> ::core::primitive::bool;
734}
735
736pub const SDL_PROP_TEXTINPUT_TYPE_NUMBER: *const ::core::ffi::c_char =
737    c"SDL.textinput.type".as_ptr();
738
739pub const SDL_PROP_TEXTINPUT_CAPITALIZATION_NUMBER: *const ::core::ffi::c_char =
740    c"SDL.textinput.capitalization".as_ptr();
741
742pub const SDL_PROP_TEXTINPUT_AUTOCORRECT_BOOLEAN: *const ::core::ffi::c_char =
743    c"SDL.textinput.autocorrect".as_ptr();
744
745pub const SDL_PROP_TEXTINPUT_MULTILINE_BOOLEAN: *const ::core::ffi::c_char =
746    c"SDL.textinput.multiline".as_ptr();
747
748pub const SDL_PROP_TEXTINPUT_ANDROID_INPUTTYPE_NUMBER: *const ::core::ffi::c_char =
749    c"SDL.textinput.android.inputtype".as_ptr();
750
751unsafe extern "C" {
752    /// Check whether or not Unicode text input events are enabled for a window.
753    ///
754    /// ## Parameters
755    /// - `window`: the window to check.
756    ///
757    /// ## Return value
758    /// Returns true if text input events are enabled else false.
759    ///
760    /// ## Thread safety
761    /// This function should only be called on the main thread.
762    ///
763    /// ## Availability
764    /// This function is available since SDL 3.2.0.
765    ///
766    /// ## See also
767    /// - [`SDL_StartTextInput`]
768    pub fn SDL_TextInputActive(window: *mut SDL_Window) -> ::core::primitive::bool;
769}
770
771unsafe extern "C" {
772    /// Stop receiving any text input events in a window.
773    ///
774    /// If [`SDL_StartTextInput()`] showed the screen keyboard, this function will hide
775    /// it.
776    ///
777    /// ## Parameters
778    /// - `window`: the window to disable text input.
779    ///
780    /// ## Return value
781    /// Returns true on success or false on failure; call [`SDL_GetError()`] for more
782    ///   information.
783    ///
784    /// ## Thread safety
785    /// This function should only be called on the main thread.
786    ///
787    /// ## Availability
788    /// This function is available since SDL 3.2.0.
789    ///
790    /// ## See also
791    /// - [`SDL_StartTextInput`]
792    pub fn SDL_StopTextInput(window: *mut SDL_Window) -> ::core::primitive::bool;
793}
794
795unsafe extern "C" {
796    /// Dismiss the composition window/IME without disabling the subsystem.
797    ///
798    /// ## Parameters
799    /// - `window`: the window to affect.
800    ///
801    /// ## Return value
802    /// Returns true on success or false on failure; call [`SDL_GetError()`] for more
803    ///   information.
804    ///
805    /// ## Thread safety
806    /// This function should only be called on the main thread.
807    ///
808    /// ## Availability
809    /// This function is available since SDL 3.2.0.
810    ///
811    /// ## See also
812    /// - [`SDL_StartTextInput`]
813    /// - [`SDL_StopTextInput`]
814    pub fn SDL_ClearComposition(window: *mut SDL_Window) -> ::core::primitive::bool;
815}
816
817unsafe extern "C" {
818    /// Set the area used to type Unicode text input.
819    ///
820    /// Native input methods may place a window with word suggestions near the
821    /// cursor, without covering the text being entered.
822    ///
823    /// ## Parameters
824    /// - `window`: the window for which to set the text input area.
825    /// - `rect`: the [`SDL_Rect`] representing the text input area, in window
826    ///   coordinates, or NULL to clear it.
827    /// - `cursor`: the offset of the current cursor location relative to
828    ///   `rect->x`, in window coordinates.
829    ///
830    /// ## Return value
831    /// Returns true on success or false on failure; call [`SDL_GetError()`] for more
832    ///   information.
833    ///
834    /// ## Thread safety
835    /// This function should only be called on the main thread.
836    ///
837    /// ## Availability
838    /// This function is available since SDL 3.2.0.
839    ///
840    /// ## See also
841    /// - [`SDL_GetTextInputArea`]
842    /// - [`SDL_StartTextInput`]
843    pub fn SDL_SetTextInputArea(
844        window: *mut SDL_Window,
845        rect: *const SDL_Rect,
846        cursor: ::core::ffi::c_int,
847    ) -> ::core::primitive::bool;
848}
849
850unsafe extern "C" {
851    /// Get the area used to type Unicode text input.
852    ///
853    /// This returns the values previously set by [`SDL_SetTextInputArea()`].
854    ///
855    /// ## Parameters
856    /// - `window`: the window for which to query the text input area.
857    /// - `rect`: a pointer to an [`SDL_Rect`] filled in with the text input area,
858    ///   may be NULL.
859    /// - `cursor`: a pointer to the offset of the current cursor location
860    ///   relative to `rect->x`, may be NULL.
861    ///
862    /// ## Return value
863    /// Returns true on success or false on failure; call [`SDL_GetError()`] for more
864    ///   information.
865    ///
866    /// ## Thread safety
867    /// This function should only be called on the main thread.
868    ///
869    /// ## Availability
870    /// This function is available since SDL 3.2.0.
871    ///
872    /// ## See also
873    /// - [`SDL_SetTextInputArea`]
874    pub fn SDL_GetTextInputArea(
875        window: *mut SDL_Window,
876        rect: *mut SDL_Rect,
877        cursor: *mut ::core::ffi::c_int,
878    ) -> ::core::primitive::bool;
879}
880
881unsafe extern "C" {
882    /// Check whether the platform has screen keyboard support.
883    ///
884    /// ## Return value
885    /// Returns true if the platform has some screen keyboard support or false if
886    ///   not.
887    ///
888    /// ## Thread safety
889    /// This function should only be called on the main thread.
890    ///
891    /// ## Availability
892    /// This function is available since SDL 3.2.0.
893    ///
894    /// ## See also
895    /// - [`SDL_StartTextInput`]
896    /// - [`SDL_ScreenKeyboardShown`]
897    pub fn SDL_HasScreenKeyboardSupport() -> ::core::primitive::bool;
898}
899
900unsafe extern "C" {
901    /// Check whether the screen keyboard is shown for given window.
902    ///
903    /// ## Parameters
904    /// - `window`: the window for which screen keyboard should be queried.
905    ///
906    /// ## Return value
907    /// Returns true if screen keyboard is shown or false if not.
908    ///
909    /// ## Thread safety
910    /// This function should only be called on the main thread.
911    ///
912    /// ## Availability
913    /// This function is available since SDL 3.2.0.
914    ///
915    /// ## See also
916    /// - [`SDL_HasScreenKeyboardSupport`]
917    pub fn SDL_ScreenKeyboardShown(window: *mut SDL_Window) -> ::core::primitive::bool;
918}
919
920#[cfg(doc)]
921use crate::everything::*;
sdl3_sys/generated/keyboard.rs

sdl3_sys/generated/
keyboard.rs
