KBDKeyEvent

Syntax

#include <cafe/kbd.h>

typedef struct _KBDKeyEvent
{
  KBDChannel  channel;
  KBDHIDCode  hid;        // USB HID code
  KBDKeyMode  mode;       // for up/down/etc (an enum)
  KBDModState modState;   // modifier state
  KBDUnicode  unicode;    // Unicode, if any
} KBDKeyEvent;

Elements

channel Keyboard channel that generated the event.
hid USB HID code associated with the key.
mode Indicates press/release, repeat.
modState Current keyboard modifier state.
unicode Translated Unicode associated with the key.

Description

The KBDKeyEvent structure contains the keyboard channel that generated the event, the USB HID code associated with the key, the type of key event (see below), the current keyboard modifier state, and the translated Unicode associated with the key.

An application function, if registered with KBDSetKeyCallback, is called with a pointer to this structure. This structure is also returned with a call to KBDGetKey.

For more information on HID codes and Unicodes, refer to the KBD Library Overview : KBDUnicode Values.

The key mode contains a bit vector that indicates whether the key event was a press or release, and whether the event was an initial key press or a repeat key event.

The following macros can be used in a boolean expression to query the state of key event mode.

#define KBD_KEY_MODE_UP(_key_mode)     (!((_key_mode) & KBD_KM_DOWN))
#define KBD_KEY_MODE_DOWN(_key_mode)   ((_key_mode) & KBD_KM_DOWN)
#define KBD_KEY_MODE_REPEAT(_key_mode) ((_key_mode) & KBD_KM_REPEAT)

The modState contained in the key event is a status maintained by the KBD driver as to which modifiers are active. However, do not confuse this with the status of which keyboard modifier keys are actually being pressed. These two may differ. For instance, if the sticky bit state of the keyboard is enabled (see KBDSetAccessSticky), the keyboard modifier keys become toggle buttons and their state of being up or down is no longer consistent with whether the corresponding modifier bit is set.

The following macros can be used to help classify the output Unicode.

#define KBD_UC_IS_PRIVATE(uc) (((uc)>=0xf000 && (uc)<=0xF1FF) || ((uc)==0xFFFF))

The above macro indicates whether the Unicode value is private to the KBD library. (For more information, see the Introduction.) If the value returned by the KBD library is not private, then it is an ASCII/Unicode printing character.

#define KBD_UC_IS_MODIFIER(uc) ((uc)>=0xf000 && (uc)<=0xf01f)

This indicates whether a value represents a modifier key (for example, KBK_Shift and KBK_Num_Lock).

#define KBD_UC_IS_KP_REG_KEY(uc) (((uc)>=0xf100) && ((uc)<=0xf13f))
#define KBD_KP_REG_KEY_TO_ASCII(uc) ((uc)&0x3f)

The first macro indicates whether the Unicode value represents a numeric keypad key that has a regular ASCII/Unicode definition. If so, the second macro will convert the private keypad Unicode value into its regular ASCII/Unicode value. (For example, KBK_Keypad_Asterisk = 0xf12A is converted to "*" = 0x2A.)

#define KBD_UC_IS_KP_NUM_NL_KEY(uc) (((uc)>=KBK_Keypad_0 && ((uc)<=KBK_Keypad_9)))
#define KBD_UC_IS_KP_NUM_UL_KEY(uc) (((uc)>=KBK_Keypad_Insert && ((uc)<=KBK_Keypad_Page_Up)))
#define KBD_KP_NUM_UL_KEY_TO_KP_NUM_NL_KEY(uc) ((KBDUnicode)((uc)-0x40))

These macros indicate whether a value is a keypad digit key with NUM LOCK on (first) or off (second). The third macro converts the second type of a value to the first.

#define KBD_UC_IS_CTRL_KEY  (((uc)>=0xf1c0) && ((uc)<=0xf1df))
#define KBD_CTRL_KEY_TO_ASCII(uc) ((uc)&0x1f)

The first macro indicates whether a value is a control key (Backspace, Tab, Enter, or Escape), and the second converts the private value to a regular ASCII/Unicode value.

If an application requires only the information about raw key presses and releases, it can filter out repeat and pseudo key events using the macros above. Repeat can also be disabled altogether using KBDSetRepeat.

Similarly, if an application wishes to know only about processed Unicode output, it can filter out key-up events and modifier-key presses using the macros above.

Do Not Call From

None.

See Also

KBDSetKeyCallback
KBDGetKey

Revision History

2013/05/08 Automated cleanup pass.
2011/12/21 Moved to Cafe.
2007/03/27 Added KBDHIDCode type.
2007/03/20 Initial version.


CONFIDENTIAL