SDL_keyboard.h File Reference
`#include <SDL3/SDL_stdinc.h>`
`#include <SDL3/SDL_error.h>`
`#include <SDL3/SDL_keycode.h>`
`#include <SDL3/SDL_properties.h>`
`#include <SDL3/SDL_rect.h>`
`#include <SDL3/SDL_scancode.h>`
`#include <SDL3/SDL_video.h>`
`#include <SDL3/SDL_begin_code.h>`
`#include <SDL3/SDL_close_code.h>`
Include dependency graph for SDL_keyboard.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Macros

#define | SDL_PROP_TEXTINPUT_TYPE_NUMBER "SDL.textinput.type"
#define | SDL_PROP_TEXTINPUT_CAPITALIZATION_NUMBER "SDL.textinput.capitalization"
#define | SDL_PROP_TEXTINPUT_AUTOCORRECT_BOOLEAN "SDL.textinput.autocorrect"
#define | SDL_PROP_TEXTINPUT_MULTILINE_BOOLEAN "SDL.textinput.multiline"
#define | SDL_PROP_TEXTINPUT_ANDROID_INPUTTYPE_NUMBER "SDL.textinput.android.inputtype"

## Typedefs

typedef Uint32 | SDL_KeyboardID

## Enumerations

enum | SDL_TextInputType { SDL_TEXTINPUT_TYPE_TEXT , SDL_TEXTINPUT_TYPE_TEXT_NAME , SDL_TEXTINPUT_TYPE_TEXT_EMAIL , SDL_TEXTINPUT_TYPE_TEXT_USERNAME , SDL_TEXTINPUT_TYPE_TEXT_PASSWORD_HIDDEN , SDL_TEXTINPUT_TYPE_TEXT_PASSWORD_VISIBLE , SDL_TEXTINPUT_TYPE_NUMBER , SDL_TEXTINPUT_TYPE_NUMBER_PASSWORD_HIDDEN , SDL_TEXTINPUT_TYPE_NUMBER_PASSWORD_VISIBLE }
enum | SDL_Capitalization { SDL_CAPITALIZE_NONE , SDL_CAPITALIZE_SENTENCES , SDL_CAPITALIZE_WORDS , SDL_CAPITALIZE_LETTERS }

## Functions

bool | SDL_HasKeyboard (void)
SDL_KeyboardID * | SDL_GetKeyboards (int *count)
const char * | SDL_GetKeyboardNameForID (SDL_KeyboardID instance_id)
SDL_Window * | SDL_GetKeyboardFocus (void)
const bool * | SDL_GetKeyboardState (int *numkeys)
void | SDL_ResetKeyboard (void)
SDL_Keymod | SDL_GetModState (void)
void | SDL_SetModState (SDL_Keymod modstate)
SDL_Keycode | SDL_GetKeyFromScancode (SDL_Scancode scancode, SDL_Keymod modstate, bool key_event)
SDL_Scancode | SDL_GetScancodeFromKey (SDL_Keycode key, SDL_Keymod *modstate)
bool | SDL_SetScancodeName (SDL_Scancode scancode, const char *name)
const char * | SDL_GetScancodeName (SDL_Scancode scancode)
SDL_Scancode | SDL_GetScancodeFromName (const char *name)
const char * | SDL_GetKeyName (SDL_Keycode key)
SDL_Keycode | SDL_GetKeyFromName (const char *name)
bool | SDL_StartTextInput (SDL_Window *window)
bool | SDL_StartTextInputWithProperties (SDL_Window *window, SDL_PropertiesID props)
bool | SDL_TextInputActive (SDL_Window *window)
bool | SDL_StopTextInput (SDL_Window *window)
bool | SDL_ClearComposition (SDL_Window *window)
bool | SDL_SetTextInputArea (SDL_Window *window, const SDL_Rect *rect, int cursor)
bool | SDL_GetTextInputArea (SDL_Window *window, SDL_Rect *rect, int *cursor)
bool | SDL_HasScreenKeyboardSupport (void)
bool | SDL_ScreenKeyboardShown (SDL_Window *window)

## Macro Definition Documentation

## SDL_PROP_TEXTINPUT_ANDROID_INPUTTYPE_NUMBER

#define SDL_PROP_TEXTINPUT_ANDROID_INPUTTYPE_NUMBER "SDL.textinput.android.inputtype"

Definition at line 479 of file SDL_keyboard.h.

## SDL_PROP_TEXTINPUT_AUTOCORRECT_BOOLEAN

#define SDL_PROP_TEXTINPUT_AUTOCORRECT_BOOLEAN "SDL.textinput.autocorrect"

Definition at line 477 of file SDL_keyboard.h.

## SDL_PROP_TEXTINPUT_CAPITALIZATION_NUMBER

#define SDL_PROP_TEXTINPUT_CAPITALIZATION_NUMBER "SDL.textinput.capitalization"

Definition at line 476 of file SDL_keyboard.h.

## SDL_PROP_TEXTINPUT_MULTILINE_BOOLEAN

#define SDL_PROP_TEXTINPUT_MULTILINE_BOOLEAN "SDL.textinput.multiline"

Definition at line 478 of file SDL_keyboard.h.

## SDL_PROP_TEXTINPUT_TYPE_NUMBER

#define SDL_PROP_TEXTINPUT_TYPE_NUMBER "SDL.textinput.type"

Definition at line 475 of file SDL_keyboard.h.

## Typedef Documentation

## SDL_KeyboardID

typedef Uint32 SDL_KeyboardID

# CategoryKeyboard

SDL keyboard management.

Please refer to the Best Keyboard Practices document for details on how best to accept keyboard input in various types of programs:

https://wiki.libsdl.org/SDL3/BestKeyboardPractices This is a unique ID for a keyboard for the time it is connected to the system, and is never reused for the lifetime of the application.

If the keyboard is disconnected and reconnected, it will get a new ID.

The value 0 is an invalid ID.

Since
  This datatype is available since SDL 3.2.0.

Definition at line 60 of file SDL_keyboard.h.

## Enumeration Type Documentation

## SDL_Capitalization

enum SDL_Capitalization

Auto capitalization type.

These are the valid values for SDL_PROP_TEXTINPUT_CAPITALIZATION_NUMBER. Not every value is valid on every platform, but where a value isn't supported, a reasonable fallback will be used.

Since
  This enum is available since SDL 3.2.0.

See also
  SDL_StartTextInputWithProperties

Enumerator
SDL_CAPITALIZE_NONE | No auto-capitalization will be done
SDL_CAPITALIZE_SENTENCES | The first letter of sentences will be capitalized
SDL_CAPITALIZE_WORDS | The first letter of words will be capitalized
SDL_CAPITALIZE_LETTERS | All letters will be capitalized

Definition at line 415 of file SDL_keyboard.h.

{
SDL_CAPITALIZE_NONE, /**< No auto-capitalization will be done */
SDL_CAPITALIZE_SENTENCES, /**< The first letter of sentences will be capitalized */
SDL_CAPITALIZE_WORDS, /**< The first letter of words will be capitalized */
SDL_CAPITALIZE_LETTERS /**< All letters will be capitalized */
} SDL_Capitalization;
SDL_Capitalization
SDL_Capitalization
Definition SDL_keyboard.h:416
SDL_CAPITALIZE_LETTERS
@ SDL_CAPITALIZE_LETTERS
Definition SDL_keyboard.h:420
SDL_CAPITALIZE_SENTENCES
@ SDL_CAPITALIZE_SENTENCES
Definition SDL_keyboard.h:418
SDL_CAPITALIZE_NONE
@ SDL_CAPITALIZE_NONE
Definition SDL_keyboard.h:417
SDL_CAPITALIZE_WORDS
@ SDL_CAPITALIZE_WORDS
Definition SDL_keyboard.h:419

## SDL_TextInputType

enum SDL_TextInputType

Text input type.

These are the valid values for SDL_PROP_TEXTINPUT_TYPE_NUMBER. Not every value is valid on every platform, but where a value isn't supported, a reasonable fallback will be used.

Since
  This enum is available since SDL 3.2.0.

See also
  SDL_StartTextInputWithProperties

Enumerator
SDL_TEXTINPUT_TYPE_TEXT | The input is text
SDL_TEXTINPUT_TYPE_TEXT_NAME | The input is a person's name
SDL_TEXTINPUT_TYPE_TEXT_EMAIL | The input is an e-mail address
SDL_TEXTINPUT_TYPE_TEXT_USERNAME | The input is a username
SDL_TEXTINPUT_TYPE_TEXT_PASSWORD_HIDDEN | The input is a secure password that is hidden
SDL_TEXTINPUT_TYPE_TEXT_PASSWORD_VISIBLE | The input is a secure password that is visible
SDL_TEXTINPUT_TYPE_NUMBER | The input is a number
SDL_TEXTINPUT_TYPE_NUMBER_PASSWORD_HIDDEN | The input is a secure PIN that is hidden
SDL_TEXTINPUT_TYPE_NUMBER_PASSWORD_VISIBLE | The input is a secure PIN that is visible

Definition at line 391 of file SDL_keyboard.h.

{
SDL_TEXTINPUT_TYPE_TEXT, /**< The input is text */
SDL_TEXTINPUT_TYPE_TEXT_NAME, /**< The input is a person's name */
SDL_TEXTINPUT_TYPE_TEXT_EMAIL, /**< The input is an e-mail address */
SDL_TEXTINPUT_TYPE_TEXT_USERNAME, /**< The input is a username */
SDL_TEXTINPUT_TYPE_TEXT_PASSWORD_HIDDEN, /**< The input is a secure password that is hidden */
SDL_TEXTINPUT_TYPE_TEXT_PASSWORD_VISIBLE, /**< The input is a secure password that is visible */
SDL_TEXTINPUT_TYPE_NUMBER, /**< The input is a number */
SDL_TEXTINPUT_TYPE_NUMBER_PASSWORD_HIDDEN, /**< The input is a secure PIN that is hidden */
SDL_TEXTINPUT_TYPE_NUMBER_PASSWORD_VISIBLE /**< The input is a secure PIN that is visible */
} SDL_TextInputType;
SDL_TextInputType
SDL_TextInputType
Definition SDL_keyboard.h:392
SDL_TEXTINPUT_TYPE_NUMBER_PASSWORD_VISIBLE
@ SDL_TEXTINPUT_TYPE_NUMBER_PASSWORD_VISIBLE
Definition SDL_keyboard.h:401
SDL_TEXTINPUT_TYPE_TEXT_PASSWORD_HIDDEN
@ SDL_TEXTINPUT_TYPE_TEXT_PASSWORD_HIDDEN
Definition SDL_keyboard.h:397
SDL_TEXTINPUT_TYPE_TEXT_USERNAME
@ SDL_TEXTINPUT_TYPE_TEXT_USERNAME
Definition SDL_keyboard.h:396
SDL_TEXTINPUT_TYPE_TEXT
@ SDL_TEXTINPUT_TYPE_TEXT
Definition SDL_keyboard.h:393
SDL_TEXTINPUT_TYPE_NUMBER_PASSWORD_HIDDEN
@ SDL_TEXTINPUT_TYPE_NUMBER_PASSWORD_HIDDEN
Definition SDL_keyboard.h:400
SDL_TEXTINPUT_TYPE_TEXT_EMAIL
@ SDL_TEXTINPUT_TYPE_TEXT_EMAIL
Definition SDL_keyboard.h:395
SDL_TEXTINPUT_TYPE_TEXT_PASSWORD_VISIBLE
@ SDL_TEXTINPUT_TYPE_TEXT_PASSWORD_VISIBLE
Definition SDL_keyboard.h:398
SDL_TEXTINPUT_TYPE_NUMBER
@ SDL_TEXTINPUT_TYPE_NUMBER
Definition SDL_keyboard.h:399
SDL_TEXTINPUT_TYPE_TEXT_NAME
@ SDL_TEXTINPUT_TYPE_TEXT_NAME
Definition SDL_keyboard.h:394

## Function Documentation

## SDL_ClearComposition()

bool SDL_ClearComposition | ( | SDL_Window * | window | ) |

extern

Dismiss the composition window/IME without disabling the subsystem.

Parameters

  window | the window to affect.

Returns
  true on success or false on failure; call SDL_GetError() for more information.

\threadsafety This function should only be called on the main thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_StartTextInput
  SDL_StopTextInput

References window.

## SDL_GetKeyboardFocus()

SDL_Window * SDL_GetKeyboardFocus | ( | void |  | ) |

extern

Query the window which currently has keyboard focus.

Returns
  the window with keyboard focus.

\threadsafety This function should only be called on the main thread.

Since
  This function is available since SDL 3.2.0.

## SDL_GetKeyboardNameForID()

const char * SDL_GetKeyboardNameForID | ( | SDL_KeyboardID | instance_id | ) |

extern

Get the name of a keyboard.

This function returns "" if the keyboard doesn't have a name.

Parameters

  instance_id | the keyboard instance ID.

Returns
  the name of the selected keyboard or NULL on failure; call SDL_GetError() for more information.

\threadsafety This function should only be called on the main thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_GetKeyboards

## SDL_GetKeyboards()

SDL_KeyboardID * SDL_GetKeyboards | ( | int * | count | ) |

extern

Get a list of currently connected keyboards.

Note that this will include any device or virtual driver that includes keyboard functionality, including some mice, KVM switches, motherboard power buttons, etc. You should wait for input from a device before you consider it actively in use.

Parameters

  count | a pointer filled in with the number of keyboards returned, may be NULL.

Returns
  a 0 terminated array of keyboards instance IDs or NULL on failure; call SDL_GetError() for more information. This should be freed with SDL_free() when it is no longer needed.

\threadsafety This function should only be called on the main thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_GetKeyboardNameForID
  SDL_HasKeyboard

## SDL_GetKeyboardState()

const bool * SDL_GetKeyboardState | ( | int * | numkeys | ) |

extern

Get a snapshot of the current state of the keyboard.

The pointer returned is a pointer to an internal SDL array. It will be valid for the whole lifetime of the application and should not be freed by the caller.

A array element with a value of true means that the key is pressed and a value of false means that it is not. Indexes into this array are obtained by using SDL_Scancode values.

Use SDL_PumpEvents() to update the state array.

This function gives you the current state after all events have been processed, so if a key or button has been pressed and released before you process events, then the pressed state will never show up in the SDL_GetKeyboardState() calls.

Note: This function doesn't take into account whether shift has been pressed or not.

Parameters

  numkeys | if non-NULL, receives the length of the returned array.

Returns
  a pointer to an array of key states.

\threadsafety It is safe to call this function from any thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_PumpEvents
  SDL_ResetKeyboard

## SDL_GetKeyFromName()

SDL_Keycode SDL_GetKeyFromName | ( | const char * | name | ) |

extern

Get a key code from a human-readable name.

Parameters

  name | the human-readable key name.

Returns
  key code, or SDLK_UNKNOWN if the name wasn't recognized; call SDL_GetError() for more information.

\threadsafety This function is not thread safe.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_GetKeyFromScancode
  SDL_GetKeyName
  SDL_GetScancodeFromName

## SDL_GetKeyFromScancode()

SDL_Keycode SDL_GetKeyFromScancode | ( | SDL_Scancode | scancode,
|  | SDL_Keymod | modstate,
|  | bool | key_event )

extern

Get the key code corresponding to the given scancode according to the current keyboard layout.

If you want to get the keycode as it would be delivered in key events, including options specified in SDL_HINT_KEYCODE_OPTIONS, then you should pass key_event as true. Otherwise this function simply translates the scancode based on the given modifier state.

Parameters

  scancode | the desired SDL_Scancode to query.
  modstate | the modifier state to use when translating the scancode to a keycode.
  key_event | true if the keycode will be used in key events.

Returns
  the SDL_Keycode that corresponds to the given SDL_Scancode.

\threadsafety This function is not thread safe.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_GetKeyName
  SDL_GetScancodeFromKey

## SDL_GetKeyName()

const char * SDL_GetKeyName | ( | SDL_Keycode | key | ) |

extern

Get a human-readable name for a key.

If the key doesn't have a name, this function returns an empty string ("").

Letters will be presented in their uppercase form, if applicable.

Parameters

  key | the desired SDL_Keycode to query.

Returns
  a UTF-8 encoded string of the key name.

\threadsafety This function is not thread safe.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_GetKeyFromName
  SDL_GetKeyFromScancode
  SDL_GetScancodeFromKey

## SDL_GetModState()

SDL_Keymod SDL_GetModState | ( | void |  | ) |

extern

Get the current key modifier state for the keyboard.

Returns
  an OR'd combination of the modifier keys for the keyboard.

\threadsafety It is safe to call this function from any thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_GetKeyboardState
  SDL_SetModState

## SDL_GetScancodeFromKey()

SDL_Scancode SDL_GetScancodeFromKey | ( | SDL_Keycode | key,
|  | SDL_Keymod * | modstate )

extern

Get the scancode corresponding to the given key code according to the current keyboard layout.

Note that there may be multiple scancode+modifier states that can generate this keycode, this will just return the first one found.

Parameters

  key | the desired SDL_Keycode to query.
  modstate | a pointer to the modifier state that would be used when the scancode generates this key, may be NULL.

Returns
  the SDL_Scancode that corresponds to the given SDL_Keycode.

\threadsafety This function is not thread safe.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_GetKeyFromScancode
  SDL_GetScancodeName

## SDL_GetScancodeFromName()

SDL_Scancode SDL_GetScancodeFromName | ( | const char * | name | ) |

extern

Get a scancode from a human-readable name.

Parameters

  name | the human-readable scancode name.

Returns
  the SDL_Scancode, or SDL_SCANCODE_UNKNOWN if the name wasn't recognized; call SDL_GetError() for more information.

\threadsafety This function is not thread safe.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_GetKeyFromName
  SDL_GetScancodeFromKey
  SDL_GetScancodeName

## SDL_GetScancodeName()

const char * SDL_GetScancodeName | ( | SDL_Scancode | scancode | ) |

extern

Get a human-readable name for a scancode.

Warning: The returned name is by design not stable across platforms, e.g. the name for SDL_SCANCODE_LGUI is "Left GUI" under Linux but "Left Windows" under Microsoft Windows, and some scancodes like SDL_SCANCODE_NONUSBACKSLASH don't have any name at all. There are even scancodes that share names, e.g. SDL_SCANCODE_RETURN and SDL_SCANCODE_RETURN2 (both called "Return"). This function is therefore unsuitable for creating a stable cross-platform two-way mapping between strings and scancodes.

Parameters

  scancode | the desired SDL_Scancode to query.

Returns
  a pointer to the name for the scancode. If the scancode doesn't have a name this function returns an empty string ("").

\threadsafety This function is not thread safe.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_GetScancodeFromKey
  SDL_GetScancodeFromName
  SDL_SetScancodeName

## SDL_GetTextInputArea()

bool SDL_GetTextInputArea | ( | SDL_Window * | window,
|  | SDL_Rect * | rect,
|  | int * | cursor )

extern

Get the area used to type Unicode text input.

This returns the values previously set by SDL_SetTextInputArea().

Parameters

  window | the window for which to query the text input area.
  rect | a pointer to an SDL_Rect filled in with the text input area, may be NULL.
  cursor | a pointer to the offset of the current cursor location relative to rect->x, may be NULL.

Returns
  true on success or false on failure; call SDL_GetError() for more information.

\threadsafety This function should only be called on the main thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_SetTextInputArea

References window.

## SDL_HasKeyboard()

bool SDL_HasKeyboard | ( | void |  | ) |

extern

Return whether a keyboard is currently connected.

Returns
  true if a keyboard is connected, false otherwise.

\threadsafety This function should only be called on the main thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_GetKeyboards

## SDL_HasScreenKeyboardSupport()

bool SDL_HasScreenKeyboardSupport | ( | void |  | ) |

extern

Check whether the platform has screen keyboard support.

Returns
  true if the platform has some screen keyboard support or false if not.

\threadsafety This function should only be called on the main thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_StartTextInput
  SDL_ScreenKeyboardShown

## SDL_ResetKeyboard()

void SDL_ResetKeyboard | ( | void |  | ) |

extern

Clear the state of the keyboard.

This function will generate key up events for all pressed keys.

\threadsafety This function should only be called on the main thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_GetKeyboardState

## SDL_ScreenKeyboardShown()

bool SDL_ScreenKeyboardShown | ( | SDL_Window * | window | ) |

extern

Check whether the screen keyboard is shown for given window.

Parameters

  window | the window for which screen keyboard should be queried.

Returns
  true if screen keyboard is shown or false if not.

\threadsafety This function should only be called on the main thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_HasScreenKeyboardSupport

References window.

## SDL_SetModState()

void SDL_SetModState | ( | SDL_Keymod | modstate | ) |

extern

Set the current key modifier state for the keyboard.

The inverse of SDL_GetModState(), SDL_SetModState() allows you to impose modifier key states on your application. Simply pass your desired modifier states into modstate. This value may be a bitwise, OR'd combination of SDL_Keymod values.

This does not change the keyboard state, only the key modifier flags that SDL reports.

Parameters

  modstate | the desired SDL_Keymod for the keyboard.

\threadsafety It is safe to call this function from any thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_GetModState

## SDL_SetScancodeName()

bool SDL_SetScancodeName | ( | SDL_Scancode | scancode,
|  | const char * | name )

extern

Set a human-readable name for a scancode.

Parameters

  scancode | the desired SDL_Scancode.
  name | the name to use for the scancode, encoded as UTF-8. The string is not copied, so the pointer given to this function must stay valid while SDL is being used.

Returns
  true on success or false on failure; call SDL_GetError() for more information.

\threadsafety This function is not thread safe.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_GetScancodeName

## SDL_SetTextInputArea()

bool SDL_SetTextInputArea | ( | SDL_Window * | window,
|  | const SDL_Rect * | rect,
|  | int | cursor )

extern

Set the area used to type Unicode text input.

Native input methods may place a window with word suggestions near the cursor, without covering the text being entered.

Parameters

  window | the window for which to set the text input area.
  rect | the SDL_Rect representing the text input area, in window coordinates, or NULL to clear it.
  cursor | the offset of the current cursor location relative to rect->x, in window coordinates.

Returns
  true on success or false on failure; call SDL_GetError() for more information.

\threadsafety This function should only be called on the main thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_GetTextInputArea
  SDL_StartTextInput

References window.

## SDL_StartTextInput()

bool SDL_StartTextInput | ( | SDL_Window * | window | ) |

extern

Start accepting Unicode text input events in a window.

This function will enable text input (SDL_EVENT_TEXT_INPUT and SDL_EVENT_TEXT_EDITING events) in the specified window. Please use this function paired with SDL_StopTextInput().

Text input events are not received by default.

On some platforms using this function shows the screen keyboard and/or activates an IME, which can prevent some key press events from being passed through.

Parameters

  window | the window to enable text input.

Returns
  true on success or false on failure; call SDL_GetError() for more information.

\threadsafety This function should only be called on the main thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_SetTextInputArea
  SDL_StartTextInputWithProperties
  SDL_StopTextInput
  SDL_TextInputActive

References window.

## SDL_StartTextInputWithProperties()

bool SDL_StartTextInputWithProperties | ( | SDL_Window * | window,
|  | SDL_PropertiesID | props )

extern

Start accepting Unicode text input events in a window, with properties describing the input.

This function will enable text input (SDL_EVENT_TEXT_INPUT and SDL_EVENT_TEXT_EDITING events) in the specified window. Please use this function paired with SDL_StopTextInput().

Text input events are not received by default.

On some platforms using this function shows the screen keyboard and/or activates an IME, which can prevent some key press events from being passed through.

These are the supported properties:

- SDL_PROP_TEXTINPUT_TYPE_NUMBER - an SDL_TextInputType value that describes text being input, defaults to SDL_TEXTINPUT_TYPE_TEXT.
- SDL_PROP_TEXTINPUT_CAPITALIZATION_NUMBER - an SDL_Capitalization value that describes how text should be capitalized, defaults to SDL_CAPITALIZE_SENTENCES for normal text entry, SDL_CAPITALIZE_WORDS for SDL_TEXTINPUT_TYPE_TEXT_NAME, and SDL_CAPITALIZE_NONE for e-mail addresses, usernames, and passwords.
- SDL_PROP_TEXTINPUT_AUTOCORRECT_BOOLEAN - true to enable auto completion and auto correction, defaults to true.
- SDL_PROP_TEXTINPUT_MULTILINE_BOOLEAN - true if multiple lines of text are allowed. This defaults to true if SDL_HINT_RETURN_KEY_HIDES_IME is "0" or is not set, and defaults to false if SDL_HINT_RETURN_KEY_HIDES_IME is "1".

On Android you can directly specify the input type:

- SDL_PROP_TEXTINPUT_ANDROID_INPUTTYPE_NUMBER - the text input type to use, overriding other properties. This is documented at https://developer.android.com/reference/android/text/InputType

Parameters

  window | the window to enable text input.
  props | the properties to use.

Returns
  true on success or false on failure; call SDL_GetError() for more information.

\threadsafety This function should only be called on the main thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_SetTextInputArea
  SDL_StartTextInput
  SDL_StopTextInput
  SDL_TextInputActive

References window.

## SDL_StopTextInput()

bool SDL_StopTextInput | ( | SDL_Window * | window | ) |

extern

Stop receiving any text input events in a window.

If SDL_StartTextInput() showed the screen keyboard, this function will hide it.

Parameters

  window | the window to disable text input.

Returns
  true on success or false on failure; call SDL_GetError() for more information.

\threadsafety This function should only be called on the main thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_StartTextInput

References window.

## SDL_TextInputActive()

bool SDL_TextInputActive | ( | SDL_Window * | window | ) |

extern

Check whether or not Unicode text input events are enabled for a window.

Parameters

  window | the window to check.

Returns
  true if text input events are enabled else false.

\threadsafety This function should only be called on the main thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_StartTextInput

References window.