NAME¶

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

SYNOPSIS¶

#include <SDL3/SDL_keyboard.h>

bool SDL_StartTextInputWithProperties(SDL_Window *window, SDL_PropertiesID props);

DESCRIPTION¶

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

FUNCTION PARAMETERS¶

window

the window to enable text input.

props

the properties to use.

RETURN VALUE¶

for more information.

THREAD SAFETY¶

This function should only be called on the main thread.

AVAILABILITY¶

This function is available since SDL 3.2.0.

SEE ALSO¶

SDL_SetTextInputArea(3), SDL_StartTextInput(3), SDL_StopTextInput(3), SDL_TextInputActive(3)