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

Detailed Description

Include file for SDL keyboard event handling

Definition in file SDL_keyboard.h.

Function Documentation

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.

{
    SDL_Keyboard *keyboard = &SDL_keyboard;

    return keyboard->focus;
}

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.

References SDL_Keyboard::keystate, SDL_keyboard, and SDL_NUM_SCANCODES.

{
    SDL_Keyboard *keyboard = &SDL_keyboard;

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

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.

{
    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)];
    }
}

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.

{
    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];
}

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.

{
    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;
    }
}

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.

{
    SDL_Keyboard *keyboard = &SDL_keyboard;

    return (SDL_Keymod) keyboard->modstate;
}

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.

{
    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;
}

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.

{
    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;
}

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.

{
    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 "";
}

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

References SDL_VideoDevice::HasScreenKeyboardSupport, and SDL_FALSE.

{
    if (_this && _this->HasScreenKeyboardSupport) {
        return _this->HasScreenKeyboardSupport(_this);
    }
    return SDL_FALSE;
}

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

References SDL_VideoDevice::IsScreenKeyboardShown, and SDL_FALSE.

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

SDL_bool SDL_IsTextInputActive

(

void

)

Return whether or not Unicode text input events are enabled.

See Also

SDL_StartTextInput()

SDL_StopTextInput()

Definition at line 3751 of file SDL_video.c.

References SDL_ENABLE, SDL_GetEventState, and SDL_TEXTINPUT.

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

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.

{
    SDL_Keyboard *keyboard = &SDL_keyboard;

    keyboard->modstate = modstate;
}

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

References SDL_VideoDevice::SetTextInputRect.

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

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

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

{
    SDL_Window *window;

    /* First, enable text events */
    SDL_EventState(SDL_TEXTINPUT, SDL_ENABLE);
    SDL_EventState(SDL_TEXTEDITING, SDL_ENABLE);

    /* Then show the on-screen keyboard, if any */
    window = SDL_GetFocusWindow();
    if (window && _this && _this->ShowScreenKeyboard) {
        _this->ShowScreenKeyboard(_this, window);
    }

    /* Finally start the text input system */
    if (_this && _this->StartTextInput) {
        _this->StartTextInput(_this);
    }
}

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

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

{
    SDL_Window *window;

    /* Stop the text input system */
    if (_this && _this->StopTextInput) {
        _this->StopTextInput(_this);
    }

    /* Hide the on-screen keyboard, if any */
    window = SDL_GetFocusWindow();
    if (window && _this && _this->HideScreenKeyboard) {
        _this->HideScreenKeyboard(_this, window);
    }

    /* Finally disable text events */
    SDL_EventState(SDL_TEXTINPUT, SDL_DISABLE);
    SDL_EventState(SDL_TEXTEDITING, SDL_DISABLE);
}