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
Key Modifier Constants
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
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
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
Purpose
This event is not currently used.
keyHoldEvent5
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
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
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
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
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
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).
-