NAME

SDL2::keyboard - SDL Keyboard Event Handling

SYNOPSIS

use SDL2 qw[:keyboard];

DESCRIPTION

SDL2::keyboard

Functions

SDL_GetKeyboardFocus( )

Query the window which currently has keyboard focus.

Returns the window with keyboard focus.

SDL_GetKeyboardState( ... )

Get a snapshot of the current state of the keyboard.

my @state = SDL_GetKeyboardState(undef);
if ( $state[SDL_SCANCODE_RETURN] ) {
    printf("<RETURN> is pressed.\n");
}
elsif ( $state[SDL_SCANCODE_RIGHT] && $state[SDL_SCANCODE_UP] ) {
    printf("Right and Up Keys Pressed.\n");
}

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.

Expected parameters include:

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

Returns a pointer to an array of key states.

SDL_GetModState( )

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.

SDL_SetModState( ... )

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.

Expected parameters include:

modstate - the desired SDL_Keymod for the keyboard

SDL_GetKeyFromScancode( ... )

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

See SDL_Keycode for details.

Expected parameters include:

scancode - the desired SDL_Scancode to query

Returns the SDL_Keycode that corresponds to the given SDL_Scancode.

SDL_GetScancodeFromKey( ... )

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

See SDL_Scancode for details.

Expected parameters include:

key - the desired SDL_Keycode to query

Returns the SDL_Scancode that corresponds to the given SDL_Keycode.

SDL_GetScancodeName( ... )

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.

Expected parameters include:

scancode the desired SDL_Scancode to query

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

SDL_GetScancodeFromName( ... )

Get a scancode from a human-readable name.

Expected parameters include:

name - the human-readable scancode name

Returns the SDL_Scancode , or SDL_SCANCODE_UNKNOWN if the name wasn't recognized; call SDL_GetError( ) for more information.

SDL_GetKeyName( ... )

Get a human-readable name for a key.

See SDL_Scancode and SDL_Keycode for details.

Expected parameters include:

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

SDL_GetKeyFromName( ... )

Get a key code from a human-readable name.

Expected parameters include:

name - the human-readable key name

Returns key code, or SDLK_UNKNOWN if the name wasn't recognized; call SDL_GetError( ) for more information.

SDL_StartTextInput( )

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.

SDL_IsTextInputActive( )

Check whether or not Unicode text input events are enabled.

Returns SDL_TRUE if text input events are enabled else SDL_FALSE.

SDL_StopTextInput( )

Stop receiving any text input events.

SDL_SetTextInputRect( )

Set the rectangle used to type Unicode text inputs.

Expected parameters include:

rect - the SDL2::Rect structure representing the rectangle to receive text (ignored if undef)

SDL_HasScreenKeyboardSupport( )

Check whether the platform has screen keyboard support.

Returns SDL_TRUE if the platform has some screen keyboard support or SDL_FALSE if not.

SDL_IsScreenKeyboardShown( ... )

Check whether the screen keyboard is shown for given window.

Expected parameters include:

window - the window for which screen keyboard should be queried

Returns SDL_TRUE if screen keyboard is shown or SDL_FALSE if not.

LICENSE

Copyright (C) Sanko Robinson.

This library is free software; you can redistribute it and/or modify it under the terms found in the Artistic License 2. Other copyrights, terms, and conditions may apply to data transmitted through this module.

AUTHOR

Sanko Robinson <sanko@cpan.org>