SDL 3.0
SDL_keyboard.h File Reference
+ 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.

Data Structures

struct  SDL_Keysym
 

Typedefs

typedef Uint32 SDL_KeyboardID
 

Functions

SDL_bool SDL_HasKeyboard (void)
 
SDL_KeyboardIDSDL_GetKeyboards (int *count)
 
const char * SDL_GetKeyboardInstanceName (SDL_KeyboardID instance_id)
 
SDL_WindowSDL_GetKeyboardFocus (void)
 
const Uint8SDL_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_Scancode SDL_GetScancodeFromKey (SDL_Keycode key)
 
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)
 
void SDL_StartTextInput (void)
 
SDL_bool SDL_TextInputActive (void)
 
void SDL_StopTextInput (void)
 
void SDL_ClearComposition (void)
 
SDL_bool SDL_TextInputShown (void)
 
int SDL_SetTextInputRect (const SDL_Rect *rect)
 
SDL_bool SDL_HasScreenKeyboardSupport (void)
 
SDL_bool SDL_ScreenKeyboardShown (SDL_Window *window)
 

Detailed Description

Include file for SDL keyboard event handling

Definition in file SDL_keyboard.h.

Typedef Documentation

◆ SDL_KeyboardID

Definition at line 42 of file SDL_keyboard.h.

Function Documentation

◆ SDL_ClearComposition()

void SDL_ClearComposition ( void  )
extern

Dismiss the composition window/IME without disabling the subsystem.

Since
This function is available since SDL 3.0.0.
See also
SDL_StartTextInput
SDL_StopTextInput

◆ SDL_GetKeyboardFocus()

SDL_Window * SDL_GetKeyboardFocus ( void  )
extern

Query the window which currently has keyboard focus.

Returns
the window with keyboard focus.
Since
This function is available since SDL 3.0.0.

◆ SDL_GetKeyboardInstanceName()

const char * SDL_GetKeyboardInstanceName ( SDL_KeyboardID  instance_id)
extern

Get the name of a keyboard.

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

Parameters
instance_idthe keyboard instance ID
Returns
the name of the selected keyboard, or NULL on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.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
counta pointer filled in with the number of keyboards returned
Returns
a 0 terminated array of keyboards instance IDs which should be freed with SDL_free(), or NULL on error; call SDL_GetError() for more details.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetKeyboardInstanceName
SDL_HasKeyboard

◆ SDL_GetKeyboardState()

const Uint8 * 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 1 means that the key is pressed and a value of 0 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
numkeysif non-NULL, receives the length of the returned array
Returns
a pointer to an array of key states.
Since
This function is available since SDL 3.0.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
namethe human-readable key name
Returns
key code, or SDLK_UNKNOWN if the name wasn't recognized; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetKeyFromScancode
SDL_GetKeyName
SDL_GetScancodeFromName

◆ SDL_GetKeyFromScancode()

SDL_Keycode SDL_GetKeyFromScancode ( SDL_Scancode  scancode)
extern

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

See SDL_Keycode for details.

Parameters
scancodethe desired SDL_Scancode to query
Returns
the SDL_Keycode that corresponds to the given SDL_Scancode.
Since
This function is available since SDL 3.0.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.

See SDL_Scancode and SDL_Keycode for details.

Parameters
keythe desired SDL_Keycode to query
Returns
a pointer to a UTF-8 string that stays valid at least until the next call to this function. If you need it around any longer, you must copy it. If the key doesn't have a name, this function returns an empty string ("").
Since
This function is available since SDL 3.0.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. See SDL_Keymod for details.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetKeyboardState
SDL_SetModState

◆ SDL_GetScancodeFromKey()

SDL_Scancode SDL_GetScancodeFromKey ( SDL_Keycode  key)
extern

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

See SDL_Scancode for details.

Parameters
keythe desired SDL_Keycode to query
Returns
the SDL_Scancode that corresponds to the given SDL_Keycode.
Since
This function is available since SDL 3.0.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
namethe human-readable scancode name
Returns
the SDL_Scancode, or SDL_SCANCODE_UNKNOWN if the name wasn't recognized; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.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.

See SDL_Scancode for details.

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
scancodethe 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 ("").
Since
This function is available since SDL 3.0.0.
See also
SDL_GetScancodeFromKey
SDL_GetScancodeFromName

◆ SDL_HasKeyboard()

SDL_bool SDL_HasKeyboard ( void  )
extern

Return whether a keyboard is currently connected.

Returns
SDL_TRUE if a keyboard is connected, SDL_FALSE otherwise.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetKeyboards

◆ SDL_HasScreenKeyboardSupport()

SDL_bool SDL_HasScreenKeyboardSupport ( void  )
extern

Check whether the platform has screen keyboard support.

Returns
SDL_TRUE if the platform has some screen keyboard support or SDL_FALSE if not.
Since
This function is available since SDL 3.0.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.

Since
This function is available since SDL 3.0.0.
See also
SDL_GetKeyboardState

◆ SDL_ScreenKeyboardShown()

SDL_bool SDL_ScreenKeyboardShown ( SDL_Window window)
extern

Check whether the screen keyboard is shown for given window.

Parameters
windowthe window for which screen keyboard should be queried
Returns
SDL_TRUE if screen keyboard is shown or SDL_FALSE if not.
Since
This function is available since SDL 3.0.0.
See also
SDL_HasScreenKeyboardSupport

◆ 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
modstatethe desired SDL_Keymod for the keyboard
Since
This function is available since SDL 3.0.0.
See also
SDL_GetModState

◆ SDL_SetTextInputRect()

int SDL_SetTextInputRect ( const SDL_Rect rect)
extern

Set the rectangle used to type Unicode text inputs.

Native input methods will place a window with word suggestions near it, without covering the text being inputted.

To start text input in a given location, this function is intended to be called before SDL_StartTextInput, although some platforms support moving the rectangle even while text input (and a composition) is active.

Note: If you want to use the system native IME window, try setting hint SDL_HINT_IME_SHOW_UI to 1, otherwise this function won't give you any feedback.

Parameters
rectthe SDL_Rect structure representing the rectangle to receive text (ignored if NULL)
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.
See also
SDL_StartTextInput

◆ SDL_StartTextInput()

void SDL_StartTextInput ( void  )
extern

Start accepting Unicode text input events.

This function will start accepting Unicode text input events in the focused SDL window, and start emitting SDL_TextInputEvent (SDL_EVENT_TEXT_INPUT) and SDL_TextEditingEvent (SDL_EVENT_TEXT_EDITING) events. Please use this function in pair with SDL_StopTextInput().

Text input events are received by default.

On some platforms using this function activates the screen keyboard.

Since
This function is available since SDL 3.0.0.
See also
SDL_SetTextInputRect
SDL_StopTextInput

◆ SDL_StopTextInput()

void SDL_StopTextInput ( void  )
extern

Stop receiving any text input events.

Text input events are received by default.

Since
This function is available since SDL 3.0.0.
See also
SDL_StartTextInput

◆ SDL_TextInputActive()

SDL_bool SDL_TextInputActive ( void  )
extern

Check whether or not Unicode text input events are enabled.

Returns
SDL_TRUE if text input events are enabled else SDL_FALSE.
Since
This function is available since SDL 3.0.0.
See also
SDL_StartTextInput

◆ SDL_TextInputShown()

SDL_bool SDL_TextInputShown ( void  )
extern

Returns if an IME Composite or Candidate window is currently shown.

Returns
SDL_TRUE if shown, else SDL_FALSE
Since
This function is available since SDL 3.0.0.