SDL keyboard management. More...

Namespaces
namespace	SDL::prop
	Constants for Properties keys.
namespace	SDL::prop::TextInput
	Properties for text input to be used on Window.StartTextInput.

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.
OwnArray< KeyboardID >	SDL::GetKeyboards ()
	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.
std::span< const bool >	SDL::GetKeyboardState ()
	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, bool key_event)
	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::Window::StartTextInput ()
	Start accepting Unicode text input events in a window.
void	SDL::Window::StartTextInput (PropertiesRef props)
	Start accepting Unicode text input events in a window, with properties describing the input.
bool	SDL::Window::IsTextInputActive () const
	Check whether or not Unicode text input events are enabled for a window.
void	SDL::Window::StopTextInput ()
	Stop receiving any text input events in a window.
void	SDL::Window::ClearComposition ()
	Dismiss the composition window/IME without disabling the subsystem.
void	SDL::Window::SetTextInputArea (const RectRaw &rect, int cursor)
	Set the area used to type Unicode text input.
void	SDL::Window::GetTextInputArea (RectRaw rect, int cursor)
	Get the area used to type Unicode text input.
bool	SDL::Window::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

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

Typedef Documentation

◆ Capitalization

using SDL::Capitalization = SDL_Capitalization

Auto capitalization type.

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: Window.StartTextInput

◆ KeyboardID

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.

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 = SDL_TextInputType

Text input type.

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: Window.StartTextInput

Function Documentation

◆ ClearComposition()

void SDL::Window::ClearComposition ( )

inline

Dismiss the composition window/IME without disabling the subsystem.

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: Window.StartTextInput; Window.StopTextInput

◆ GetKeyboardFocus()

WindowRef SDL::GetKeyboardFocus ( )

inline

Query the window which currently has keyboard focus.

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

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 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()

OwnArray< KeyboardID > SDL::GetKeyboards ( )

inline

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.

Returns: a 0 terminated array of keyboards instance IDs on success..

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: GetKeyboardNameForID; HasKeyboard

◆ GetKeyboardState()

std::span< const bool > SDL::GetKeyboardState ( )

inline

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

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

Get the current key modifier state for the keyboard.

Returns: an OR'd combination of the modifier keys 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: GetKeyboardState; SetModState

◆ GetName() [1/2]

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

inline

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.

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

Get a human-readable name for a scancode.

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

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

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::Window::GetTextInputArea	(	RectRaw *	rect,
		int *	cursor )

inline

Get the area used to type Unicode text input.

This returns the values previously set by Window.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: Window.SetTextInputArea

◆ HasKeyboard()

bool SDL::HasKeyboard ( )

inline

Return whether a keyboard is currently connected.

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

Check whether the platform has screen keyboard support.

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: Window.StartTextInput; Window.IsScreenKeyboardShown

◆ IsScreenKeyboardShown()

bool SDL::Window::IsScreenKeyboardShown ( ) const

inline

Check whether the screen keyboard is shown for given window.

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::Window::IsTextInputActive ( ) const

inline

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

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: Window.StartTextInput

◆ Keycode() [1/2]

SDL::Keycode::Keycode	(	Scancode	scancode,
		Keymod	modstate,
		bool	key_event )

inline

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

inline

Get a key code from a human-readable name.

Parameters

name	the human-readable key name.

Postcondition: 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

Clear the state of the keyboard.

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

Get a scancode from a human-readable name.

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

Set the current key modifier state for the keyboard.

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

Set a human-readable name for a scancode.

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::Window::SetTextInputArea	(	const RectRaw &	rect,
		int	cursor )

inline

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

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: Window.GetTextInputArea; Window.StartTextInput

◆ StartTextInput() [1/2]

void SDL::Window::StartTextInput ( )

inline

Start accepting Unicode text input events in a window.

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

◆ StartTextInput() [2/2]

void SDL::Window::StartTextInput ( PropertiesRef props )

inline

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

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

◆ StopTextInput()

void SDL::Window::StopTextInput ( )

inline

Stop receiving any text input events in a window.

If Window.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: Window.StartTextInput

The input is a username.

Namespaces

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