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

2    Palm OS Events

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

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 ^TOP^

eventsEnum ^TOP^

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 ^TOP^

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, otherwise false.
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 the data 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 ^TOP^

Purpose

The EventPtr defines a pointer to an EventType.

Prototype

typedef EventType *EventPtr;

Event Reference ^TOP^

appStopEvent ^TOP^

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 ^TOP^

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

formID
Developer-defined ID of the form.

Compatibility

This event is only supported if 5.0 New Feature Set is present.

attnIndicatorSelectEvent ^TOP^

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

formID
Developer-defined ID of the form.

Compatibility

This event is only supported if 5.0 New Feature Set is present.

ctlEnterEvent ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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 {
UInt16controlID;
struct ControlType *pControl;
Booleanon;
UInt8reserved1;
UInt16value;
} 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 ^TOP^

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 ^TOP^

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

fieldID
Developer-defined ID of the field.
pField
Pointer to a field structure (FieldType).

fldEnterEvent ^TOP^

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 ^TOP^

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 ^TOP^

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

formID
Developer-defined ID of the form.

frmGadgetEnterEvent ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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

formID
Developer-defined ID of the form.

frmObjectFocusLostEvent ^TOP^

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 ^TOP^

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 ^TOP^

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

formID
Developer-defined ID of the form.

frmSaveEvent ^TOP^

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 ^TOP^

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

formID
Developer-defined ID of the form.

frmTitleSelectEvent ^TOP^

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

formID
Developer-defined ID of the form.

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 ^TOP^

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 ^TOP^

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 the INetLibSockRead() 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 ^TOP^

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 ^TOP^

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:

wchar32_t = eventP->data.keyDown.chr;

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 a keyHoldEvent 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 ^TOP^

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:

wchar32_t = eventP->data.keyHold.chr;

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 in keyDownEvent.

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

keyDownEvent, keyUpEvent

keyUpEvent ^TOP^

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:

wchar32_t = eventP->data.keyUp.chr;

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 in keyDownEvent.

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 ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

This event is not currently used.

menuCmdBarOpenEvent ^TOP^

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. If false, 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 ^TOP^

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

itemID
Item ID of the selected menu command.

menuOpenEvent ^TOP^

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. If menuCommandCause, 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 ^TOP^

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 nilEvents under different circumstances, so you might receive a nilEvent even before the timeout has expired.

penDownEvent ^TOP^

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 ^TOP^

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 ^TOP^

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

start
Display-relative start point of the stroke.
end
Display-relative end point of the stroke.

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 ^TOP^

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 ^TOP^

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 ^TOP^

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 and newValue, you can actually tell how much you have scrolled.

sclRepeatEvent ^TOP^

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 and newValue, 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 ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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 a WindowType 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 a WindowType structure.

winExitEvent ^TOP^

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 a WindowType 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 a WindowType structure.