SDL 2.0
SDL_keyboard.h File Reference
#include "SDL_stdinc.h"
#include "SDL_error.h"
#include "SDL_keycode.h"
#include "SDL_video.h"
#include "begin_code.h"
#include "close_code.h"
+ 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
 The SDL keysym structure, used in key events. More...
 

Functions

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_IsTextInputActive (void)
 
void SDL_StopTextInput (void)
 
void SDL_ClearComposition (void)
 
SDL_bool SDL_IsTextInputShown (void)
 
void SDL_SetTextInputRect (const SDL_Rect *rect)
 
SDL_bool SDL_HasScreenKeyboardSupport (void)
 
SDL_bool SDL_IsScreenKeyboardShown (SDL_Window *window)
 

Detailed Description

Include file for SDL keyboard event handling

Definition in 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 2.0.22.
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 2.0.0.

◆ 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 2.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 2.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 2.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 2.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 2.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 2.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 2.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 2.0.0.
See also
SDL_GetScancodeFromKey
SDL_GetScancodeFromName

◆ 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 2.0.0.
See also
SDL_StartTextInput
SDL_IsScreenKeyboardShown

◆ SDL_IsScreenKeyboardShown()

SDL_bool SDL_IsScreenKeyboardShown ( 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 2.0.0.
See also
SDL_HasScreenKeyboardSupport

◆ SDL_IsTextInputActive()

SDL_bool SDL_IsTextInputActive ( 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 2.0.0.
See also
SDL_StartTextInput

◆ SDL_IsTextInputShown()

SDL_bool SDL_IsTextInputShown ( void  )
extern

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

Since
This function is available since SDL 2.0.22.

◆ 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 2.24.0.
See also
SDL_GetKeyboardState

◆ 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 2.0.0.
See also
SDL_GetModState

◆ SDL_SetTextInputRect()

void 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)
Since
This function is available since SDL 2.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_TEXTINPUT) and SDL_TextEditingEvent (SDL_TEXTEDITING) events. Please use this function in pair with SDL_StopTextInput().

On some platforms using this function activates the screen keyboard.

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

◆ SDL_StopTextInput()

void SDL_StopTextInput ( void  )
extern

Stop receiving any text input events.

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