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)
 Get the window which currently has keyboard focus. More...
 
const Uint8SDL_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 622 of file SDL_keyboard.c.

References SDL_Keyboard::focus, and SDL_keyboard.

623 {
624  SDL_Keyboard *keyboard = &SDL_keyboard;
625 
626  return keyboard->focus;
627 }
SDL_Window * focus
Definition: SDL_keyboard.c:41
static SDL_Keyboard SDL_keyboard
Definition: SDL_keyboard.c:47

◆ SDL_GetKeyboardState()

const Uint8* SDL_GetKeyboardState ( int *  numkeys)

Get a snapshot of the current state of the keyboard.

Parameters
numkeysif 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:

printf("<RETURN> is pressed.\n");
}

Definition at line 837 of file SDL_keyboard.c.

References SDL_Keyboard::keystate, SDL_keyboard, and SDL_NUM_SCANCODES.

838 {
839  SDL_Keyboard *keyboard = &SDL_keyboard;
840 
841  if (numkeys != (int *) 0) {
842  *numkeys = SDL_NUM_SCANCODES;
843  }
844  return keyboard->keystate;
845 }
static SDL_Keyboard SDL_keyboard
Definition: SDL_keyboard.c:47
Uint8 keystate[SDL_NUM_SCANCODES]
Definition: SDL_keyboard.c:43

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

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

983 {
985 
986  /* Check input */
987  if (name == NULL) {
988  return SDLK_UNKNOWN;
989  }
990 
991  /* If it's a single UTF-8 character, then that's the keycode itself */
992  key = *(const unsigned char *)name;
993  if (key >= 0xF0) {
994  if (SDL_strlen(name) == 4) {
995  int i = 0;
996  key = (Uint16)(name[i]&0x07) << 18;
997  key |= (Uint16)(name[++i]&0x3F) << 12;
998  key |= (Uint16)(name[++i]&0x3F) << 6;
999  key |= (Uint16)(name[++i]&0x3F);
1000  return key;
1001  }
1002  return SDLK_UNKNOWN;
1003  } else if (key >= 0xE0) {
1004  if (SDL_strlen(name) == 3) {
1005  int i = 0;
1006  key = (Uint16)(name[i]&0x0F) << 12;
1007  key |= (Uint16)(name[++i]&0x3F) << 6;
1008  key |= (Uint16)(name[++i]&0x3F);
1009  return key;
1010  }
1011  return SDLK_UNKNOWN;
1012  } else if (key >= 0xC0) {
1013  if (SDL_strlen(name) == 2) {
1014  int i = 0;
1015  key = (Uint16)(name[i]&0x1F) << 6;
1016  key |= (Uint16)(name[++i]&0x3F);
1017  return key;
1018  }
1019  return SDLK_UNKNOWN;
1020  } else {
1021  if (SDL_strlen(name) == 1) {
1022  if (key >= 'A' && key <= 'Z') {
1023  key += 32;
1024  }
1025  return key;
1026  }
1027 
1028  /* Get the scancode for this name, and the associated keycode */
1030  }
1031 }
Sint32 SDL_Keycode
The SDL virtual key representation.
Definition: SDL_keycode.h:45
GLuint const GLchar * name
GLuint64 key
Definition: gl2ext.h:2192
SDL_Scancode SDL_GetScancodeFromName(const char *name)
Get a scancode from a human-readable name.
Definition: SDL_keyboard.c:920
static const SDL_Keycode SDL_default_keymap[SDL_NUM_SCANCODES]
Definition: SDL_keyboard.c:49
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
#define NULL
Definition: begin_code.h:164
#define SDL_strlen
uint16_t Uint16
Definition: SDL_stdinc.h:169

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

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

878 {
879  SDL_Keyboard *keyboard = &SDL_keyboard;
880 
881  if (((int)scancode) < ((int)SDL_SCANCODE_UNKNOWN) || scancode >= SDL_NUM_SCANCODES) {
882  SDL_InvalidParamError("scancode");
883  return 0;
884  }
885 
886  return keyboard->keymap[scancode];
887 }
SDL_Keycode keymap[SDL_NUM_SCANCODES]
Definition: SDL_keyboard.c:44
#define SDL_InvalidParamError(param)
Definition: SDL_error.h:54
static SDL_Keyboard SDL_keyboard
Definition: SDL_keyboard.c:47

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

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.

944 {
945  static char name[8];
946  char *end;
947 
948  if (key & SDLK_SCANCODE_MASK) {
949  return
950  SDL_GetScancodeName((SDL_Scancode) (key & ~SDLK_SCANCODE_MASK));
951  }
952 
953  switch (key) {
954  case SDLK_RETURN:
956  case SDLK_ESCAPE:
958  case SDLK_BACKSPACE:
960  case SDLK_TAB:
962  case SDLK_SPACE:
964  case SDLK_DELETE:
966  default:
967  /* Unaccented letter keys on latin keyboards are normally
968  labeled in upper case (and probably on others like Greek or
969  Cyrillic too, so if you happen to know for sure, please
970  adapt this). */
971  if (key >= 'a' && key <= 'z') {
972  key -= 32;
973  }
974 
975  end = SDL_UCS4ToUTF8((Uint32) key, name);
976  *end = '\0';
977  return name;
978  }
979 }
GLuint GLuint end
Definition: SDL_opengl.h:1571
#define SDLK_SCANCODE_MASK
Definition: SDL_keycode.h:47
uint32_t Uint32
Definition: SDL_stdinc.h:181
GLuint const GLchar * name
GLuint64 key
Definition: gl2ext.h:2192
const char * SDL_GetScancodeName(SDL_Scancode scancode)
Get a human-readable name for a scancode.
Definition: SDL_keyboard.c:905
char * SDL_UCS4ToUTF8(Uint32 ch, char *dst)
Definition: SDL_keyboard.c:520
SDL_Scancode
The SDL keyboard scancode representation.
Definition: SDL_scancode.h:43

◆ SDL_GetModState()

SDL_Keymod SDL_GetModState ( void  )

Get the current key modifier state for the keyboard.

Definition at line 848 of file SDL_keyboard.c.

References SDL_Keyboard::modstate, and SDL_keyboard.

849 {
850  SDL_Keyboard *keyboard = &SDL_keyboard;
851 
852  return (SDL_Keymod) keyboard->modstate;
853 }
Uint16 modstate
Definition: SDL_keyboard.c:42
SDL_Keymod
Enumeration of valid key mods (possibly OR&#39;d together).
Definition: SDL_keycode.h:325
static SDL_Keyboard SDL_keyboard
Definition: SDL_keyboard.c:47

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

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

891 {
892  SDL_Keyboard *keyboard = &SDL_keyboard;
893  SDL_Scancode scancode;
894 
895  for (scancode = SDL_SCANCODE_UNKNOWN; scancode < SDL_NUM_SCANCODES;
896  ++scancode) {
897  if (keyboard->keymap[scancode] == key) {
898  return scancode;
899  }
900  }
901  return SDL_SCANCODE_UNKNOWN;
902 }
SDL_Keycode keymap[SDL_NUM_SCANCODES]
Definition: SDL_keyboard.c:44
GLuint64 key
Definition: gl2ext.h:2192
static SDL_Keyboard SDL_keyboard
Definition: SDL_keyboard.c:47
SDL_Scancode
The SDL keyboard scancode representation.
Definition: SDL_scancode.h:43

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

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

Referenced by SDL_GetKeyFromName().

921 {
922  int i;
923 
924  if (!name || !*name) {
925  SDL_InvalidParamError("name");
926  return SDL_SCANCODE_UNKNOWN;
927  }
928 
929  for (i = 0; i < SDL_arraysize(SDL_scancode_names); ++i) {
930  if (!SDL_scancode_names[i]) {
931  continue;
932  }
933  if (SDL_strcasecmp(name, SDL_scancode_names[i]) == 0) {
934  return (SDL_Scancode)i;
935  }
936  }
937 
938  SDL_InvalidParamError("name");
939  return SDL_SCANCODE_UNKNOWN;
940 }
#define SDL_InvalidParamError(param)
Definition: SDL_error.h:54
#define SDL_strcasecmp
GLuint const GLchar * name
static const char * SDL_scancode_names[SDL_NUM_SCANCODES]
Definition: SDL_keyboard.c:282
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
#define SDL_arraysize(array)
Definition: SDL_stdinc.h:93
SDL_Scancode
The SDL keyboard scancode representation.
Definition: SDL_scancode.h:43

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

References SDL_InvalidParamError, SDL_NUM_SCANCODES, SDL_scancode_names, and SDL_SCANCODE_UNKNOWN.

Referenced by SDL_GetKeyName(), and SDL_SendKeyboardKey().

906 {
907  const char *name;
908  if (((int)scancode) < ((int)SDL_SCANCODE_UNKNOWN) || scancode >= SDL_NUM_SCANCODES) {
909  SDL_InvalidParamError("scancode");
910  return "";
911  }
912 
913  name = SDL_scancode_names[scancode];
914  if (name)
915  return name;
916  else
917  return "";
918 }
#define SDL_InvalidParamError(param)
Definition: SDL_error.h:54
GLuint const GLchar * name
static const char * SDL_scancode_names[SDL_NUM_SCANCODES]
Definition: SDL_keyboard.c:282

◆ 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 3709 of file SDL_video.c.

References SDL_VideoDevice::HasScreenKeyboardSupport, and SDL_FALSE.

Referenced by SDL_VideoInit().

3710 {
3713  }
3714  return SDL_FALSE;
3715 }
static SDL_VideoDevice * _this
Definition: SDL_video.c:121
SDL_bool(* HasScreenKeyboardSupport)(_THIS)
Definition: SDL_sysvideo.h:291

◆ SDL_IsScreenKeyboardShown()

SDL_bool SDL_IsScreenKeyboardShown ( SDL_Window window)

Returns 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 else SDL_FALSE.
See also
SDL_HasScreenKeyboardSupport()

Definition at line 3718 of file SDL_video.c.

References SDL_VideoDevice::IsScreenKeyboardShown, and SDL_FALSE.

3719 {
3720  if (window && _this && _this->IsScreenKeyboardShown) {
3721  return _this->IsScreenKeyboardShown(_this, window);
3722  }
3723  return SDL_FALSE;
3724 }
SDL_bool(* IsScreenKeyboardShown)(_THIS, SDL_Window *window)
Definition: SDL_sysvideo.h:294
static SDL_VideoDevice * _this
Definition: SDL_video.c:121

◆ 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 3674 of file SDL_video.c.

References SDL_ENABLE, SDL_GetEventState, and SDL_TEXTINPUT.

3675 {
3677 }
#define SDL_ENABLE
Definition: SDL_events.h:722
#define SDL_GetEventState(type)
Definition: SDL_events.h:735

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

References SDL_Keyboard::modstate, and SDL_keyboard.

857 {
858  SDL_Keyboard *keyboard = &SDL_keyboard;
859 
860  keyboard->modstate = modstate;
861 }
Uint16 modstate
Definition: SDL_keyboard.c:42
static SDL_Keyboard SDL_keyboard
Definition: SDL_keyboard.c:47

◆ 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 3701 of file SDL_video.c.

References SDL_VideoDevice::SetTextInputRect.

3702 {
3703  if (_this && _this->SetTextInputRect) {
3704  _this->SetTextInputRect(_this, rect);
3705  }
3706 }
static SDL_VideoDevice * _this
Definition: SDL_video.c:121
void(* SetTextInputRect)(_THIS, SDL_Rect *rect)
Definition: SDL_sysvideo.h:288

◆ 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 3653 of file SDL_video.c.

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

Referenced by SDL_VideoInit().

3654 {
3655  SDL_Window *window;
3656 
3657  /* First, enable text events */
3660 
3661  /* Then show the on-screen keyboard, if any */
3662  window = SDL_GetFocusWindow();
3663  if (window && _this && _this->ShowScreenKeyboard) {
3664  _this->ShowScreenKeyboard(_this, window);
3665  }
3666 
3667  /* Finally start the text input system */
3668  if (_this && _this->StartTextInput) {
3670  }
3671 }
SDL_Window * SDL_GetFocusWindow(void)
Definition: SDL_video.c:2594
#define SDL_ENABLE
Definition: SDL_events.h:722
void(* StartTextInput)(_THIS)
Definition: SDL_sysvideo.h:286
static SDL_VideoDevice * _this
Definition: SDL_video.c:121
EGLSurface EGLNativeWindowType * window
Definition: eglext.h:1025
void(* ShowScreenKeyboard)(_THIS, SDL_Window *window)
Definition: SDL_sysvideo.h:292
The type used to identify a window.
Definition: SDL_sysvideo.h:73
#define SDL_EventState

◆ 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 3680 of file SDL_video.c.

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

3681 {
3682  SDL_Window *window;
3683 
3684  /* Stop the text input system */
3685  if (_this && _this->StopTextInput) {
3687  }
3688 
3689  /* Hide the on-screen keyboard, if any */
3690  window = SDL_GetFocusWindow();
3691  if (window && _this && _this->HideScreenKeyboard) {
3692  _this->HideScreenKeyboard(_this, window);
3693  }
3694 
3695  /* Finally disable text events */
3698 }
SDL_Window * SDL_GetFocusWindow(void)
Definition: SDL_video.c:2594
static SDL_VideoDevice * _this
Definition: SDL_video.c:121
void(* StopTextInput)(_THIS)
Definition: SDL_sysvideo.h:287
#define SDL_DISABLE
Definition: SDL_events.h:721
EGLSurface EGLNativeWindowType * window
Definition: eglext.h:1025
The type used to identify a window.
Definition: SDL_sysvideo.h:73
#define SDL_EventState
void(* HideScreenKeyboard)(_THIS, SDL_Window *window)
Definition: SDL_sysvideo.h:293