#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 896 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 1041 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 936 of file SDL_keyboard.c.

 {
     SDL_Keyboard *keyboard = &SDL_keyboard;
  
     if (((int)scancode) < 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 1002 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 949 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 979 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 964 of file SDL_keyboard.c.

 {
     const char *name;
     if (((int)scancode) < 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_SendKeyboardKeyInternal().

◆ 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 3940 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 3896 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 915 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 3923 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.