Documentation

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.

See also

sDL_GetKeyboards

C declaration

SDL_HasKeyboard, defined at SDL3/SDL_keyboard.h 75:34

Since: 3.2.0

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.

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.

Thread safety

This function should only be called on the main thread.

See also

sDL_GetKeyboardNameForID, sDL_HasKeyboard

C declaration

SDL_GetKeyboards, defined at SDL3/SDL_keyboard.h 98:46

Since: 3.2.0

Get the name of a keyboard.

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

instance_id

the keyboard instance ID.

Returns

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

Thread safety

This function should only be called on the main thread.

See also

sDL_GetKeyboards

C declaration

SDL_GetKeyboardNameForID, defined at SDL3/SDL_keyboard.h 115:42

Since: 3.2.0

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.

C declaration

SDL_GetKeyboardFocus, defined at SDL3/SDL_keyboard.h 126:42

Since: 3.2.0

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.

numkeys

if non-NULL, 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.

See also

SDL_PumpEvents, sDL_ResetKeyboard

C declaration

SDL_GetKeyboardState, defined at SDL3/SDL_keyboard.h 159:42

Since: 3.2.0

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.

See also

sDL_GetKeyboardState

C declaration

SDL_ResetKeyboard, defined at SDL3/SDL_keyboard.h 172:34

Since: 3.2.0

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.

See also

sDL_GetKeyboardState, sDL_SetModState

C declaration

SDL_GetModState, defined at SDL3/SDL_keyboard.h 186:40

Since: 3.2.0

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.

modstate

the desired SDL_Keymod for the keyboard.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetModState

C declaration

SDL_SetModState, defined at SDL3/SDL_keyboard.h 207:34

Since: 3.2.0

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.

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.

Thread safety

This function is not thread safe.

See also

sDL_GetKeyName, sDL_GetScancodeFromKey

C declaration

SDL_GetKeyFromScancode, defined at SDL3/SDL_keyboard.h 231:41

Since: 3.2.0

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.

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.

Thread safety

This function is not thread safe.

See also

sDL_GetKeyFromScancode, sDL_GetScancodeName

C declaration

SDL_GetScancodeFromKey, defined at SDL3/SDL_keyboard.h 252:42

Since: 3.2.0

Set a human-readable name for a scancode.

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.

Thread safety

This function is not thread safe.

See also

sDL_GetScancodeName

C declaration

SDL_SetScancodeName, defined at SDL3/SDL_keyboard.h 270:34

Since: 3.2.0

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.

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

Thread safety

This function is not thread safe.

See also

sDL_GetScancodeFromKey, sDL_GetScancodeFromName, sDL_SetScancodeName

C declaration

SDL_GetScancodeName, defined at SDL3/SDL_keyboard.h 296:42

Since: 3.2.0

Get a scancode from a human-readable name.

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.

Thread safety

This function is not thread safe.

See also

sDL_GetKeyFromName, sDL_GetScancodeFromKey, sDL_GetScancodeName

C declaration

SDL_GetScancodeFromName, defined at SDL3/SDL_keyboard.h 313:42

Since: 3.2.0

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.

key

the desired SDL_Keycode to query.

Returns

a UTF-8 encoded string of the key name.

Thread safety

This function is not thread safe.

See also

sDL_GetKeyFromName, sDL_GetKeyFromScancode, sDL_GetScancodeFromKey

C declaration

SDL_GetKeyName, defined at SDL3/SDL_keyboard.h 333:42

Since: 3.2.0

Get a key code from a human-readable name.

name

the human-readable key name.

Returns

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

Thread safety

This function is not thread safe.

See also

sDL_GetKeyFromScancode, sDL_GetKeyName, sDL_GetScancodeFromName

C declaration

SDL_GetKeyFromName, defined at SDL3/SDL_keyboard.h 350:41

Since: 3.2.0

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.

window

the window to enable text input.

Returns

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

Thread safety

This function should only be called on the main thread.

See also

sDL_SetTextInputArea, sDL_StartTextInputWithProperties, sDL_StopTextInput, sDL_TextInputActive

C declaration

SDL_StartTextInput, defined at SDL3/SDL_keyboard.h 378:34

Since: 3.2.0

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

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.

Thread safety

This function should only be called on the main thread.

See also

sDL_SetTextInputArea, sDL_StartTextInput, sDL_StopTextInput, sDL_TextInputActive

C declaration

SDL_StartTextInputWithProperties, defined at SDL3/SDL_keyboard.h 473:34

Since: 3.2.0

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

window

the window to check.

Returns

true if text input events are enabled else false.

Thread safety

This function should only be called on the main thread.

See also

sDL_StartTextInput

C declaration

SDL_TextInputActive, defined at SDL3/SDL_keyboard.h 493:34

Since: 3.2.0

Stop receiving any text input events in a window.

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

window

the window to disable text input.

Returns

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

Thread safety

This function should only be called on the main thread.

See also

sDL_StartTextInput

C declaration

SDL_StopTextInput, defined at SDL3/SDL_keyboard.h 511:34

Since: 3.2.0

Dismiss the composition window/IME without disabling the subsystem.

window

the window to affect.

Returns

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

Thread safety

This function should only be called on the main thread.

See also

sDL_StartTextInput, sDL_StopTextInput

C declaration

SDL_ClearComposition, defined at SDL3/SDL_keyboard.h 527:34

Since: 3.2.0

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.

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.

Thread safety

This function should only be called on the main thread.

See also

sDL_GetTextInputArea, sDL_StartTextInput

C declaration

SDL_SetTextInputArea, defined at SDL3/SDL_keyboard.h 550:34

Since: 3.2.0

Get the area used to type Unicode text input.

This returns the values previously set by SDL_SetTextInputArea().

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.

Thread safety

This function should only be called on the main thread.

See also

sDL_SetTextInputArea

C declaration

SDL_GetTextInputArea, defined at SDL3/SDL_keyboard.h 571:34

Since: 3.2.0

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.

See also

sDL_StartTextInput, sDL_ScreenKeyboardShown

C declaration

SDL_HasScreenKeyboardSupport, defined at SDL3/SDL_keyboard.h 586:34

Since: 3.2.0

Check whether the screen keyboard is shown for given window.

window

the window for which screen keyboard should be queried.

Returns

true if screen keyboard is shown or false if not.

Thread safety

This function should only be called on the main thread.

See also

sDL_HasScreenKeyboardSupport

C declaration

SDL_ScreenKeyboardShown, defined at SDL3/SDL_keyboard.h 600:34

Since: 3.2.0