Keyboard Events

Keyboard events are divided into “key typed” and “key pressed/released” events.

Key Typed Events

“Key typed” events are higher-level and generally are independent of platform (and keyboard layout).  These are generated when a character is typed on the keyboard (typing means both pressing and releasing the character key(s) on the keyboard).

The following function is provided to handle “key typed” events.  It is available for all GUI objects (e.g., Display, Circle, etc.).

Function Description
object.onKeyType(function) When the user types a key (i.e., presses it and releases it), the system calls the provided function.  This function should accept one parameter (a string), which is the key typed, e.g., “a”, “A”, “b”, “B”, “1”,”2”,  “/”, etc.).  Lower and uppercase characters are distinguished.

Key Down/Up Events

“Key down” and “key up” events are lower level events and are generated whenever a key is pressed or released.  As a result, these events may be used for various gaming applications (e.g., when pressing and holding a key does one thing, and when releasing the key does another).

These events are specific to the platform and keyboard layout (i.e., some keys may not work the same on all platforms).  So, test on all desired platforms to make sure keystroke controls work as intended.

“Key down” and “key up”  events are the only way to find out about keys that do not generate character input (e.g., action keys, modifier keys, etc.).

The following functions are provided to handle “key down” and “key up” events.  They are available for all GUI objects (e.g., Display, Circle, etc.).

Function Description
object.onKeyDown(function) When the user presses a key (i.e., pushes a key down), the system calls the provided function.  This function should accept one parameter (an int), which is the virtual key pressed, e.g., VK_SHIFT or VK_A.
NOTE:  This function may be called many times, if a key is held down (according to the keyboard’s key repeat rate).  This is similar to pressing a key and having it repeat many times (e.g., in an editor window).
object.onKeyUp(function) When the user releases a key, the system calls the provided function.  This function should accept one parameter (an int), which is the virtual key released, e.g., VK_SHIFT or VK_A.

“Key down” and “key up” events use virtual key names to report which keyboard key has been pressed, rather than a character generated by the combination of one or more keystrokes (such as “A”, which comes from shift and “a”).

For example, pressing the Shift key will cause a “key down” event with a VK_SHIFT key name; whereas pressing the ‘a’ key will result in a VK_A key name. After the ‘a’ key is released, a “key up” event will be fired with VK_A.

Here is a list of the most important virtual key names:

  • VK_0 through VK_9 are for keys ‘0’ thru ‘9’.
  • VK_A through VK_Z are for keys ‘A’ thru ‘Z’ (regardless of case – upper/lower).
  • VK_LEFT, VK_RIGHT, VK_UP, VK_DOWN are for the arrow keys.
  • VK_F1 through VK_F12 are for the function keys.
  • other keys, such as VK_AMPERSAND, VK_CAPS_LOCK, VK_COMMA, VK_CONTROL, VK_ENTER, VK_MINUS, VK_PLUS, VK_SPACE, and so on.

For a complete list of virtual key names see the KeyEvent Java API documentation.