Palm OS® events are structures (defined in the header files Event.h
, SysEvent.h
, and INetMgr.h
) that the system passes to the application when the user interacts with the graphical user interface. Chapter 3, "Event Loop," in the Palm OS Programmer's Companion, vol. I discusses in detail how this works. This chapter provides reference-style information about each event. First it shows the types used by Palm OS events. Then it discusses the following events in alphabetical order:
|
|
|
|
Event Data Structures
eventsEnum
Purpose
The eventsEnum
enum specifies the possible event types.
Prototype
typedef enum { nilEvent = 0, penDownEvent, penUpEvent, penMoveEvent, keyDownEvent, winEnterEvent, winExitEvent, ctlEnterEvent, ctlExitEvent, ctlSelectEvent, ctlRepeatEvent, lstEnterEvent, lstSelectEvent, lstExitEvent, popSelectEvent, fldEnterEvent, fldHeightChangedEvent, fldChangedEvent, tblEnterEvent, tblSelectEvent, daySelectEvent, menuEvent, appStopEvent = 22, frmLoadEvent, frmOpenEvent, frmGotoEvent, frmUpdateEvent, frmSaveEvent, frmCloseEvent, frmTitleEnterEvent, frmTitleSelectEvent, tblExitEvent, sclEnterEvent, sclExitEvent, sclRepeatEvent, tsmFepModeEvent, attnIndicatorEnterEvent, attnIndicatorSelectEvent, menuCmdBarOpenEvent = 0x0800, menuOpenEvent, menuCloseEvent, frmGadgetEnterEvent, frmGadgetMiscEvent, firstINetLibEvent = 0x1000, firstWebLibEvent = 0x1100, keyUpEvent = 0x4000, keyHoldEvent = 0x4001, frmObjectFocusTakeEvent = 0x4002, frmObjectFocusLostEvent = 0x4003, firstUserEvent = 0x6000, lastUserEvent = 0x7FFF } eventsEnum;
Each of these event types is discussed in alphabetical order below.
EventType Struct
Purpose
The EventType
structure contains all the data associated with a system event. All event types have some common data. Most events also have data specific to those events. The specific data uses a union that is part of the EventType
data structure. The union can have up to 16 bytes of specific data.
The common data is documented below the structure. The Event Reference section gives details on the important data associated with each type of event.
Prototype
typedef struct { eventsEnum eType; Boolean penDown; UInt8 tapCount; Int16 screenX; Int16 screenY; union{ ... } data; } EventType;
Fields
-
eType
- One of the
eventsEnum
constants. Specifies the type of the event. -
penDown
-
true
if the pen was down at the time of the event, otherwisefalse
. -
tapCount
- The number of taps received at this location. This value is used mainly by fields. When the user taps in a text field, two taps selects a word, and three taps selects the entire line.
-
screenX
- Window-relative position of the pen in pixels (number of pixels from the left bound of the window).
-
screenY
- Window-relative position of the pen in pixels (number of pixels from the top left of the window).
-
data
- The specific data for an event, if any. The data is a union, and its exact contents depend on the
eType
field. The Event Reference section in this chapter shows what thedata
field contains for each event.
NOTE: Remember that the
data
field is part of the access path to an identifier in the EventType
structure. As an example, the code to access the controlID
field of a ctlEnterEvent
would be:EventType *event;
//...
if (event->data.ctlEnter.controlID ==
MyAppLockButton)
Compatibility
The tapCount
field is only defined if 3.5 New Feature Set is present. Because of the tapCount
field, it's particularly important that you clear the event structure before you use it to add a new event to the queue in Palm OS 3.5 and higher. Otherwise, the tapCount
value may be incorrect for the new event.
EventPtr Typedef
Purpose
The EventPtr
defines a pointer to an EventType
.
Prototype
typedef EventType *EventPtr;
Event Reference
appStopEvent
When the system wants to launch a different application than the one currently running, the event manager sends this event to request the current application to terminate. In response, an application has to exit its event loop, close any open files and forms, and exit.
If an application doesn't respond to this event by exiting, the system can't start the other application.
attnIndicatorEnterEvent
Purpose
The function FrmHandleEvent()
sends this event when it receives a penDownEvent
within the bounds of the attention indicator.
For this event, the data
field contains the following structure:
Prototype
struct attnIndicatorEnter { UInt16 formID; } attnIndicatorEnter;
Fields
Compatibility
This event is only supported if 5.0 New Feature Set is present.
attnIndicatorSelectEvent
Purpose
The control function FrmHandleEvent()
sends this event. When FrmHandleEvent()
receives a attnIndicatorEnterEvent
, it tracks the pen until the pen is lifted. If the pen is lifted within the bounds of the attention indicator, an attnIndicatorSelectEvent
is added to the event queue.
For this event, the data
field contains the following structure:
Prototype
struct attnIndicatorSelect { UInt16 formID; } attnIndicatorSelect;
Fields
Compatibility
This event is only supported if 5.0 New Feature Set is present.
ctlEnterEvent
Purpose
The control routine CtlHandleEvent()
sends this event when it receives a penDownEvent
within the bounds of a control.
For this event, the data
field contains the following structure:
Prototype
struct ctlEnter { UInt16 controlID; struct ControlType *pControl; } ctlEnter;
Fields
-
controlID
- Developer-defined ID of the control.
-
pControl
- Pointer to a control structure (
ControlType
).
ctlExitEvent
Purpose
The control routine CtlHandleEvent()
sends this event. When CtlHandleEvent
receives a ctlEnterEvent
, it tracks the pen until the pen is lifted from the display. If the pen is lifted within the bounds of a control, a ctlSelectEvent
is added to the event queue; if not, a ctlExitEvent
is added to the event queue. The penDown
, screenX
, and screenY
fields of the EventType
structure are set appropriately for the ctlExitEvent
. As well, the data
field contains the following structure:
Prototype
struct ctlExit { UInt16 controlID; struct ControlType *pControl; } ctlExit;
Fields
-
controlID
- Developer-defined ID of the control.
-
pControl
- Pointer to a control structure (
ControlType
).
ctlRepeatEvent
Purpose
The control routine CtlHandleEvent()
sends this event. When CtlHandleEvent
receives a ctlEnterEvent
in a repeating button (tREP) or a feedback slider control (tslf), it sends a ctlRepeatEvent. When CtlHandleEvent
receives a ctlRepeatEvent in a repeating button, it sends another ctlRepeatEvent if the pen remains down within the bounds of the control for 1/2 second beyond the last ctlRepeatEvent.
When CtlHandleEvent
receives a ctlRepeatEvent
in a feedback slider control, it sends a ctlRepeatEvent
each time the slider's thumb moves by at least one pixel. Feedback sliders do not send ctlRepeatEvents
at regular intervals like repeating buttons do.
If you return true
in response to a ctlRepeatEvent
, it stops the ctlRepeatEvent
loop. No further ctlRepeatEvents
are sent.
For this event, the data
field contains the following structure:
Prototype
struct ctlRepeat { UInt16 controlID; struct ControlType *pControl; UInt32 time; UInt16 value; } ctlRepeat;
Fields
-
controlID
- Developer-defined ID of the control.
-
pControl
- Pointer to a control structure (
ControlType
). -
time
- System-ticks count when the event is added to the queue.
-
value
- Current value if the control is a feedback slider.
Compatibility
The value
field is only present if 3.5 New Feature Set is present.
ctlSelectEvent
Purpose
The control routine CtlHandleEvent()
sends this event. When CtlHandleEvent
receives a ctlEnterEvent
, it tracks the pen until the pen is lifted. If the pen is lifted within the bounds of the same control it went down in, a cltSelectEvent
is added to the event queue; if not, a ctlExitEvent
is added to the event queue.
It usually doesn't matter whether you return true
or false
from your event handler since the operating system doesn't handle this event. The default event handler for popup triggers does handle this event, however, so you must return false
in this instance to ensure that the list is actually displayed.
For this event, the data
field contains the following structure:
Prototype
struct ctlSelect { UInt16 controlID; struct ControlType *pControl; Boolean on; UInt8 reserved1; UInt16 value; } ctlSelect;
Fields
-
controlID
- Developer-defined ID of the control.
-
pControl
- Pointer to a control structure (
ControlType
). -
on
-
true
when the control is depressed; otherwise,false
. -
reserved1
- Unused.
-
value
- Current value if the control is a slider.
Compatibility
The value
field is only present if 3.5 New Feature Set is present.
daySelectEvent
Purpose
The system-internal DayHandleEvent routine, which handles events in the day selector object, handles this event. When the day selector object displays a calendar month, the user can select a day by tapping on it.
This event is sent when the pen touches and is lifted from a day number.
For this event, the data
field contains the following structure:
Prototype
struct daySelect { struct DaySelectorType *pSelector; Int16 selection; Boolean useThisDate; UInt8 reserved1; } daySelect;
Fields
-
pSelector
- Pointer to a day selector structure (DaySelectorType).
-
selection
- Not used.
-
useThisDate
- Set to
true
to automatically use the selected date. -
reserved1
- Unused.
fldChangedEvent
Purpose
The field routine FldHandleEvent()
sends this event when the text of a field has or might have been scrolled. This event actually can be triggered from any call to the field code that causes scrolling to happen; most often, this happens during FldHandleEvent
.
When FldHandleEvent
receives a fldEnterEvent
, it positions the insertion point and tracks the pen until it's lifted. Text is selected (highlighted) appropriately as the pen is dragged.
For this event, the data
field contains the following structure:
Prototype
struct fldChanged { UInt16 fieldID; struct FieldType *pField; } fldChanged;
Parameters
fldEnterEvent
Purpose
The field routine FldHandleEvent()
sends this event when the field receives a penDownEvent
within the bounds of a field. For this event, the data
field contains the following structure:
Prototype
struct fldEnter { UInt16 fieldID; struct FieldType *pField; } fldEnter;
Fields
-
fieldID
- Developer-defined ID of the field.
-
pField
- Pointer to a field structure (
FieldType
).
fldHeightChangedEvent
Purpose
Several field routines, including FldHandleEvent()
, send this event when the number of lines in the field changes. These functions send a fldHeightChangedEvent to notify your application that the height of a field needs to change.
If the field is contained in a table, the table's code handles the fldHeightChangedEvent
. If the field is directly on a form, your application code should handle the fldHeightChangedEvent
itself. The form code does not handle the event for you.
For this event, the data
field contains the following structure:
Prototype
struct fldHeightChanged { UInt16 fieldID; struct FieldType *pField; Int16 newHeight; UInt16 currentPos; } fldHeightChanged;
Fields
-
fieldID
- Developer-defined ID of the field.
-
pField
- Pointer to a field structure (
FieldType
). -
newHeight
- New visible height of the field, in number of lines.
-
currentPos
- Current position of the insertion point.
frmCloseEvent
Purpose
The form routines FrmGotoForm()
and FrmCloseAllForms()
send this event. FrmGotoForm
sends a frmCloseEvent to the currently active form; FrmCloseAllForms
sends a frmCloseEvent to all forms an application has loaded into memory. If an application doesn't intercept this event, the routine FrmHandleEvent()
erases the specified form and releases any memory allocated for it.
For this event, the data
field contains the following structure:
Prototype
struct frmClose { UInt16 formID; } frmClose;
Fields
frmGadgetEnterEvent
Purpose
The function FrmHandleEvent()
sends this event when there is a penDownEvent
within the bounds of an extended gadget. The gadget handler function (see FormGadgetHandlerType()
) should handle this event.
For this event, the data
field contains the following structure:
Prototype
struct gadgetEnter { UInt16 gadgetID; struct FormGadgetType *gadgetP; } gadgetEnter;
Fields
-
gadgetID
- Developer-defined ID of the gadget.
-
gadgetP
- Pointer to the
FormGadgetType
object representing this gadget.
Compatibility
Implemented only if 3.5 New Feature Set is present.
frmGadgetMiscEvent
Purpose
An application may choose to send this event when it needs to pass information to an extended gadget. The FrmHandleEvent()
function passes frmGadgetMiscEvents
on to the extended gadget's handler function (see FormGadgetHandlerType()
).
For this event, the data
field contains the following structure:
Prototype
struct gadgetMisc { UInt16 gadgetID; struct FormGadgetType *gadgetP; UInt16 selector; void *dataP; } gadgetMisc;
Fields
-
gadgetID
- Developer-defined ID of the gadget.
-
gadgetP
- Pointer to the
FormGadgetType
object representing this gadget. -
selector
- Any necessary integer value to pass to the gadget handler function.
-
dataP
- A pointer to any necessary data to pass to the gadget handler function.
Compatibility
Implemented only if 3.5 New Feature Set is present.
frmGotoEvent
Purpose
An application may choose to send itself this event when it receives a sysAppLaunchCmdGoTo
launch code. sysAppLaunchCmdGoTo
is generated when the user selects a record in the global find facility. Like frmOpenEvent
, frmGotoEvent
is a request that the application initialize and draw a form, but this event provides extra information so that the application may display and highlight the matching string in the form.
The application is responsible for handling this event.
For this event, the data
field contains the following structure:
Prototype
struct frmGoto { UInt16 formID; UInt16 recordNum; UInt16 matchPos; UInt16 matchLen; UInt16 matchFieldNum; UInt32 matchCustom; } frmGoto;
Fields
-
formID
- Developer-defined ID of the form.
-
recordNum
- Index of record containing the match string.
-
matchPos
- Position of the match.
-
matchLen
- Length of the matched string.
-
matchFieldNum
- Number of the field the matched string was found in.
-
matchCustom
- Application-specific information. You might use this if you need to provide extra information to locate the matching string within the record.
frmLoadEvent
Purpose
The form routines FrmGotoForm()
and FrmPopupForm()
send this event. It's a request that the application load a form into memory.
The application is responsible for handling this event. In response to this event, applications typically initialize the form, make it active, and set the event handler.
For this event, the data
field contains the following structure:
Prototype
struct frmLoad { UInt16 formID; } frmLoad;
Fields
frmObjectFocusLostEvent
Purpose
In some devices, a 5-way navigation button generates this event as the navigation focus moves in a form. The event is sent after an object has lost the focus.
For this event, the data
field contains the following structure:
Prototype
struct frmObjectFocusLost{ UInt16 formID; UInt16 objectID; UInt32 dispatchHint; } frmObjectFocusLost;
Fields
-
formID
- Developer-defined ID of the form.
-
objectID
- ID of the object in the tab order.
-
dispatchHint
- System use only.
Comments
The system's internal focus structures have already been updated when this event is sent. Therefore, it simply initiates the redrawing of the object that lost the focus.
When FrmHandleEvent()
receives this event, it will call the type-specific handler of the UI object associated with the event. Usually, the type-specific handler will draw the UI object associated with the event in its normal state and then return true.
Compatibility
Some devices that have 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.
frmObjectFocusTakeEvent
Purpose
In some devices, a 5-way navigation button generates this event as the navigation focus moves in a form. The event is sent when an object should grab the focus.
For this event, the data
field contains the following structure:
Prototype
struct frmObjectFocusTake{ UInt16 formID; UInt16 objectID; UInt32 dispatchHint; } frmObjectFocusTake;
Fields
-
formID
- Developer-defined ID of the form.
-
objectID
- ID of the object in the tab order.
-
dispatchHint
- System use only.
Comments
The system's internal focus structures are updated when this event is handled, not when it is sent.
When FrmHandleEvent()
receives this event, it will call the type-specific handler of the UI object associated with the event. The type-specific handler must call FrmSetFocus()
for the associated object, draw the object in its focused state, and then return true. FrmSetFocus()
updates the system's internal focus structures and then sends a frmObjectFocusLostEvent
.
Compatibility
Some devices that have 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.
frmOpenEvent
Purpose
The form routines FrmGotoForm()
and FrmPopupForm()
send this event. It is a request that the application initialize and draw a form.
The application is responsible for handling this event.
For this event, the data
field contains the following structure:
Prototype
struct frmOpen { UInt16 formID; } frmOpen;
Parameters
frmSaveEvent
The form routine FrmSaveAllForms()
sends this event. It is a request that the application save any data stored in a form.
The application is responsible for handling this event.
No data is passed with this event.
frmTitleEnterEvent
Purpose
The control routine FrmHandleEvent()
sends this event when it receives a penDownEvent
within the bounds of the title of the form. Note that only the written title, not the whole title bar is active.
For this event, the data
field contains the following structure:
Prototype
struct frmTitleEnter { UInt16 formID; } frmTitleEnter;
Fields
frmTitleSelectEvent
Purpose
The control routine FrmHandleEvent()
sends this event. FrmHandleEvent()
receives a frmTitleEnterEvent
, it tracks the pen until the pen is lifted. If the pen is lifted within the bounds of the active same title bar region, a frmTitleSelectEvent
is added to the event queue.
For this event, the data
field contains the following structure:
Prototype
struct frmTitleSelect { UInt16 formID; } frmTitleSelect;
Fields
Compatibility
In Palm OS version 3.5 and higher, FrmHandleEvent()
responds to frmTitleSelectEvent
. Its response is to enqueue a keyDownEvent
with a vchrMenu
character to display the form's menu.
frmUpdateEvent
Purpose
The form routine FrmUpdateForm()
, or in some cases the routine FrmEraseForm()
, sends this event when it needs to redraw the region obscured by the form being erased.
Generally, the region obscured by a form is saved and restored by the form routines without application intervention. However, in cases where the system is running low on memory, the form's routine may not save obscured regions itself. In that case, the application adds a frmUpdateEvent
to the event queue. The form receives the event and redraws the region using the updateCode
value.
An application can define its own updateCode
and then use this event to also trigger behavior in another form, usually when changes made to one form need to be reflected in another form.
For this event, the data
field contains the following structure:
Prototype
struct frmUpdate { UInt16 formID; UInt16 updateCode; } frmUpdate;
Fields
-
formID
- Developer-defined ID of the form.
-
updateCode
- The reason for the update request. FrmEraseForm sets this code to frmRedrawUpdateCode, which indicates that the entire form needs to be redrawn. Application developers can define their own updateCode. The updateCode is passed as a parameter to
FrmUpdateForm()
.
inetSockReadyEvent
Purpose
This event is returned only by INetLibGetEvent()
(not EvtGetEvent
) when the Internet library determines that a socket has data ready for an INetLibSockRead()
.
For this event, the data
field contains the following structure:
Prototype
struct { MemHandle sockH; UInt32 context; Boolean inputReady; Boolean outputReady; } inetSockReady;
Fields
-
sockH
- Socket handle of the socket that this event refers to.
-
context
- Not used.
-
inputReady
-
true
when the socket has data ready for theINetLibSockRead()
call. -
outputReady
- Not used.
The penDown
, tapCount
, screenX
and screenY
fields are not valid for Internet library events and should be ignored.
Compatibility
Implemented only if Wireless Internet Feature Set is present.
inetSockStatusChangeEvent
Purpose
This event is returned only by INetLibGetEvent()
(not EvtGetEvent
) when the Internet library determines that a socket has data ready for an INetLibSockRead()
.
For this event, the data
field contains the following structure:
Prototype
struct { MemHandle sockH; UInt32 context; UInt16 status; Err sockErr; }inetSockStatusChange;
Fields
-
sockH
- Socket handle of the socket that this event refers to.
-
context
- Not used.
-
status
- Current status of the socket. This is one of the
INetStatusEnum
constants. -
sockErr
- Reason for failure of the last operation, if any. The current socket error can be cleared by calling
INetLibSockStatus()
.
The penDown
, tapCount
, screenX
and screenY
fields are not valid for Internet library events and should be ignored.
Compatibility
Implemented only if Wireless Internet Feature Set is present.
keyDownEvent
Purpose
This event is sent by the system when the user enters a Graffiti® or Graffiti 2 character, presses one of the buttons below the display, or taps one of the icons in the icon area; for example, the Find icon.
For this event, the data
field contains the structure defined below. Access the information stored in the data
field in this way:
Prototype
struct _KeyDownEventType { WChar chr; UInt16 keyCode; UInt16 modifiers; };
Fields
-
chr
- The character code.
-
keyCode
- Unused.
-
modifiers
- 0, or one or more of the following values:
-
shiftKeyMask
- Graffiti or Graffiti 2 is in case-shift mode.
-
capsLockMask
- Graffiti is in cap-shift mode. (Cap-shift mode is not supported in Graffiti 2.)
-
numLockMask
- Graffiti or Graffiti 2 is in numeric-shift mode.
-
commandKeyMask
- The glyph was the menu command glyph or a virtual key code.
-
optionKeyMask
- Not implemented. Reserved.
-
controlKeyMask
- Not implemented. Reserved.
-
autoRepeatKeyMask
- Event was generated due to auto-repeat.
-
doubleTapKeyMask
- Not implemented. Reserved.
-
poweredOnKeyMask
- The key press caused the system to be powered on.
-
appEvtHookKeyMask
- System use only.
-
libEvtHookKeyMask
- System use only.
-
willSendKeyUpMask
- Sent only from hardware keys. Indicates that a
keyUpEvent
will be sent and akeyHoldEvent
could be sent.
Compatibility
The willSendKeyUpMask
applies only to certain devices that support a 5-way navigation button—such as the Handspring Treo 600 Smartphone. Consult the licensee's developer documentation to see whether this version of the keyDownEvent
is generated by a particular device.
IMPORTANT: If the Graffiti 2 Feature Set is present, your application may receive a key down event for a character that is actually meant to be the first stroke of a multi-stroke character. See "Event Translation: Pen Strokes to Key Events" of the Palm OS Programmer's Companion, vol. I for more information.
keyHoldEvent
Purpose
Sent when the user holds a hard key on the device.
For this event, the data
field contains the structure defined below. Access the information stored in the data
field in this way:
Prototype
struct _keyHoldEventType { WChar chr; UInt16 keycode; UInt16 modifiers; };
Fields
-
chr
- The character code.
-
keyCode
- Unused.
-
modifiers
- 0, or one or more of the key modifier constants listed under
modifiers
inkeyDownEvent
.
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
, keyHoldEvent
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 keyHoldEvent
, and, ultimately, a keyUpEvent
. If the user is using a software keyboard, the application receives only the keyDownEvent
.
Only one keyHoldEvent
is sent for each press-and-hold of the key. You do not get a keyHoldEvent
for each additional second that the key is held.
A keyHoldEvent
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 keyHoldEvent
is not sent for the first key, but a keyHoldEvent
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
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.
See Also
keyUpEvent
Purpose
Sent when the user releases a hard key on the device.
For this event, the data
field contains the structure defined below. Access the information stored in the data
field in this way:
Prototype
struct _keyUpEventType { WChar chr; UInt16 keycode; UInt16 modifiers; };
Fields
-
chr
- The character code.
-
keyCode
- Unused.
-
modifiers
- 0, or one or more of the key modifier constants listed under
modifiers
inkeyDownEvent
.
Comments
Unlike 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 software keyboard, the application only receives the keyDownEvent
.
Compatibility
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.
lstEnterEvent
Purpose
The list routine LstHandleEvent()
sends this event when it receives a penDownEvent
within the bounds of a list object.
For this event, the data
field contains the following structure:
Prototype
struct lstEnter { UInt16 listID; struct ListType *pList; Int16 selection; } lstEnter;
Fields
-
listID
- Developer-defined ID of the list.
-
pList
- Pointer to a list structure (
ListType
). -
selection
- Unused.
lstExitEvent
Purpose
The list routine LstHandleEvent()
sends this event. When LstHandleEvent
receives a lstEnterEvent
, it tracks the pen until the pen is lifted. If the pen is lifted within the bounds of a list, a lstSelectEvent
is added to the event queue; if not, a lstExitEvent is added to the event queue.
For this event, the data
field contains the following structure:
Prototype
struct lstExit { UInt16 listID; struct ListType *pList; } lstExit;
Fields
-
listID
- Developer-defined ID of the list.
-
pList
- Pointer to a list structure (
ListType
).
lstSelectEvent
Purpose
The list routine LstHandleEvent()
sends this event. When LstHandleEvent
receives a lstEnterEvent
, it tracks the pen until the pen is lifted. If the pen is lifted within the bounds of a list, a lstSelectEvent is added to the event queue; if not, a lstExitEvent
is added to the event queue.
Note that popup lists don't generate a lstSelectEvent
. Instead, they generate a popSelectEvent
.
For this event, the data
field contains the following structure:
Prototype
struct lstSelect { UInt16 listID; struct ListType *pList; Int16 selection; } lstSelect;
Fields
-
listID
- Developer-defined ID of the list.
-
pList
- Pointer to a list structure (
ListType
). -
selection
- Item number (zero-based) of the new selection.
menuCloseEvent
This event is not currently used.
menuCmdBarOpenEvent
Purpose
The menu routine MenuHandleEvent()
sends this event when the user enters the menu shortcut keystroke, causing the command toolbar to be displayed at the bottom of the screen. Applications might respond to this event by calling MenuCmdBarAddButton()
to add custom buttons to the command toolbar. Shared libraries or other non-application code resources can add buttons to the toolbar by registering to receive the sysNotifyMenuCmdBarOpenEvent
notification.
For this event, the data
field contains the following structure:
Prototype
struct menuCmdBarOpen { Boolean preventFieldButtons; UInt8 reserved; } menuCmdBarOpen;
Fields
-
preventFieldButtons
- If
true
, the field manager does not add the standard cut, copy, paste, and undo buttons when the focus is on a field. Iffalse
, the field adds the buttons. -
reserved
- Unused.
To prevent the command toolbar from being displayed, respond to this event and return true
. Returning true
prevents the form manager from displaying the toolbar.
Compatibility
Implemented only if 3.5 New Feature Set is present.
menuEvent
Purpose
The menu routine MenuHandleEvent()
sends this event:
- When the user selects an item from a pull-down menu
- When the user selects a menu command using the command stroke followed by an available command; for example, Command-C for copy
- When the user taps one of the buttons on the command toolbar and the button is set up to generate a
menuEvent
.
For this event, the data
field contains the following structure:
Prototype
struct menu { UInt16 itemID; } menu;
Fields
menuOpenEvent
Purpose
The menu routine MenuHandleEvent()
sends this event when a new active menu has been initialized. A menu becomes active the first time the user taps the Menu silk-screen button or taps the form's titlebar, and it might need to be re-initialized and reactivated several times during the life of an application.
A menu remains active until one of the following happens:
- A
FrmSetMenu()
call changes the active menu on the form. - A new form, even a modal form or alert panel, becomes active.
Suppose a user selects your application's About item from the Options menu then clicks the OK button to return to the main form. When the About dialog is displayed, it becomes the active form, which causes the main form's menu state to be erased. This menu state is not restored when the main form becomes active again. The next time the user requests the menu, it must be initialized again, so menuOpenEvent
is sent again.
Applications might respond to this event by adding, hiding, or un-hiding menu items using the functions MenuAddItem()
, MenuHideItem()
, or MenuShowItem()
.
A menuCloseEvent
is defined by the system, but it is not currently sent. If you need to perform some cleanup (such as closing a resource) after the menu item you added is no longer needed, do so in response to frmCloseEvent
.
For this event, the data
field contains the following structure:
Prototype
struct menuOpen { UInt16 menuRscID; Int16 cause; } menuOpen;
Fields
-
menuRscID
- Resource ID of the menu.
-
cause
- Reason for opening the menu. If
menuButtonCause
, the user tapped the Menu silkscreen button or tapped the form's titlebar, and the menu is going to be displayed. IfmenuCommandCause
, the user entered the command keystroke, so the menu is becoming active without being displayed.
Compatibility
Implemented only if 3.5 New Feature Set is present.
nilEvent
A nilEvent is useful for animation, polling, and similar situations.
The event manager sends this event when there are no events in the event queue. This can happen if the routine EvtGetEvent()
is passed a time-out value (a value other than evtWaitForever, -1). If EvtGetEvent
is unable to return an event in the specified time, it returns a nilEvent. Different Palm OS versions and different devices can send nilEvent
s under different circumstances, so you might receive a nilEvent
even before the timeout has expired.
penDownEvent
The event manager sends this event when the pen first touches the digitizer.
The following data is passed with the event:
Fields
-
penDown
- Always
true
. -
tapCount
- The number of taps received at this location.
-
screenX
- Window-relative position of the pen in pixels (number of pixels from the left bound of the window).
-
screenY
- Window-relative position of the pen in pixels (number of pixels from the top left of the window).
penMoveEvent
Purpose
The event manager sends this event when the pen is moved on the digitizer. Note that several kinds of UI objects, such as controls and lists, track the movement directly, and no penMoveEvent is generated.
The following data is passed with the event:
Fields
-
penDown
- Always
true
. -
tapCount
- The number of taps received at this location.
-
screenX
- Window-relative position of the pen in pixels (number of pixels from the left bound of the window).
-
screenY
- Window-relative position of the pen in pixels (number of pixels from the top left of the window).
penUpEvent
Purpose
The event manager sends this event 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 contains the following structure:
Prototype
struct _PenUpEventType { PointType start; PointType end; };
Fields
In addition, the following data is passed with this event:
-
penDown
- Always
false
. -
tapCount
- The number of taps received at this location.
-
screenX
- Window-relative position of the pen in pixels (number of pixels from the left bound of the window).
-
screenY
- Window-relative position of the pen in pixels (number of pixels from the top left of the window).
popSelectEvent
Purpose
The form routine FrmHandleEvent()
sends this event when the user selects an item in a popup list.
For this event, the data
field contains the following structure:
Prototype
struct popSelect { UInt16 controlID; struct ControlType *controlP; UInt16 listID; struct ListType *listP; Int16 selection; Int16 priorSelection; } popSelect;
Fields
-
controlID
- Developer-defined ID of the resource.
-
controlP
- Pointer to the control structure (
ControlType
) of the popup trigger object. -
listID
- Developer-defined ID of the popup list object.
-
listP
- Pointer to the list structure (
ListType
) of the popup list object. -
selection
- Item number (zero-based) of the new list selection.
-
priorSelection
- Item number (zero-based) of the prior list selection.
sclEnterEvent
Purpose
The routine SclHandleEvent()
sends this event when it receives a penDownEvent
within the bounds of a scroll bar.
Applications usually don't have to handle this event.
For this event, the data
field contains the following structure:
Prototype
struct sclEnter { UInt16 scrollBarID; struct ScrollBarType *pScrollBar; } sclEnter;
Fields
-
scrollBarID
- Developer-defined ID of the scroll bar resource.
-
pScrollBar
- Pointer to the scroll bar structure.
sclExitEvent
Purpose
The routine SclHandleEvent()
sends this event when the user lifts the pen from the scroll bar.
Applications that want to implement non-dynamic scrolling should wait for this event, then scroll the text using the values provided in value
and newvalue
.
Note that this event is sent regardless of previous sclRepeatEvents
. If, however, the application has implemented dynamic scrolling, it doesn't have to catch this event.
For this event, the data
field contains the following structure:
Prototype
struct sclExit { UInt16 scrollBarID; struct ScrollBarType *pScrollBar; Int16 value; Int16 newValue; } sclExit;
Fields
-
scrollBarID
- Developer-defined ID of the scroll bar resource.
-
pScrollBar
- Pointer to the scroll bar structure.
-
value
- Initial position of the scroll bar
-
newvalue
- New position of the scroll bar. Given
value
andnewValue
, you can actually tell how much you have scrolled.
sclRepeatEvent
Purpose
The routine SclHandleEvent()
sends this event when the pen is continually held within the bounds of a scroll bar.
Applications that implement dynamic scrolling should watch for this event. In dynamic scrolling, the display is updated as the user drags the scroll bar (not after the user releases the scroll bar).
For this event, the data
field contains the following structure:
Prototype
struct sclRepeat { UInt16 scrollBarID; struct ScrollBarType *pScrollBar; Int16 value; Int16 newValue; Int32 time; } sclRepeat;
Fields
-
scrollBarID
- Developer-defined ID of the scroll bar resource.
-
pScrollBar
- Pointer to the scroll bar structure.
-
value
- Initial position of the scroll bar.
-
newValue
- New position of the scroll bar. Given
value
andnewValue
, you can actually tell how much you have scrolled. -
time
- System-ticks count when the event is added to the queue to determine when the next event should occur.
tblEnterEvent
Purpose
The table routine TblHandleEvent()
sends this event when it receives a penDownEvent
within the bounds of an active item in a table object.
For this event, the data
field contains the following structure:
Prototype
struct tblEnter { UInt16 tableID; struct TableType *pTable; Int16 row; Int16 column; } tblEnter;
Fields
-
tableID
- Developer-defined ID of the table.
-
pTable
- Pointer to a table structure (
TableType
). -
row
- Row of the item.
-
column
- Column of the item.
tblExitEvent
Purpose
The table routine TblHandleEvent()
sends this event. When TblHandleEvent
receives a tblEnterEvent
, it tracks the pen until it's lifted from the display. If the pen is lifted within the bounds of the same item it went down in, a tblSelectEvent
is added to the event queue; if not, a tblExitEvent is added to the event queue.
For this event, the data
field contains the following structure:
Prototype
struct tblExit { UInt16 tableID; struct TableType *pTable; Int16 row; Int16 column; } tblExit;
Fields
-
tableID
- Developer-defined ID of the table.
-
pTable
- Pointer to a table structure (
TableType
). -
row
- Row of the item.
-
column
- Column of the item.
tblSelectEvent
Purpose
The table routine TblHandleEvent()
sends this event. When TblHandleEvent
receives a tblEnterEvent
, it tracks the pen until the pen is lifted from the display. If the pen is lifted within the bounds of the same item it went down in, a tblSelectEvent is added to the event queue; if not, a tblExitEvent
is added to the event queue.
For this event, the data
field contains the following structure:
Prototype
struct tblSelect { UInt16 tableID; struct TableType *pTable; Int16 row; Int16 column; } tblSelect;
Fields
-
tableID
- Developer-defined ID of the table.
-
pTable
- Pointer to a table structure (
TableType
). -
row
- Row of the item.
-
column
- Column of the item.
winDisplayChangedEvent
Purpose
Posted by PINSetInputAreaState
after the dynamic input area has been opened or closed. Normally, the user opens and closes the dynamic input area, but applications may also do so.
Applications may respond to the event by redrawing the active form in the available space.
By the time the application receives this event, the OS has already changed the bounds of the display window as appropriate to the state of the input area. The application must resize its active form's window and relayout the form accordingly.
No data is passed with this event.
Compatibility
Sent only if the Pen Input Manager Feature Set is present and returns pinAPIVersion1_1
.
winEnterEvent
Purpose
The event manager sends this event when a window becomes the active window. This can happen in two ways: a call to WinSetActiveWindow()
is issued (FrmSetActiveForm()
calls this routine), or the user taps within the bounds of a window that is visible but not active. All forms are windows, but not all windows are forms; for example, the menu bar is a window but not a form.
For this event, the data
field contains the following structure:
Prototype
struct _WinEnterEventType { WinHandle enterWindow; WinHandle exitWindow; };
Fields
-
enterWindow
- Handle to the window we are entering. If the window is a form, then this is a pointer to a
FormType
structure; if not, it's a pointer to aWindowType
structure. -
exitWindow
- Handle to the window we are exiting, if there is currently an active window, or zero if there is no active window. If the window is a form, then this is a pointer to a
FormType
structure; if not, it's a pointer to aWindowType
structure.
winExitEvent
Purpose
This event is sent by the event manager when a window is deactivated. A window is deactivated when another window becomes the active window (see winEnterEvent
).
For this event, the data
field contains the following structure:
Prototype
struct _WinExitEventType { WinHandle enterWindow; WinHandle exitWindow; };
Fields
-
enterWindow
- Handle to the window we are entering. If the window is a form, then this is a pointer to a
FormType
structure; if not, it's a pointer to aWindowType
structure. -
exitWindow
- Handle to the window we are exiting. If the window is a form, then this is a pointer to a
FormType
structure; if not, it's a pointer to aWindowType
structure.