Keyboard routines are implemented in <lua_kbd.c>. Header file is: <lua_kbd.h>.

Most of keyboard routines are ready.

 

Keyboard routines

 

The Allegro keyboard handler provides both buffered input and a set of flags storing the current state of each key. Note that it is not possible to correctly detect every combination of keys, due to the design of the PC keyboard. Up to two or three keys at a time will work fine, but if you press more than that the extras are likely to be ignored (exactly which combinations are possible seems to vary from one keyboard to another).

On some platforms (like DOS and Windows), Allegro requires the user to specify the language of the keyboard mapping because it is impossible to obtain this information from the OS, otherwise the default US keyboard mapping will be used. Allegro comes with a prepackaged `keyboard.dat' file which you can put along with your binary. If this file is present, Allegro will be able to extract the keyboard mapping information stored there. However, the end user still needs to select which keyboard mapping to use. This can be acomplished through the keyboard variable of the system section in a standard `allegro.cfg' configuration file. Read chapter "Configuration routines" for more information about this.


bool kbd.install( )

Installs the Allegro keyboard interrupt handler. You must call this before using any of the keyboard input routines. Once you have set up the Allegro handler, you can no longer use operating system calls or C library functions to access the keyboard.

Note that on some platforms the keyboard won't work unless you have set a graphics mode, even if this function returns a success value before calling set_gfx_mode. This can happen in environments with graphic windowed modes, since Allegro usually reads the keyboard through the graphical window (which appears after the set_gfx_call). Example:

      allegro.init()
      allegro.install_timer()
      kbd.install()
      -- We are not 100% sure we can read the keyboard yet! 
      if (not allegro.set_gfx_mode(GFX_AUTODETECT, 640, 480, 0, 0)) then
         abort_on_error("Couldn't set graphic mode!") 
 end

 -- Now we are guaranteed to be able to read the keyboard. 
 kbd.readkey();

Return value: Returns true on success, or a false on failure (but you may decide not to check the return value as this function is very unlikely to fail).

 

kbd.remove( )

Removes the keyboard handler, returning control to the operating system. You don't normally need to bother calling this, because allegro.exit( ) will do it for you. However, you might want to call this during runtime if you want to change the keyboard mapping on those platforms were keyboard mappings are needed. You would first modify the configuration variable holding the keyboard mapping and then reinstall the keyboard handler.

 Example:

      kbd.remove( )
      -- Switch to Spanish keyboard mapping. 
      allegro.set_config_string("system", "keyboard", "es")
      kbd.install()
void install_keyboard_hooks(int (*keypressed)(), int (*readkey)());

This callback is not implemented, and I am not sure if there exists such need of using this.

You should only use this function if you *aren't* using the rest of the keyboard handler. It should be called in the place of install_keyboard(), and lets you provide callback routines to detect and read keypresses, which will be used by the main keypressed() and readkey() functions. This can be useful if you want to use Allegro's GUI code with a custom keyboard handler, as it provides a way for the GUI to get keyboard input from your own code, bypassing the normal Allegro input system.

bool kbd.poll( )        - or -      kbd.poll_keyboard( )

Wherever possible, Allegro will read the keyboard input asynchronously (ie. from inside an interrupt handler), but on some platforms that may not be possible, in which case you must call this routine at regular intervals to update the keyboard state variables.

To help you test your keyboard polling code even if you are programming on a platform that doesn't require it, after the first time that you call this function Allegro will switch into polling mode, so from that point onwards you will have to call this routine in order to get any keyboard input at all, regardless of whether the current driver actually needs to be polled or not.

The keypressed(), readkey(), and ureadkey() functions call poll_keyboard() automatically, so you only need to use this function when accessing the key[] array and key_shifts variable.

Return value: Returns true on success, or a false on failure (ie. no keyboard driver installed).

 

bool kbd.needs_poll( )    - or -    kbd.keyboard_needs_poll( )

Returns TRUE if the current keyboard driver is operating in polling mode.

 

bool kbd.keystate(scancode)

Returns a state of a key from allegro key[KEY_MAX] array.

key[KEY_MAX] is an array of flags indicating the state of each key, ordered by scancode. Wherever possible these values will be updated asynchronously, but if kbd.needs_poll( ) returns TRUE, you must manually call kbd.poll( ) to update them with the current input state. The scancodes are defined in Luallegro as a series of KEY_* constants (and are also listed below). For example, you could write:

      if (kbd.keystate(kbd.KEY_SPACE))then
         print("Space is pressed.");
      end
 

Note that the array is supposed to represent which keys are physically held down and which keys are not.

These are the keyboard scancodes (don't forget to write kbd (dot) prefix before each of these constants when writing your code):

      KEY_A ... KEY_Z,
      KEY_0 ... KEY_9,
      KEY_0_PAD ... KEY_9_PAD,
      KEY_F1 ... KEY_F12,

      KEY_ESC, KEY_TILDE, KEY_MINUS, KEY_EQUALS,
      KEY_BACKSPACE, KEY_TAB, KEY_OPENBRACE, KEY_CLOSEBRACE,
      KEY_ENTER, KEY_COLON, KEY_QUOTE, KEY_BACKSLASH,
      KEY_BACKSLASH2, KEY_COMMA, KEY_STOP, KEY_SLASH,
      KEY_SPACE,

      KEY_INSERT, KEY_DEL, KEY_HOME, KEY_END, KEY_PGUP,
      KEY_PGDN, KEY_LEFT, KEY_RIGHT, KEY_UP, KEY_DOWN,

      KEY_SLASH_PAD, KEY_ASTERISK, KEY_MINUS_PAD,
      KEY_PLUS_PAD, KEY_DEL_PAD, KEY_ENTER_PAD,

      KEY_PRTSCR, KEY_PAUSE,

      KEY_ABNT_C1, KEY_YEN, KEY_KANA, KEY_CONVERT, KEY_NOCONVERT,
      KEY_AT, KEY_CIRCUMFLEX, KEY_COLON2, KEY_KANJI,

      KEY_LSHIFT, KEY_RSHIFT,
      KEY_LCONTROL, KEY_RCONTROL,
      KEY_ALT, KEY_ALTGR,
      KEY_LWIN, KEY_RWIN, KEY_MENU,
      KEY_SCRLOCK, KEY_NUMLOCK, KEY_CAPSLOCK

      KEY_EQUALS_PAD, KEY_BACKQUOTE, KEY_SEMICOLON, KEY_COMMAND

Finally, you may notice an `odd' behaviour of the KEY_PAUSE key. This key only generates an interrupt when it is pressed, not when it is released. For this reason, Allegro pretends the pause key is a `state' key, which is the only way to make it usable.

 

extern volatile int key_shifts;
 

Not implemented yet.

Bitmask containing the current state of shift/ctrl/alt, the special Windows keys, and the accent escape characters. Wherever possible this value will be updated asynchronously, but if keyboard_needs_poll() returns TRUE, you must manually call poll_keyboard() to update it with the current input state. This can contain any of the flags:

      KB_SHIFT_FLAG
      KB_CTRL_FLAG
      KB_ALT_FLAG
      KB_LWIN_FLAG
      KB_RWIN_FLAG
      KB_MENU_FLAG
      KB_COMMAND_FLAG
      KB_SCROLOCK_FLAG
      KB_NUMLOCK_FLAG
      KB_CAPSLOCK_FLAG
      KB_INALTSEQ_FLAG
      KB_ACCENT1_FLAG
      KB_ACCENT2_FLAG
      KB_ACCENT3_FLAG
      KB_ACCENT4_FLAG

Example:

      if (key[KEY_W]) {
         if (key_shifts & KB_SHIFT_FLAG) {
            /* User is pressing shift + W. */
         } else {
            /* Hmmm... lower case W then. */
         }
      }
See also: install_keyboard, poll_keyboard, key.
Examples using this: excamera, exkeys.
bool kbd.keypressed( )

Returns TRUE if there are keypresses waiting in the input buffer. You can use this to see if the next call to kbd.readkey( ) is going to block or to simply wait for the user to press a key while you still update the screen possibly drawing some animation. 

Example:

      while not kbd.keypressed() 
      do
         -- Show cool animated logo. 
      end
      -- So he skipped our title screen. 
 
key,scancode =  kbd.readkey( )


Returns the next character from the keyboard buffer, in ASCII format, number value. If the buffer is empty, it waits until a key is pressed. You can see if there are queued keypresses with kbd.keypressed( ). Key contains ASCII code of the key, and scancode is scancode.

For example:

      val,scancode = readkey();
      if (val == string.byte("d")) -- by ASCII code 
         then allegro_message("You pressed 'd'\n") end

      if (scancode == KEY_SPACE)   -- by scancode 
         then allegro_message("You pressed Space\n") end

      if (val == 3)                -- ctrl+letter 
         then allegro_message("You pressed Control+C\n") end

      if (scancode == KEY_X)       -- alt+letter 
         then allegro_message("You pressed Alt+X\n") end
This function cannot return character values greater than 255. If you need to read Unicode input, use kbd.ureadkey( ) instead.
val, scancode = kbd.ureadkey( )

Returns the next character from the keyboard buffer, in Unicode format. If the buffer is empty, it waits until a key is pressed. You can see if there are queued keypresses with keypressed(). The return value contains the Unicode value of the key, and if not NULL, the pointer argument will be set to the scancode. Unlike readkey(), this function is able to return character values greater than 255. Example:
      val,scancode = kbd.ureadkey()
      if (val == 0x00F1) then
         allegro_message("You pressed n with tilde\n")
      end

      if (val == 0x00DF) then
         allegro_message("You pressed sharp s\n")
      end
You should be able to find Unicode character maps at http://www.unicode.org/. Remember that on some platforms you must specify a custom keyboard map (like those found in `keyboard.dat') usually with the help of a configuration file specifying the language mapping (keyboard variable in system section of `allegro.cfg'), or you will get the default US keyboard mapping.
int kbd.scancode_to_ascii(scancode)

Converts the given scancode to an ASCII character for that key (mangling Unicode values), returning the unshifted uncapslocked result of pressing the key, or zero if the key isn't a character-generating key or the lookup can't be done. The lookup cannot be done for keys like the F1-F12 keys or the cursor keys, and some drivers will only return approximate values. Generally, if you want to display the name of a key to the user, you should use the scancode_to_name function.

Example:

      int ascii;
      ...
      ascii = scancode_to_ascii(scancode)
      allegro_message("You pressed '%c'\n", ascii);
 
string kbd.scancode_to_name(scancode);

This function returns a string containing the name of they key with the given scancode. This is useful if you e.g. let the user choose a key for some action, and want to display something more meaningful than just the scancode. Example:
      char const *keyname = scancode_to_name(scancode);
      allegro_message("You pressed the %s key.", keyname);
 
kbd.simulate_keypress(key);

Stuffs a key into the keyboard buffer, just as if the user had pressed it.
The parameter is in the same format returned by kbd.readkey( ). 

Example:

      simulate_keypress(kbd.KEY_SPACE * 256);
      if (readkey() == (kbd.KEY_SPACE * 256)) then
         allegro_message("You simulated Alt+Space\n");
      end
 
kbd.simulate_ukeypress( key , scancode )

Stuffs a key into the keyboard buffer, just as if the user had pressed it.
The parameter is in the same format returned by kbd.ureadkey( ). 

Example:

      
      -- We ignore the scancode simulation. 
      simulate_ukeypress(0x00DF, 0);
      if (kbd.ureadkey() == 0x00DF) then
         allegro_message("You simulated sharp s\n"); 
      end
 
See also: install_keyboard, simulate_keypress, keypressed, ureadkey.
void set_leds(int leds);
 

Not implemented yet.


Overrides the state of the keyboard LED indicators. The parameter is a bitmask containing any of the values KB_SCROLOCK_FLAG, KB_NUMLOCK_FLAG, and KB_CAPSLOCK_FLAG, or -1 to restore the default behavior. Example:

      /* Cycle led indicators. */
      set_leds(KB_SCROLOCK_FLAG);
      rest(1000);
      set_leds(KB_CAPSLOCK_FLAG);
      rest(1000);
      set_leds(KB_NUMLOCK_FLAG);
      rest(1000);
      set_leds(-1);
Note that the led behaviour cannot be guaranteed on some platforms, some leds might not react, or none at all. Therefore you shouldn't rely only on them to communicate information to the user, just in case it doesn't get through.
See also: install_keyboard, key_led_flag.
void set_keyboard_rate(int delay, int repeat);
 

Not implemented yet.


Sets the keyboard repeat rate. Times are given in milliseconds. Passing zero times will disable the key repeat.

See also: install_keyboard, readkey, ureadkey.
kbd.clear_keybuf( )
 

Empties the keyboard buffer. Usually you want to use this in your program before reading keys to avoid previously buffered keys to be returned by calls to kbd.readkey( ) or kbd.ureadkey( ).

 

value = kbd.three_finger_flag(new_optional_value)

The DJGPP keyboard handler provides an 'emergency exit' sequence which you can use to kill off your program. If you are running under DOS this is the three finger salute, ctrl+alt+del. Most multitasking OS's will trap this combination before it reaches the Allegro handler, in which case you can use the alternative ctrl+alt+end. If you want to disable this behaviour in release versions of your program, set this flag to FALSE.

 

extern int key_led_flag;
 

Not implemented yet.


By default, the capslock, numlock, and scroll-lock keys toggle the keyboard LED indicators when they are pressed. If you are using these keys for input in your game (eg. capslock to fire) this may not be desirable, so you can clear this flag to prevent the LED's being updated.

 


Back to main page