3 Palm OS Events

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 4, "Event Loop" in the Palm OS Programmer's Companion 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	UI Object
appStopEvent	N.A.
ctlEnterEvent, ctlExitEvent, ctlRepeatEvent, ctlSelectEvent	Control
daySelectEvent	N.A.
fldChangedEvent, fldEnterEvent, fldHeightChangedEvent	Field
frmCloseEvent, frmGotoEvent, frmLoadEvent, frmOpenEvent, frmSaveEvent, frmUpdateEvent, frmTitleEnterEvent, frmTitleSelectEvent	Form
frmGadgetEnterEvent, frmGadgetMiscEvent	Extended gadget
inetSockReadyEvent, inetSockStatusChangeEvent	N.A. (INetLib)
keyDownEvent	N.A.
lstEnterEvent, lstExitEvent, lstSelectEvent	List
menuEvent, menuOpenEvent, menuCloseEvent, menuCmdBarOpenEvent	Menu
nilEvent	N.A.
penDownEvent, penMoveEvent, penUpEvent	N.A. (pen)
popSelectEvent	Popup (Control)
sclEnterEvent, sclRepeatEvent, sclExitEvent	Scroll bar
tblEnterEvent, tblExitEvent, tblSelectEvent	Table
winEnterEvent, winExitEvent	Window

Event Data Structures

eventsEnum

The eventsEnum enum specifies the possible event types.

enum events {

    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,
   
    menuCmdBarOpenEvent = 0x0800,
    menuOpenEvent,
    menuCloseEvent,
    frmGadgetEnterEvent,
    frmGadgetMiscEvent,

    firstINetLibEvent = 0x1000,
    firstWebLibEvent = 0x1100,
   
    firstUserEvent = 0x6000
} eventsEnum;

Each of these event types is discussed in alphabetical order below.

EventType

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 8 words 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.

typedef struct {

    eventsEnum eType;
    Boolean penDown;
    UInt8 tapCount;
    Int16 screenX;
    Int16 screenY;
    union{
    ...
    } data;
} EventType;

Common Field Descriptions

---

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

The EventPtr defines a pointer to an EventType.

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.

ctlEnterEvent

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:

struct ctlEnter {

    UInt16 controlID;
    struct ControlType *pControl;
} ctlEnter;

Field Descriptions

ctlExitEvent

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 following data is passed with the event:

Field Descriptions

ctlRepeatEvent

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:

struct ctlRepeat {

    UInt16 controlID;
    struct ControlType *pControl;
    UInt32 time;
    UInt16 value;
} ctlRepeat;

Field Descriptions

Compatibility

The value field is only present if 3.5 New Feature Set is present.

ctlSelectEvent

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.

For this event, the data field contains the following structure:

struct ctlSelect {

    UInt16 controlID;
    struct ControlType *pControl;
    Boolean on;
    UInt8 reserved1;
    UInt16 value;
} ctlSelect;

Field Descriptions

Compatibility

The value field is only present if 3.5 New Feature Set is present.

daySelectEvent

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:

struct daySelect {

    struct DaySelectorType *pSelector;
    Int16 selection;
    Boolean useThisDate;
    UInt8 reserved1;
} daySelect;

Field Descriptions

fldChangedEvent

The field routine FldHandleEvent sends this event when the text of a field has been scrolled as a result of drag-selecting. 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:

struct fldChanged {

    UInt16 fieldID;
    struct FieldType *pField;
} fldChanged;

Field Descriptions

fldEnterEvent

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:

struct fldEnter {

    UInt16 fieldID;
    struct FieldType *pField;
} fldEnter;

Field Descriptions

fldHeightChangedEvent

The field routine FldHandleEvent sends this event. The field API supports a feature that allows a field to dynamically resize its visible height as text is added or removed from it. Functions in the field API send a fldHeightChangedEvent to change the height of a field.

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:

struct fldHeightChanged {

    UInt16 fieldID;
    struct FieldType *pField;
    Int16 newHeight;
    UInt16 currentPos;
} fldHeightChanged;

Field Descriptions

frmCloseEvent

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:

struct frmClose {

    UInt16 formID;
} frmClose;

Field Descriptions

frmGadgetEnterEvent

The function FrmHandleEvent sends this event when there is a penDownEvent within the bounds of an extended gadget. The gadget handler function (see FormGadgetHandler) should handle this event.

For this event, the data field contains the following structure:

struct gadgetEnter {

    UInt16 gadgetID;
    struct FormGadgetType *gadgetP;
} gadgetEnter;

Field Descriptions

Compatibility

Implemented only if 3.5 New Feature Set is present.

frmGadgetMiscEvent

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 FormGadgetHandler).

For this event, the data field contains the following structure:

struct gadgetMisc {

    UInt16 gadgetID;
    struct FormGadgetType *gadgetP;
    UInt16 selector;
    void *dataP;
} gadgetMisc;

Field Descriptions

Compatibility

Implemented only if 3.5 New Feature Set is present.

frmGotoEvent

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:

struct frmGoto {

    UInt16 formID;
    UInt16 recordNum;
    UInt16 matchPos;
    UInt16 matchLen;
    UInt16 matchFieldNum;
    UInt32 matchCustom;
} frmGoto;

Field Descriptions

frmLoadEvent

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.

For this event, the data field contains the following structure:

struct frmLoad {

    UInt16 formID;
} frmLoad;

Field Descriptions

frmOpenEvent

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:

struct frmOpen {

    UInt16 formID;
} frmOpen;

Field Descriptions

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

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:

struct frmTitleEnter {

    UInt16 formID;
    } frmTitleEnter;

Field Descriptions

frmTitleSelectEvent

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:

struct frmTitleSelect {

    UInt16 formID;
} frmTitleSelect;

Field Descriptions

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

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:

struct frmUpdate {

    UInt16 formID;
    UInt16 updateCode;
} frmUpdate;

Field Descriptions

inetSockReadyEvent

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:

struct {

    MemHandle sockH;
    UInt32 context;
    Boolean inputReady;
    Boolean outputReady;
} inetSockReady;

Field Descriptions

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

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:

struct {

    MemHandle sockH;
    UInt32 context;
    UInt16 status;
    Err sockErr;
}inetSockStatusChange;

Field Descriptions

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

This event is sent by the system when the user enters a Graffiti^® 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 following structure:

struct _KeyDownEventType {

    WChar chr;
    UInt16 keyCode;
    UInt16 modifiers;
};

Field Descriptions

lstEnterEvent

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:

struct lstEnter {

    UInt16 listID;
    struct ListType *pList;
    Int16 selection;
} lstEnter;

Field Descriptions

lstExitEvent

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:

struct lstExit {

    UInt16 listID;
    struct ListType *pList;
} lstExit;

Field Descriptions

lstSelectEvent

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:

struct lstSelect {

    UInt16 listID;
    struct ListType *pList;
    Int16 selection;
} lstSelect;

Field Descriptions

menuCloseEvent

This event is not currently used.

menuCmdBarOpenEvent

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. (See Chapter 36, "Notification Manager.")

For this event, the data field contains the following structure:

struct menuCmdBarOpen {

    Boolean preventFieldButtons;
    UInt8 reserved;
} menuCmdBarOpen;

Field Descriptions

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

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 Graffiti command keystroke 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:

struct menu {

    UInt16 itemID;
} menu;

Field Descriptions

menuOpenEvent

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 unhiding 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:

struct menuOpen {

    UInt16 menuRscID;
    Int16 cause;
} menuOpen;

Field Descriptions

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 nilEvents 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:

Field Descriptions

penMoveEvent

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:

Field Descriptions

penUpEvent

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:

struct _PenUpEventType {

    PointType start;
    PointType end;
};

Field Descriptions

In addition, the following data is passed with this event:

popSelectEvent

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:

struct popSelect {

    UInt16 controlID;
    struct ControlType *controlP;
    UInt16 listID;
    struct ListType *listP;
    Int16 selection;
    Int16 priorSelection;
} popSelect;

Field Descriptions

sclEnterEvent

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:

struct sclEnter {

    UInt16 scrollBarID;
    struct ScrollBarType *pScrollBar;
} sclEnter;

Field Descriptions

sclExitEvent

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:

struct sclExit {

    UInt16 scrollBarID;
    struct ScrollBarType *pScrollBar;
    Int16 value;
    Int16 newValue;
} sclExit;

Field Descriptions

sclRepeatEvent

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:

struct sclRepeat {

    UInt16 scrollBarID;
    struct ScrollBarType *pScrollBar;
    Int16 value;
    Int16 newValue;
    Int32 time;
} sclRepeat;

Field Descriptions

tblEnterEvent

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:

struct tblEnter {

    UInt16 tableID;
    struct TableType *pTable;
    Int16 row;
    Int16 column;
} tblEnter;

Field Descriptions

tblExitEvent

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:

struct tblExit {

    UInt16 tableID;
    struct TableType *pTable;
    Int16 row;
    Int16 column;
} tblExit;

Field Descriptions

tblSelectEvent

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:

struct tblSelect {

    UInt16 tableID;
    struct TableType *pTable;
    Int16 row;
    Int16 column;
} tblSelect;

Field Descriptions

winEnterEvent

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:

struct _WinEnterEventType {

    WinHandle enterWindow;
    WinHandle exitWindow;
};

Field Descriptions

winExitEvent

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:

struct _WinExitEventType {

    WinHandle enterWindow;
    WinHandle exitWindow;
};

Field Descriptions