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_Window * | SDL_GetKeyboardFocus (void)
| Get the window which currently has keyboard focus. More...
const Uint8 * | SDL_GetKeyboardState (int *numkeys)
| Get a snapshot of the current state of the keyboard. More...
SDL_Keymod | SDL_GetModState (void)
| Get the current key modifier state for the keyboard. More...
void | SDL_SetModState (SDL_Keymod modstate)
| Set the current key modifier state for the keyboard. More...
SDL_Keycode | SDL_GetKeyFromScancode (SDL_Scancode scancode)
| Get the key code corresponding to the given scancode according to the current keyboard layout. More...
SDL_Scancode | SDL_GetScancodeFromKey (SDL_Keycode key)
| Get the scancode corresponding to the given key code according to the current keyboard layout. More...
const char * | SDL_GetScancodeName (SDL_Scancode scancode)
| Get a human-readable name for a scancode. More...
SDL_Scancode | SDL_GetScancodeFromName (const char *name)
| Get a scancode from a human-readable name. More...
const char * | SDL_GetKeyName (SDL_Keycode key)
| Get a human-readable name for a key. More...
SDL_Keycode | SDL_GetKeyFromName (const char *name)
| Get a key code from a human-readable name. More...
void | SDL_StartTextInput (void)
| Start accepting Unicode text input events. This function will show the on-screen keyboard if supported. More...
SDL_bool | SDL_IsTextInputActive (void)
| Return whether or not Unicode text input events are enabled. More...
void | SDL_StopTextInput (void)
| Stop receiving any text input events. This function will hide the on-screen keyboard if supported. More...
void | SDL_SetTextInputRect (SDL_Rect *rect)
| Set the rectangle used to type Unicode text inputs. This is used as a hint for IME and on-screen keyboard placement. More...
SDL_bool | SDL_HasScreenKeyboardSupport (void)
| Returns whether the platform has some screen keyboard support. More...
SDL_bool | SDL_IsScreenKeyboardShown (SDL_Window *window)
| Returns whether the screen keyboard is shown for given window. More...

## Detailed Description

Include file for SDL keyboard event handling

Definition in file SDL_keyboard.h.

## Function Documentation

## SDL_GetKeyboardFocus()

SDL_Window* SDL_GetKeyboardFocus | ( | void |  | ) |

Get the window which currently has keyboard focus.

Definition at line 247 of file SDL_dynapi_procs.h.

References SDL_Keyboard::focus, and SDL_keyboard.

## SDL_GetKeyboardState()

const Uint8* SDL_GetKeyboardState | ( | int * | numkeys | ) |

Get a snapshot of the current state of the keyboard.

Parameters

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

Returns
  An array of key states. Indexes into this array are obtained by using SDL_Scancode values.

Example:

const Uint8 *state = SDL_GetKeyboardState(NULL);
if ( state[SDL_SCANCODE_RETURN] ) {
printf("<RETURN> is pressed.\n");
}

Definition at line 837 of file SDL_keyboard.c.

{
SDL_Keyboard *keyboard = &SDL_keyboard;
if (numkeys != (int *) 0) {
*numkeys = SDL_NUM_SCANCODES;
}
return keyboard->keystate;
}

References SDL_Keyboard::keystate, SDL_keyboard, and SDL_NUM_SCANCODES.

## SDL_GetKeyFromName()

SDL_Keycode SDL_GetKeyFromName | ( | const char * | name | ) |

Get a key code from a human-readable name.

Returns
  key code, or SDLK_UNKNOWN if the name wasn't recognized

See also
  SDL_Keycode

Definition at line 982 of file SDL_keyboard.c.

{
SDL_Keycode key;
/* Check input */
if (name == NULL) {
return SDLK_UNKNOWN;
}
/* If it's a single UTF-8 character, then that's the keycode itself */
key = *(const unsigned char *)name;
if (key >= 0xF0) {
if (SDL_strlen(name) == 4) {
int i = 0;
key = (Uint16)(name[i]&0x07) << 18;
key |= (Uint16)(name[++i]&0x3F) << 12;
key |= (Uint16)(name[++i]&0x3F) << 6;
key |= (Uint16)(name[++i]&0x3F);
return key;
}
return SDLK_UNKNOWN;
} else if (key >= 0xE0) {
if (SDL_strlen(name) == 3) {
int i = 0;
key = (Uint16)(name[i]&0x0F) << 12;
key |= (Uint16)(name[++i]&0x3F) << 6;
key |= (Uint16)(name[++i]&0x3F);
return key;
}
return SDLK_UNKNOWN;
} else if (key >= 0xC0) {
if (SDL_strlen(name) == 2) {
int i = 0;
key = (Uint16)(name[i]&0x1F) << 6;
key |= (Uint16)(name[++i]&0x3F);
return key;
}
return SDLK_UNKNOWN;
} else {
if (SDL_strlen(name) == 1) {
if (key >= 'A' && key <= 'Z') {
key += 32;
}
return key;
}
/* Get the scancode for this name, and the associated keycode */
return SDL_default_keymap[SDL_GetScancodeFromName(name)];
}
}

References i, NULL, SDL_default_keymap, SDL_GetScancodeFromName(), SDL_strlen, and SDLK_UNKNOWN.

## SDL_GetKeyFromScancode()

SDL_Keycode SDL_GetKeyFromScancode | ( | SDL_Scancode | scancode | ) |

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

See SDL_Keycode for details.

See also
  SDL_GetKeyName()

Definition at line 877 of file SDL_keyboard.c.

{
SDL_Keyboard *keyboard = &SDL_keyboard;
if (((int)scancode) < ((int)SDL_SCANCODE_UNKNOWN) || scancode >= SDL_NUM_SCANCODES) {
SDL_InvalidParamError("scancode");
return 0;
}
return keyboard->keymap[scancode];
}

References SDL_Keyboard::keymap, SDL_InvalidParamError, SDL_keyboard, SDL_NUM_SCANCODES, and SDL_SCANCODE_UNKNOWN.

## SDL_GetKeyName()

const char* SDL_GetKeyName | ( | SDL_Keycode | key | ) |

Get a human-readable name for a key.

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

See also
  SDL_Keycode

Definition at line 943 of file SDL_keyboard.c.

{
static char name[8];
char *end;
if (key & SDLK_SCANCODE_MASK) {
return
SDL_GetScancodeName((SDL_Scancode) (key & ~SDLK_SCANCODE_MASK));
}
switch (key) {
case SDLK_RETURN:
return SDL_GetScancodeName(SDL_SCANCODE_RETURN);
case SDLK_ESCAPE:
return SDL_GetScancodeName(SDL_SCANCODE_ESCAPE);
case SDLK_BACKSPACE:
return SDL_GetScancodeName(SDL_SCANCODE_BACKSPACE);
case SDLK_TAB:
return SDL_GetScancodeName(SDL_SCANCODE_TAB);
case SDLK_SPACE:
return SDL_GetScancodeName(SDL_SCANCODE_SPACE);
case SDLK_DELETE:
return SDL_GetScancodeName(SDL_SCANCODE_DELETE);
default:
/* Unaccented letter keys on latin keyboards are normally
labeled in upper case (and probably on others like Greek or
Cyrillic too, so if you happen to know for sure, please
adapt this). */
if (key >= 'a' && key <= 'z') {
key -= 32;
}
end = SDL_UCS4ToUTF8((Uint32) key, name);
*end = '\0';
return name;
}
}

References SDL_GetScancodeName(), SDL_SCANCODE_BACKSPACE, SDL_SCANCODE_DELETE, SDL_SCANCODE_ESCAPE, SDL_SCANCODE_RETURN, SDL_SCANCODE_SPACE, SDL_SCANCODE_TAB, SDL_UCS4ToUTF8(), SDLK_BACKSPACE, SDLK_DELETE, SDLK_ESCAPE, SDLK_RETURN, SDLK_SCANCODE_MASK, SDLK_SPACE, and SDLK_TAB.

## SDL_GetModState()

SDL_Keymod SDL_GetModState | ( | void |  | ) |

Get the current key modifier state for the keyboard.

Definition at line 249 of file SDL_dynapi_procs.h.

References SDL_Keyboard::modstate, and SDL_keyboard.

## SDL_GetScancodeFromKey()

SDL_Scancode SDL_GetScancodeFromKey | ( | SDL_Keycode | key | ) |

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

See SDL_Scancode for details.

See also
  SDL_GetScancodeName()

Definition at line 890 of file SDL_keyboard.c.

{
SDL_Keyboard *keyboard = &SDL_keyboard;
SDL_Scancode scancode;
for (scancode = SDL_SCANCODE_UNKNOWN; scancode < SDL_NUM_SCANCODES;
++scancode) {
if (keyboard->keymap[scancode] == key) {
return scancode;
}
}
return SDL_SCANCODE_UNKNOWN;
}

References SDL_Keyboard::keymap, SDL_keyboard, SDL_NUM_SCANCODES, and SDL_SCANCODE_UNKNOWN.

## SDL_GetScancodeFromName()

SDL_Scancode SDL_GetScancodeFromName | ( | const char * | name | ) |

Get a scancode from a human-readable name.

Returns
  scancode, or SDL_SCANCODE_UNKNOWN if the name wasn't recognized

See also
  SDL_Scancode

Definition at line 920 of file SDL_keyboard.c.

{
int i;
if (!name || !*name) {
SDL_InvalidParamError("name");
return SDL_SCANCODE_UNKNOWN;
}
for (i = 0; i < SDL_arraysize(SDL_scancode_names); ++i) {
if (!SDL_scancode_names[i]) {
continue;
}
if (SDL_strcasecmp(name, SDL_scancode_names[i]) == 0) {
return (SDL_Scancode)i;
}
}
SDL_InvalidParamError("name");
return SDL_SCANCODE_UNKNOWN;
}

References i, SDL_arraysize, SDL_InvalidParamError, SDL_scancode_names, SDL_SCANCODE_UNKNOWN, and SDL_strcasecmp.

Referenced by SDL_GetKeyFromName().

## SDL_GetScancodeName()

const char* SDL_GetScancodeName | ( | SDL_Scancode | scancode | ) |

Get a human-readable name for a scancode.

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

See also
  SDL_Scancode

Definition at line 905 of file SDL_keyboard.c.

{
const char *name;
if (((int)scancode) < ((int)SDL_SCANCODE_UNKNOWN) || scancode >= SDL_NUM_SCANCODES) {
SDL_InvalidParamError("scancode");
return "";
}
name = SDL_scancode_names[scancode];
if (name)
return name;
else
return "";
}

References SDL_InvalidParamError, SDL_NUM_SCANCODES, SDL_scancode_names, and SDL_SCANCODE_UNKNOWN.

Referenced by SDL_GetKeyName(), and SDL_SendKeyboardKey().

## SDL_HasScreenKeyboardSupport()

SDL_bool SDL_HasScreenKeyboardSupport | ( | void |  | ) |

Returns whether the platform has some screen keyboard support.

Returns
  SDL_TRUE if some keyboard support is available else SDL_FALSE.

Note
  Not all screen keyboard functions are supported on all platforms.

See also
  SDL_IsScreenKeyboardShown()

Definition at line 261 of file SDL_dynapi_procs.h.

References _this, SDL_VideoDevice::HasScreenKeyboardSupport, and SDL_FALSE.

Referenced by SDL_VideoInit().

## SDL_IsScreenKeyboardShown()

SDL_bool SDL_IsScreenKeyboardShown | ( | SDL_Window * | window | ) |

Returns whether the screen keyboard is shown for given window.

Parameters

  window | The window for which screen keyboard should be queried.

Returns
  SDL_TRUE if screen keyboard is shown else SDL_FALSE.

See also
  SDL_HasScreenKeyboardSupport()

Definition at line 3820 of file SDL_video.c.

{
if (window && _this && _this->IsScreenKeyboardShown) {
return _this->IsScreenKeyboardShown(_this, window);
}
return SDL_FALSE;
}

References _this, SDL_VideoDevice::IsScreenKeyboardShown, and SDL_FALSE.

## SDL_IsTextInputActive()

SDL_bool SDL_IsTextInputActive | ( | void |  | ) |

Return whether or not Unicode text input events are enabled.

See also
  SDL_StartTextInput()
  SDL_StopTextInput()

Definition at line 3776 of file SDL_video.c.

{
return (SDL_GetEventState(SDL_TEXTINPUT) == SDL_ENABLE);
}

References SDL_ENABLE, SDL_GetEventState, and SDL_TEXTINPUT.

## SDL_SetModState()

void SDL_SetModState | ( | SDL_Keymod | modstate | ) |

Set the current key modifier state for the keyboard.

Note
  This does not change the keyboard state, only the key modifier flags.

Definition at line 856 of file SDL_keyboard.c.

{
SDL_Keyboard *keyboard = &SDL_keyboard;
keyboard->modstate = modstate;
}

References SDL_Keyboard::modstate, and SDL_keyboard.

## SDL_SetTextInputRect()

void SDL_SetTextInputRect | ( | SDL_Rect * | rect | ) |

Set the rectangle used to type Unicode text inputs. This is used as a hint for IME and on-screen keyboard placement.

See also
  SDL_StartTextInput()

Definition at line 3803 of file SDL_video.c.

{
if (_this && _this->SetTextInputRect) {
_this->SetTextInputRect(_this, rect);
}
}

References _this, rect, and SDL_VideoDevice::SetTextInputRect.

## SDL_StartTextInput()

void SDL_StartTextInput | ( | void |  | ) |

Start accepting Unicode text input events. This function will show the on-screen keyboard if supported.

See also
  SDL_StopTextInput()
  SDL_SetTextInputRect()
  SDL_HasScreenKeyboardSupport()

Definition at line 257 of file SDL_dynapi_procs.h.

References _this, SDL_ENABLE, SDL_EventState, SDL_GetFocusWindow(), SDL_TEXTEDITING, SDL_TEXTINPUT, SDL_VideoDevice::ShowScreenKeyboard, and SDL_VideoDevice::StartTextInput.

Referenced by SDL_VideoInit().

## SDL_StopTextInput()

void SDL_StopTextInput | ( | void |  | ) |

Stop receiving any text input events. This function will hide the on-screen keyboard if supported.

See also
  SDL_StartTextInput()
  SDL_HasScreenKeyboardSupport()

Definition at line 259 of file SDL_dynapi_procs.h.

References _this, SDL_VideoDevice::HideScreenKeyboard, SDL_DISABLE, SDL_EventState, SDL_GetFocusWindow(), SDL_TEXTEDITING, SDL_TEXTINPUT, and SDL_VideoDevice::StopTextInput.

Uint32
uint32_t Uint32
Definition: SDL_stdinc.h:203
SDL_Keyboard::modstate
Uint16 modstate
Definition: SDL_keyboard.c:42
SDLK_UNKNOWN
@ SDLK_UNKNOWN
Definition: SDL_keycode.h:52
SDL_scancode_names
static const char * SDL_scancode_names[SDL_NUM_SCANCODES]
Definition: SDL_keyboard.c:282
end
GLuint GLuint end
Definition: SDL_opengl.h:1571
NULL
#define NULL
Definition: begin_code.h:167
SDL_Keyboard::keystate
Uint8 keystate[SDL_NUM_SCANCODES]
Definition: SDL_keyboard.c:43
SDL_VideoDevice::SetTextInputRect
void(* SetTextInputRect)(_THIS, SDL_Rect *rect)
Definition: SDL_sysvideo.h:289
SDL_UCS4ToUTF8
char * SDL_UCS4ToUTF8(Uint32 ch, char *dst)
Definition: SDL_keyboard.c:520
SDL_Scancode
SDL_Scancode
The SDL keyboard scancode representation.
Definition: SDL_scancode.h:43
SDL_InvalidParamError
#define SDL_InvalidParamError(param)
Definition: SDL_error.h:54
SDL_SCANCODE_TAB
@ SDL_SCANCODE_TAB
Definition: SDL_scancode.h:95
SDL_ENABLE
#define SDL_ENABLE
Definition: SDL_events.h:759
SDL_Keycode
Sint32 SDL_Keycode
The SDL virtual key representation.
Definition: SDL_keycode.h:45
SDL_strcasecmp
#define SDL_strcasecmp
Definition: SDL_dynapi_overrides.h:419
SDLK_ESCAPE
@ SDLK_ESCAPE
Definition: SDL_keycode.h:55
SDL_FALSE
@ SDL_FALSE
Definition: SDL_stdinc.h:163
SDL_Keyboard
Definition: SDL_keyboard.c:38
_this
static SDL_VideoDevice * _this
Definition: SDL_video.c:118
SDL_SCANCODE_SPACE
@ SDL_SCANCODE_SPACE
Definition: SDL_scancode.h:96
SDL_GetEventState
#define SDL_GetEventState(type)
Definition: SDL_events.h:772
window
EGLSurface EGLNativeWindowType * window
Definition: eglext.h:1025
SDL_TEXTINPUT
@ SDL_TEXTINPUT
Definition: SDL_events.h:99
SDL_default_keymap
static const SDL_Keycode SDL_default_keymap[SDL_NUM_SCANCODES]
Definition: SDL_keyboard.c:49
SDL_Keyboard::keymap
SDL_Keycode keymap[SDL_NUM_SCANCODES]
Definition: SDL_keyboard.c:44
SDL_GetKeyboardState
#define SDL_GetKeyboardState
Definition: SDL_dynapi_overrides.h:217
name
GLuint const GLchar * name
Definition: SDL_opengl_glext.h:660
SDLK_SPACE
@ SDLK_SPACE
Definition: SDL_keycode.h:58
rect
SDL_Rect rect
Definition: testrelative.c:27
SDL_SCANCODE_ESCAPE
@ SDL_SCANCODE_ESCAPE
Definition: SDL_scancode.h:93
Uint16
uint16_t Uint16
Definition: SDL_stdinc.h:191
key
GLuint64 key
Definition: gl2ext.h:2192
SDL_SCANCODE_BACKSPACE
@ SDL_SCANCODE_BACKSPACE
Definition: SDL_scancode.h:94
SDL_GetScancodeName
const char * SDL_GetScancodeName(SDL_Scancode scancode)
Get a human-readable name for a scancode.
Definition: SDL_keyboard.c:905
SDLK_BACKSPACE
@ SDLK_BACKSPACE
Definition: SDL_keycode.h:56
SDL_VideoDevice::IsScreenKeyboardShown
SDL_bool(* IsScreenKeyboardShown)(_THIS, SDL_Window *window)
Definition: SDL_sysvideo.h:295
SDLK_SCANCODE_MASK
#define SDLK_SCANCODE_MASK
Definition: SDL_keycode.h:47
SDL_SCANCODE_UNKNOWN
@ SDL_SCANCODE_UNKNOWN
Definition: SDL_scancode.h:45
SDLK_DELETE
@ SDLK_DELETE
Definition: SDL_keycode.h:148
SDL_arraysize
#define SDL_arraysize(array)
Definition: SDL_stdinc.h:115
SDL_SCANCODE_DELETE
@ SDL_SCANCODE_DELETE
Definition: SDL_scancode.h:173
SDLK_RETURN
@ SDLK_RETURN
Definition: SDL_keycode.h:54
SDLK_TAB
@ SDLK_TAB
Definition: SDL_keycode.h:57
SDL_strlen
#define SDL_strlen
Definition: SDL_dynapi_overrides.h:393
SDL_NUM_SCANCODES
@ SDL_NUM_SCANCODES
Definition: SDL_scancode.h:407
state
struct xkb_state * state
Definition: SDL_waylandsym.h:113
i
return Display return Display Bool Bool int int int return Display XEvent Bool(*) XPointer return Display return Display Drawable _Xconst char unsigned int unsigned int return Display Pixmap Pixmap XColor XColor unsigned int unsigned int return Display _Xconst char char int char return Display Visual unsigned int int int char unsigned int unsigned int in i)
Definition: SDL_x11sym.h:50
SDL_GetScancodeFromName
SDL_Scancode SDL_GetScancodeFromName(const char *name)
Get a scancode from a human-readable name.
Definition: SDL_keyboard.c:920
SDL_SCANCODE_RETURN
@ SDL_SCANCODE_RETURN
Definition: SDL_scancode.h:92
SDL_keyboard
static SDL_Keyboard SDL_keyboard
Definition: SDL_keyboard.c:47
Uint8
uint8_t Uint8
Definition: SDL_stdinc.h:179