# Keyboard routines

These functions are declared in the main Allegro header file:

    #include <allegro5/allegro.h>

## API: ALLEGRO_KEYBOARD_STATE

This is a structure that is used to hold a "snapshot" of a keyboard's
state at a particular instant.  It contains the following publically
readable fields:

* display - points to the display that had keyboard focus at the time
the state was saved.  If no display was focused, this points
to NULL.

You cannot read the state of keys directly.  Use the function
[al_key_down].

## Key codes

The constant ALLEGRO_KEY_MAX is always one higher than
the highest key code. So if you want to use the key code as array index
you can do something like this:

    bool pressed_keys[ALLEGRO_KEY_MAX];
    ...
    pressed_keys[key_code] = true;

These are the list of key codes used by Allegro, which are returned in
the event.keyboard.keycode field of the ALLEGRO_KEY_DOWN and
ALLEGRO_KEY_UP events and which you can pass to [al_key_down]:

    ALLEGRO_KEY_A ... ALLEGRO_KEY_Z,
    ALLEGRO_KEY_0 ... ALLEGRO_KEY_9,
    ALLEGRO_KEY_PAD_0 ... ALLEGRO_KEY_PAD_9,
    ALLEGRO_KEY_F1 ... ALLEGRO_KEY_F12,
    ALLEGRO_KEY_ESCAPE,
    ALLEGRO_KEY_TILDE,
    ALLEGRO_KEY_MINUS,
    ALLEGRO_KEY_EQUALS,
    ALLEGRO_KEY_BACKSPACE,
    ALLEGRO_KEY_TAB,
    ALLEGRO_KEY_OPENBRACE, ALLEGRO_KEY_CLOSEBRACE,
    ALLEGRO_KEY_ENTER,
    ALLEGRO_KEY_SEMICOLON,
    ALLEGRO_KEY_QUOTE,
    ALLEGRO_KEY_BACKSLASH, ALLEGRO_KEY_BACKSLASH2,
    ALLEGRO_KEY_COMMA,
    ALLEGRO_KEY_FULLSTOP,
    ALLEGRO_KEY_SLASH,
    ALLEGRO_KEY_SPACE,
    ALLEGRO_KEY_INSERT, ALLEGRO_KEY_DELETE,
    ALLEGRO_KEY_HOME, ALLEGRO_KEY_END,
    ALLEGRO_KEY_PGUP, ALLEGRO_KEY_PGDN,
    ALLEGRO_KEY_LEFT, ALLEGRO_KEY_RIGHT,
    ALLEGRO_KEY_UP, ALLEGRO_KEY_DOWN,
    ALLEGRO_KEY_PAD_SLASH, ALLEGRO_KEY_PAD_ASTERISK,
    ALLEGRO_KEY_PAD_MINUS, ALLEGRO_KEY_PAD_PLUS,
    ALLEGRO_KEY_PAD_DELETE, ALLEGRO_KEY_PAD_ENTER,
    ALLEGRO_KEY_PRINTSCREEN, ALLEGRO_KEY_PAUSE,
    ALLEGRO_KEY_ABNT_C1, ALLEGRO_KEY_YEN, ALLEGRO_KEY_KANA,
    ALLEGRO_KEY_CONVERT, ALLEGRO_KEY_NOCONVERT,
    ALLEGRO_KEY_AT, ALLEGRO_KEY_CIRCUMFLEX,
    ALLEGRO_KEY_COLON2, ALLEGRO_KEY_KANJI,
    ALLEGRO_KEY_LSHIFT, ALLEGRO_KEY_RSHIFT,
    ALLEGRO_KEY_LCTRL, ALLEGRO_KEY_RCTRL,
    ALLEGRO_KEY_ALT, ALLEGRO_KEY_ALTGR,
    ALLEGRO_KEY_LWIN, ALLEGRO_KEY_RWIN,
    ALLEGRO_KEY_MENU,
    ALLEGRO_KEY_SCROLLLOCK,
    ALLEGRO_KEY_NUMLOCK,
    ALLEGRO_KEY_CAPSLOCK
    ALLEGRO_KEY_PAD_EQUALS,
    ALLEGRO_KEY_BACKQUOTE,
    ALLEGRO_KEY_SEMICOLON2,
    ALLEGRO_KEY_COMMAND

## Keyboard modifier flags

    ALLEGRO_KEYMOD_SHIFT
    ALLEGRO_KEYMOD_CTRL
    ALLEGRO_KEYMOD_ALT
    ALLEGRO_KEYMOD_LWIN
    ALLEGRO_KEYMOD_RWIN
    ALLEGRO_KEYMOD_MENU
    ALLEGRO_KEYMOD_ALTGR
    ALLEGRO_KEYMOD_COMMAND
    ALLEGRO_KEYMOD_SCROLLLOCK
    ALLEGRO_KEYMOD_NUMLOCK
    ALLEGRO_KEYMOD_CAPSLOCK
    ALLEGRO_KEYMOD_INALTSEQ
    ALLEGRO_KEYMOD_ACCENT1
    ALLEGRO_KEYMOD_ACCENT2
    ALLEGRO_KEYMOD_ACCENT3
    ALLEGRO_KEYMOD_ACCENT4

The event field 'keyboard.modifiers' is a bitfield composed of these constants.
These indicate the modifier keys which were pressed at the time a character was
typed.

## API: al_install_keyboard

Install a keyboard driver. Returns true if successful. If a driver
was already installed, nothing happens and true is returned.

See also: [al_uninstall_keyboard], [al_is_keyboard_installed]

## API: al_is_keyboard_installed

Returns true if [al_install_keyboard] was called successfully.

## API: al_uninstall_keyboard

Uninstalls the active keyboard driver, if any.  This will
automatically unregister the keyboard event source with any event
queues.

This function is automatically called when Allegro is shut down.

See also: [al_install_keyboard]

## API: al_get_keyboard_state

Save the state of the keyboard specified at the time the function
is called into the structure pointed to by *ret_state*.

See also: [al_key_down], [ALLEGRO_KEYBOARD_STATE]

## API: al_key_down

Return true if the key specified was held down in the state
specified.

See also: [ALLEGRO_KEYBOARD_STATE]

## API: al_keycode_to_name

Converts the given keycode to a description of the key.

## API: al_set_keyboard_leds

Overrides the state of the keyboard LED indicators.
Set to -1 to return to default behavior.
False is returned if the current keyboard driver cannot set LED indicators.

## API: al_get_keyboard_event_source

Retrieve the keyboard event source.

Returns NULL if the keyboard subsystem was not installed.

