SDL keyboard management. More...

Typedefs
using	SDL::KeyboardID = SDL_KeyboardID
	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.

using	SDL::TextInputType = SDL_TextInputType
	Text input type.

using	SDL::Capitalization = SDL_Capitalization
	Auto capitalization type.

Functions
bool	SDL::HasKeyboard ()
	Return whether a keyboard is currently connected.

KeyboardID *	SDL::GetKeyboards (int *count)
	Get a list of currently connected keyboards.

const char *	SDL::GetKeyboardNameForID (KeyboardID instance_id)
	Get the name of a keyboard.

WindowRef	SDL::GetKeyboardFocus ()
	Query the window which currently has keyboard focus.

const bool *	SDL::GetKeyboardState (int *numkeys=nullptr)
	Get a snapshot of the current state of the keyboard.

void	SDL::ResetKeyboard ()
	Clear the state of the keyboard.

Keymod	SDL::GetModState ()
	Get the current key modifier state for the keyboard.

void	SDL::SetModState (Keymod modstate)
	Set the current key modifier state for the keyboard.

bool	SDL::HasScreenKeyboardSupport ()
	Check whether the platform has screen keyboard support.

	SDL::Keycode::Keycode (Scancode scancode, Keymod modstate=0, bool key_event=false)
	Get the key code corresponding to the given scancode according to the current keyboard layout.

	SDL::Keycode::Keycode (StringParam name)
	Get a key code from a human-readable name.

Scancode	SDL::Keycode::GetScancode (Keymod *modstate) const
	Get the scancode corresponding to the given key code according to the current keyboard layout.

void	SDL::Scancode::SetName (StringParam name)
	Set a human-readable name for a scancode.

const char *	SDL::Scancode::GetName () const
	Get a human-readable name for a scancode.

	SDL::Scancode::Scancode (StringParam name)
	Get a scancode from a human-readable name.

const char *	SDL::Keycode::GetName () const
	Get a human-readable name for a key.

void	SDL::WindowBase::StartTextInput ()
	Start accepting Unicode text input events in a window.

void	SDL::WindowBase::StartTextInput (PropertiesBase &props)
	Start accepting Unicode text input events in a window, with properties describing the input.

bool	SDL::WindowBase::IsTextInputActive () const
	Check whether or not Unicode text input events are enabled for a window.

void	SDL::WindowBase::StopTextInput ()
	Stop receiving any text input events in a window.

void	SDL::WindowBase::ClearComposition ()
	Dismiss the composition window/IME without disabling the subsystem.

void	SDL::WindowBase::SetTextInputArea (const SDL_Rect &rect, int cursor)
	Set the area used to type Unicode text input.

void	SDL::WindowBase::GetTextInputArea (Rect rect, int cursor)
	Get the area used to type Unicode text input.

bool	SDL::WindowBase::IsScreenKeyboardShown () const
	Check whether the screen keyboard is shown for given window.

Variables
constexpr TextInputType	SDL::TEXTINPUT_TYPE_TEXT
	The input is text.

constexpr TextInputType	SDL::TEXTINPUT_TYPE_TEXT_NAME
	The input is a person's name.

constexpr TextInputType	SDL::TEXTINPUT_TYPE_TEXT_EMAIL
	The input is an e-mail address.

constexpr TextInputType	SDL::TEXTINPUT_TYPE_TEXT_USERNAME
	The input is a username.

constexpr TextInputType	SDL::TEXTINPUT_TYPE_TEXT_PASSWORD_HIDDEN
	The input is a secure password that is hidden.

constexpr TextInputType	SDL::TEXTINPUT_TYPE_TEXT_PASSWORD_VISIBLE
	The input is a secure password that is visible.

constexpr TextInputType	SDL::TEXTINPUT_TYPE_NUMBER
	The input is a number.

constexpr TextInputType	SDL::TEXTINPUT_TYPE_NUMBER_PASSWORD_HIDDEN
	The input is a secure PIN that is hidden.

constexpr TextInputType	SDL::TEXTINPUT_TYPE_NUMBER_PASSWORD_VISIBLE
	The input is a secure PIN that is visible.

constexpr Capitalization	SDL::CAPITALIZE_NONE
	No auto-capitalization will be done.

constexpr Capitalization	SDL::CAPITALIZE_SENTENCES
	The first letter of sentences will be capitalized.

constexpr Capitalization	SDL::CAPITALIZE_WORDS
	The first letter of words will be capitalized.

constexpr Capitalization	SDL::CAPITALIZE_LETTERS
	All letters will be capitalized.

Detailed Description

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

Typedef Documentation

◆ Capitalization

using SDL::Capitalization = typedef SDL_Capitalization

These are the valid values for 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: WindowBase.StartTextInput

◆ KeyboardID

using SDL::KeyboardID = typedef SDL_KeyboardID

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.

◆ TextInputType

using SDL::TextInputType = typedef SDL_TextInputType

These are the valid values for 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: WindowBase.StartTextInput

Function Documentation

◆ ClearComposition()

void SDL::WindowBase::ClearComposition ( )

inline

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: WindowBase.StartTextInput; WindowBase.StopTextInput

◆ GetKeyboardFocus()

WindowRef SDL::GetKeyboardFocus ( )

inline

Returns: the window with keyboard focus.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

◆ GetKeyboardNameForID()

const char * SDL::GetKeyboardNameForID ( KeyboardID instance_id )

inline

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 nullptr on failure; call GetError() for more information.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: GetKeyboards

◆ GetKeyboards()

KeyboardID * SDL::GetKeyboards ( int * count )

inline

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 nullptr.

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

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: GetKeyboardNameForID; HasKeyboard

◆ GetKeyboardState()

const bool * SDL::GetKeyboardState ( int * numkeys = nullptr )

inline

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 Scancode values.

Use 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 GetKeyboardState() calls.

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

Parameters

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

Returns: a pointer to an array of key states.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: PumpEvents; ResetKeyboard

◆ GetModState()

Keymod SDL::GetModState ( )

inline

Returns: an OR'd combination of the modifier keys for the keyboard. See Keymod for details.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: GetKeyboardState; SetModState

◆ GetName() [1/2]

const char * SDL::Keycode::GetName ( ) const

inline

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

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

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

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: Keycode.Keycode; Keycode.Keycode; Keycode.GetScancode

◆ GetName() [2/2]

const char * SDL::Scancode::GetName ( ) const

inline

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

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

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: Keycode.GetScancode; Scancode.Scancode; Scancode.SetName

◆ GetScancode()

Scancode SDL::Keycode::GetScancode ( Keymod * modstate ) const

inline

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

Parameters

modstate a pointer to the modifier state that would be used when the scancode generates this key, may be nullptr.

Returns: the Scancode that corresponds to the given Keycode.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: Keycode.Keycode; Scancode.GetName

◆ GetTextInputArea()

void SDL::WindowBase::GetTextInputArea	(	Rect *	rect,
		int *	cursor
	)

inline

This returns the values previously set by WindowBase.SetTextInputArea().

Parameters

rect	a pointer to an Rect filled in with the text input area, may be nullptr.
cursor	a pointer to the offset of the current cursor location relative to `rect->x`, may be nullptr.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: WindowBase.SetTextInputArea

◆ HasKeyboard()

bool SDL::HasKeyboard ( )

inline

Returns: true if a keyboard is connected, false otherwise.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: GetKeyboards

◆ HasScreenKeyboardSupport()

bool SDL::HasScreenKeyboardSupport ( )

inline

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

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: WindowBase.StartTextInput; WindowBase.IsScreenKeyboardShown

◆ IsScreenKeyboardShown()

bool SDL::WindowBase::IsScreenKeyboardShown ( ) const

inline

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

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: HasScreenKeyboardSupport

◆ IsTextInputActive()

bool SDL::WindowBase::IsTextInputActive ( ) const

inline

Returns: true if text input events are enabled else false.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: WindowBase.StartTextInput

◆ Keycode() [1/2]

SDL::Keycode::Keycode	(	Scancode	scancode,
		Keymod	modstate = `0`,
		bool	key_event = `false`
	)

inlineexplicit

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 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.

Postcondition: the Keycode that corresponds to the given Scancode.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: Keycode.GetName; Keycode.GetScancode

◆ Keycode() [2/2]

SDL::Keycode::Keycode ( StringParam name )

inlineexplicit

Parameters

name	the human-readable key name.

Postcondition: a valid key code, or SDLK_UNKNOWN if the name wasn't recognized; call GetError() for more information.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: Keycode.Keycode; Keycode.GetName; Scancode.Scancode

◆ ResetKeyboard()

void SDL::ResetKeyboard ( )

inline

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

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: GetKeyboardState

◆ Scancode()

SDL::Scancode::Scancode ( StringParam name )

inline

Parameters

name	the human-readable scancode name.

Postcondition: the Scancode, or SCANCODE_UNKNOWN if the name wasn't recognized; call GetError() for more information.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: Keycode.Keycode; Keycode.GetScancode; Scancode.GetName

◆ SetModState()

void SDL::SetModState ( Keymod modstate )

inline

The inverse of GetModState(), 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 Keymod values.

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

Parameters

modstate the desired Keymod for the keyboard.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: GetModState

◆ SetName()

void SDL::Scancode::SetName ( StringParam name )

inline

Parameters

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.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: Scancode.GetName

◆ SetTextInputArea()

void SDL::WindowBase::SetTextInputArea	(	const SDL_Rect &	rect,
		int	cursor
	)

inline

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

Parameters

rect	the Rect representing the text input area, in window coordinates, or nullptr to clear it.
cursor	the offset of the current cursor location relative to `rect->x`, in window coordinates.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: WindowBase.GetTextInputArea; WindowBase.StartTextInput

◆ StartTextInput() [1/2]

void SDL::WindowBase::StartTextInput ( )

inline

This function will enable text input (EVENT_TEXT_INPUT and EVENT_TEXT_EDITING events) in the specified window. Please use this function paired with WindowBase.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.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: WindowBase.SetTextInputArea; WindowBase.StartTextInput; WindowBase.StopTextInput; WindowBase.IsTextInputActive

◆ StartTextInput() [2/2]

void SDL::WindowBase::StartTextInput ( PropertiesBase & props )

inline

This function will enable text input (EVENT_TEXT_INPUT and EVENT_TEXT_EDITING events) in the specified window. Please use this function paired with WindowBase.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:

prop::TextInput.TYPE_NUMBER - an TextInputType value that describes text being input, defaults to TEXTINPUT_TYPE_TEXT.
prop::TextInput.CAPITALIZATION_NUMBER - an Capitalization value that describes how text should be capitalized, defaults to CAPITALIZE_SENTENCES for normal text entry, CAPITALIZE_WORDS for TEXTINPUT_TYPE_TEXT_NAME, and CAPITALIZE_NONE for e-mail addresses, usernames, and passwords.
prop::TextInput.AUTOCORRECT_BOOLEAN - true to enable auto completion and auto correction, defaults to true.
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:

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

props the properties to use.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: WindowBase.SetTextInputArea; WindowBase.StartTextInput; WindowBase.StopTextInput; WindowBase.IsTextInputActive

◆ StopTextInput()

void SDL::WindowBase::StopTextInput ( )

inline

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

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: WindowBase.StartTextInput

SDL_TEXTINPUT_TYPE_TEXT_USERNAME

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ Capitalization

◆ KeyboardID

◆ TextInputType

Function Documentation

◆ ClearComposition()

◆ GetKeyboardFocus()

◆ GetKeyboardNameForID()

◆ GetKeyboards()

◆ GetKeyboardState()

◆ GetModState()

◆ GetName() [1/2]

◆ GetName() [2/2]

◆ GetScancode()

◆ GetTextInputArea()

◆ HasKeyboard()

◆ HasScreenKeyboardSupport()

◆ IsScreenKeyboardShown()

◆ IsTextInputActive()

◆ Keycode() [1/2]

◆ Keycode() [2/2]

◆ ResetKeyboard()

◆ Scancode()

◆ SetModState()

◆ SetName()

◆ SetTextInputArea()

◆ StartTextInput() [1/2]

◆ StartTextInput() [2/2]

◆ StopTextInput()

Variable Documentation

◆ CAPITALIZE_LETTERS

◆ CAPITALIZE_NONE

◆ CAPITALIZE_SENTENCES

◆ CAPITALIZE_WORDS

◆ TEXTINPUT_TYPE_NUMBER

◆ TEXTINPUT_TYPE_NUMBER_PASSWORD_HIDDEN

◆ TEXTINPUT_TYPE_NUMBER_PASSWORD_VISIBLE

◆ TEXTINPUT_TYPE_TEXT

◆ TEXTINPUT_TYPE_TEXT_EMAIL

◆ TEXTINPUT_TYPE_TEXT_NAME

◆ TEXTINPUT_TYPE_TEXT_PASSWORD_HIDDEN

◆ TEXTINPUT_TYPE_TEXT_PASSWORD_VISIBLE

◆ TEXTINPUT_TYPE_TEXT_USERNAME