Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

5    Low-Level Events Reference

Input Services

Exploring Palm OS®

This chapter describes the lowest level of events that an application may need to handle. It contains the following sections:

Event Constants
Events

Event Constants ^TOP^

Key Modifier Constants ^TOP^

Purpose

Used as the modifiers field of a keyDownEvent.

Declared In

CmnKeyTypes.h

Constants

#define appEvtHookKeyMask 0x0200
System use only.
#define autoRepeatKeyMask 0x0040
Event was generated due to auto-repeat.
#define capsLockMask 0x0002
The handwriting recognition engine is in caps lock mode.
#define commandKeyMask 0x0008
The menu command stroke or a virtual key code.
#define controlKeyMask 0x0020
Not implemented. Reserved.
#define doubleTapKeyMask 0x0080
Not implemented. Reserved.
#define libEvtHookKeyMask 0x0400
System use only.
#define numLockMask 0x0004
The handwriting recognition engine is in numeric-shift mode.
#define optionKeyMask 0x0010
Not implemented. Reserved.
#define poweredOnKeyMask 0x0100
The key press caused the system to be powered on.
#define shiftKeyMask 0x0001
No longer used.
#define willGoUpKeyMask 0x0800
Set if a keyUpEvent will be sent.
#define softwareKeyMask 0x1000
Set if the key event was generated by software (such as the handwriting recognition engine), or clear if it was generated by pressing an actual hard key.

Events ^TOP^

This section describes the lowest level events that send user input to an application. Further events are described in other Exploring Palm OS volumes. See in particular Exploring Palm OS: Programming Basics and Exploring Palm OS: User Interface.

keyDownEvent ^TOP^

Purpose

Sent when the user draws a character in the input area or presses one of the hard keys on the device.

For this event, the data field of the EventType structure contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct _KeyDownEventType {
  wchar32_t chr;
  uint16_t keyCode;
  uint16_t modifiers;
} keyDown

Fields

chr
The character code in the device-specific character encoding.
keyCode
Unused.
modifiers
0, or one or more of the Key Modifier Constants.

Comments

The chr field does not necessarily contain a printable character. If the modifiers field has the commandKeyMask bit set, then the character is a virtual character. Virtual characters generally correspond to an action that the system should take, such as launching a different application or adjusting the contrast.

Example

The structure shown in the prototype section is the definition for the data field of the EventType structure. Access the information stored in the data field in this way:


wchar32_t chr = eventP->data.keyDown.chr; 

keyHoldEvent ^TOP^

Purpose

This event is not currently used.

keyHoldEvent5 ^TOP^

Purpose

Sent when the user holds a hard key on the device.

For this event, the data field of the EventType structure contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct _KeyHoldEventType {
  wchar32_t chr;
  uint16_t keyCode;
  uint16_t modifiers;
} keyHold 

Fields

chr
The character code.
keyCode
Unused.
modifiers
0, or one or more of the Key Modifier Constants.

Comments

This event is sent when a hardware key is held for one second. (Note that the one-second timing may be modified by a Palm OS® licensee.)

Unlike keyDownEvent, keyHoldEvent5 is sent for characters corresponding to hardware buttons only. If the device contains a hardware keyboard, holding a key results in a keyDownEvent and then, one second later, a keyHoldEvent5, and, ultimately, a keyUpEvent. If the user is using a keyboard pinlet, or some other software keyboard, the application receives only the keyDownEvent.

Only one keyHoldEvent5 is sent for each press-and-hold of the key. You do not get a keyHoldEvent5 for each additional second that the key is held.

A keyHoldEvent5 is sent only for the most recently pressed key. For instance, if a key is pressed and held, and then another key is pressed within a second and before the first key is released, the following happens: a keyHoldEvent5 is not sent for the first key, but a keyHoldEvent5 is sent for the second key if it is held for a full second. Note that a keyUpEvent will be generated for both the first and second key as each key is released.

Compatibility

By default, Palm OS Cobalt does not generate this event. Some devices that support a 5-way navigation button—such as the Handspring Treo 600 Smartphone—generate this event. Consult the licensee's developer documentation to see whether this event is generated by a particular device.

keyUpEvent ^TOP^

Purpose

Sent when the user releases a hard key on the device.

For this event, the data field of the EventType structure contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct _KeyUpEventType {
  wchar32_t chr;
  uint16_t keyCode;
  uint16_t modifiers;
} keyUp

Fields

chr
The character code.
keyCode
Unused.
modifiers
0, or one or more of the Key Modifier Constants.

Comments

Unlike the keyDownEvent, the keyUpEvent is sent for characters corresponding to hardware buttons only. If the device contains a hardware keyboard, the application receives keyDownEvent and keyUpEvent for each character typed. If the user is using a keyboard pinlet or some other software keyboard, the application only receives the keyDownEvent.

Example

The structure shown in the prototype section is the definition for the data field of the EventType structure. Access the information stored in the data field in this way:


wchar32_t char = eventP->data.keyUp.chr; 

keyUpEvent5 ^TOP^

Purpose

Sent when the user releases a hard key on the device.

For this event, the data field of the EventType structure contains the same structure as is shown for the keyUpEvent.

Declared In

Event.h

Compatibility

By default, Palm OS Cobalt does not generate this event. Some devices that support a 5-way navigation button—such as the Handspring Treo 600 Smartphone—generate this event. Consult the licensee's developer documentation to see whether this event is generated by a particular device.

penDownEvent ^TOP^

Purpose

Sent when the pen first touches the digitizer.

For this event, the data field of the EventType structure contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct _PenDownMoveEventType {
  uint16_t flags;
  int16_t pressure;
};

Fields

flags
If this field contains evtPenPressureFlag, the pressure field is valid.
pressure
The amount of pressure the user applied to the stylus while pressing the pen. If 0, no pressure was applied. A value greater than or equal to 0x1000 is considered heavy pressure.

The following fields in the EventType structure are set for this event:

penDown
Always true.
tapCount
The number of taps received at this location.
screenX
Draw window-relative position of the pen in standard coordinates (number of coordinates from the left bound of the window).
screenY
Draw window-relative position of the pen in coordinates (number of coordinates from the top of the window).

Comments

Note that this information is passed with all events.

penMoveEvent ^TOP^

Purpose

Sent when the user drags the pen on the digitizer. Note that several kinds of UI objects, such as controls and lists, track the movement directly, and no penMoveEvent is generated.

For this event, the data field of the EventType structure contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct _PenDownMoveEventType {
  uint16_t flags;
  int16_t pressure;
};

Fields

flags
If this field contains evtPenPressureFlag, the pressure field is valid.
pressure
The amount of pressure the user applied to the stylus while pressing the pen. If 0, no pressure was applied. A value greater than or equal to 0x1000 is considered heavy pressure.

The following fields in the EventType structure are set for this event:

penDown
Always true.
tapCount
The number of taps received at this location.
screenX
Draw window-relative position of the pen in standard coordinates (number of coordinates from the left bound of the window).
screenY
Draw window-relative position of the pen in coordinates (number of coordinates from the top of the window).

penUpEvent ^TOP^

Purpose

Sent when the pen is lifted from the digitizer. Note that several kinds of UI objects, such as controls and lists, track the movement directly, and no penUpEvent is generated.

For this event, the data field of the EventType structure contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct _PenUpEventType {
  PointType start;
  PointType end;
} penUp

Fields

start
Draw window-relative start point of the stroke in standard coordinates.
end
Draw window-relative end point of the stroke in standard coordinates.

The following fields in the EventType structure are set for this event:

penDown
Always false.
tapCount
The number of taps received at this location.
screenX
Draw window-relative position of the pen in standard coordinates (number of coordinates from the left bound of the window).
screenY
Draw window-relative position of the pen in coordinates (number of coordinates from the top of the window).