This chapter describes functions available in the system event manager. The system event manager API is declared in the header files Event.h and SysEvtMgr.h.
For more information on the system event manager, see the chapter "Event Loop" in the Palm OS Programmer's Companion, vol. I. The reference for specific events sent by the system are documented in "Palm OS Events".
System Event Manager Data Structures

The following system event manager data structures are documented in the "Palm OS Events" chapter:
eventsEnum
EventType
EventPtr
System Event Manager Functions

EvtAddEventToQueue

Purpose
Add an event to the event queue.
Prototype
void EvtAddEventToQueue (const EventType *event)
Parameters
-> event | Pointer to the structure that contains the event. |
Result
Returns nothing.
Comments
This function makes a copy of the structure that you pass in and adds it to the event queue.
EvtAddUniqueEventToQueue

Purpose
Add an event to the event queue, replacing one of the same type if it is found.
Prototype
void EvtAddUniqueEventToQueue (const EventType *eventP, UInt32 id, Boolean inPlace)
Parameters
-> eventP | Pointer to the structure that contains the event. |
-> id | ID of the event. 0 means match only on the type. |
-> inPlace | If true, any existing event is replaced. If false, the existing event is deleted and a new event is added to end of queue. |
Result
Returns nothing.
Comments
This function looks for an event in the event queue of the same event type and ID (if specified). The routine replaces it with the new event, if found.
If no existing event is found, the new event is copied to the queue.
If an existing event is found, the routine proceeds as follows:
If inPlace is true, the existing event is replaced with a copy of the new event.
If inPlace is false, the existing event is removed and the new event is added to the end of the queue.
Compatibility
Implemented only if 2.0 New Feature Set is present.
EvtCopyEvent

Purpose
Copy an event.
Prototype
void EvtCopyEvent (const EventType *source, EventType *dest)
Parameters
-> source | Pointer to the structure containing the event to copy. |
<- dest | Pointer to the structure to copy the event to. |
Result
Returns nothing.
Comments
Use this function only if you want to create an event that has the same type as the source event. The data field in an EventType structure is specific to events of a given type. If you were to use this function to copy a keyDownEvent and then change it to a frmLoadEvent, the resulting frmLoadEvent would not have the proper data field.
If you want to create an event of a different type, do not use EvtCopyEvent. First clear the EventType structure using MemSet and then change the event type:
MemSet(&event, sizeof(EventType), 0);
event.eType = frmLoadEvent;
event.data.frmLoad.formID = formID;
EvtAddEventToQueue(&event);
EvtDequeuePenPoint

Purpose
Get the next pen point out of the pen queue. This function is called by recognizers.
Prototype
Err EvtDequeuePenPoint (PointType *retP)
Parameters
Result
Always returns 0.
Comments
Called by a recognizer that wishes to extract the points of a stroke. Returns the point (-1, -1) at the end of a stroke.
Before calling this routine, you must call EvtDequeuePenStrokeInfo.
EvtDequeuePenStrokeInfo

Purpose
Initiate the extraction of a stroke from the pen queue.
Prototype
Err EvtDequeuePenStrokeInfo (PointType *startPtP, PointType *endPtP)
Parameters
<- startPtP | Start point returned here. |
<- endPtP | End point returned here. |
Result
Always returns 0.
Comments
Called by the system function EvtGetSysEvent when a penUpEvent is being generated. This routine must be called before EvtDequeuePenPoint is called.
Subsequent calls to EvtDequeuePenPoint return points at the starting point in the stroke and including the end point. After the end point is returned, the next call to EvtDequeuePenPoint returns the point -1, -1.
See Also
EvtDequeuePenPoint
EvtEnableGraffiti

Purpose
Set Graffiti® enabled or disabled.
Prototype
void EvtEnableGraffiti (Boolean enable)
Parameters
-> enable | true to enable Graffiti, false to disable Graffiti. |
Result
Returns nothing.
EvtEnqueueKey

Purpose
Place keys into the key queue.
Prototype
Err EvtEnqueueKey (WChar ascii, UInt16 keycode, UInt16 modifiers)
Parameters
-> ascii | Character code for the key. |
-> keycode | Virtual key code of key. This is the keyCode field of the keyDownEvent and is currently unused. |
-> modifiers | Modifiers for keyDownEvent. |
Result
Returns 0 if successful, or evtErrParamErr if an error occurs.
Comments
This function disables interrupts while the queue header is being modified because both interrupt- and non-interrupt-level code can post keys into the queue.
Entries in the key queue only take 1 byte if the ascii parameter has a value less than 256 and the keycode and modifiers parameters are both zero. Otherwise an entry can take up to 7 bytes.
IMPORTANT: Make sure you pass a WChar as the ascii parameter, not a Char. If you pass a high-ASCII Char, the compiler sign-extends it to be a 16-bit value, resulting in the wrong character being added to the key queue.
EvtEventAvail

Purpose
Return true if an event is available.
Prototype
Boolean EvtEventAvail (void)
Parameters
Result
Returns true if an event is available, false otherwise.
Compatibility
Implemented only if 2.0 New Feature Set is present.
EvtFlushKeyQueue

Purpose
Flush all keys out of the key queue.
Prototype
Err EvtFlushKeyQueue (void)
Parameters
Result
Always returns 0.
Comments
Called by the system function EvtSetPenQueuePtr.
EvtFlushNextPenStroke

Purpose
Flush the next stroke out of the pen queue.
Prototype
Err EvtFlushNextPenStroke ()
Parameters
Result
Always returns 0.
Comments
Called by recognizers that need only the start and end points of a stroke. If a stroke has already been partially dequeued (by EvtDequeuePenStrokeInfo) this routine finishes the stroke dequeueing. Otherwise, this routine flushes the next stroke in the queue.
See Also
EvtDequeuePenPoint
EvtFlushPenQueue

Purpose
Flush all points out of the pen queue.
Prototype
Err EvtFlushPenQueue (void)
Parameters
Result
Always returns 0.
Comments
Called by the system function EvtSetKeyQueuePtr.
See Also
EvtPenQueueSize
EvtGetEvent

Purpose
Return the next available event.
Prototype
void EvtGetEvent (EventType *event, Int32 timeout)
Parameters
<- event | Pointer to the structure to hold the event returned. |
-> timeout | Maximum number of ticks to wait before an event is returned (evtWaitForever means wait indefinitely). |
Comments
Pass evtWaitForever as the timeout in most instances. When running on the device, this makes the CPU go into doze mode until the user provides input. For applications that do animation, pass a timeout value greater than or equal to zero.
Note that a timeout value greater than or equal to zero is simply the maximum number of ticks which can elapse before EvtGetEvent returns an event. If any other event-including a nilEvent-occurs before this time has elapsed, EvtGetEvent will return that event. Otherwise, once the specified time has elapsed EvtGetEvent generates and returns a nilEvent. If you supply a value of zero for the timeout parameter, EvtGetEvent returns the event currently in the queue, or, if there aren't any events in the queue, it immediately generates and returns a nilEvent.
Result
Returns nothing.
EvtGetPen

Purpose
Return the current status of the pen.
Prototype
void EvtGetPen (Int16 *pScreenX, Int16 *pScreenY, Boolean *pPenDown)
Parameters
<- pScreenX | x location relative to display. |
<- pScreenY | y location relative to display. |
<- pPenDown | true or false. |
Result
Returns nothing.
Comments
Called by various UI routines.
See Also
KeyCurrentState
EvtGetPenBtnList

Purpose
Return a pointer to the silk-screen button array.
Prototype
const PenBtnInfoType *EvtGetPenBtnList (UInt16 *numButtons)
Parameters
<- numButtons | The number of elements in the returned array. |
Result
Returns a pointer to an array of the silk-screen buttons.
Comments
This function returns an array of PenBtnInfoType structures:
typedef struct PenBtnInfoType {
RectangleType boundsR;
WChar asciiCode;
UInt16 keyCode;
UInt16 modifiers;
} PenBtnInfoType;
The fields in the PenBtnInfoType contain the following information:
boundsR |
The button's bounding rectangle. |
asciiCode |
The character code generated when the button is tapped. This is typically a virtual character. |
keyCode |
Currently unused. |
modifiers |
Modifiers for the key down event. (See the description of the modifiers field for keyDownEvent.) |
The number of buttons is device-dependent. Even devices with the same Palm OS® version may have differing numbers of silk-screen buttons. For example, Japanese devices typically have four extra silk-screen buttons used to transliterate characters into different alphabets.
See Also
EvtProcessSoftKeyStroke
EvtGetSilkscreenAreaList

Purpose
Returns a pointer to the silk-screen area array. This array contains the bounds of each silk-screen area.
Prototype
const SilkscreenAreaType *EvtGetSilkscreenAreaList (UInt16 *numAreas)
Parameters
<- numAreas | The number of elements in the returned array. |
Result
Returns a pointer to an array containing the bounds of each silk-screen area.
Comments
This function returns an array of the SilkscreenAreaType structures:
typedef struct SilkscreenAreaType {
RectangleType bounds;
UInt32 areaType;
UInt16 index;
} SilkscreenAreaType;
The fields in this structure provide the following information.
bounds |
The area's bounds. |
areaType |
The area type, can be one of the following:
silkscreenRectGraffiti | The Graffiti area. |
silkscreenRectScreen | The entire silkscreen area. |
Palm PoweredTM devices not manufactured by Palm, Inc. may have other area types.
|
index |
If the area type is silkscreenRectGraffiti, this field is either alphaGraffitiSilkscreenArea to represent the portion where letters are entered or numericGraffitiSilkscreenArea to represent the portion where numbers are entered. |
Compatibility
Implemented only if 3.5 New Feature Set is present.
EvtKeydownIsVirtual

Purpose
Macro that indicates if eventP is a pointer to a virtual character key down event.
Prototype
EvtKeydownIsVirtual (eventP)
Parameters
Result
Returns true if the character is a letter in an alphabet or a numeric digit, false otherwise.
Comments
The macro assumes that the caller has already determined the event is a keyDownEvent.
This macro is intended for use by the system. Applications should use TxtGlueCharIsVirtual, contained in the PalmOSGlue Library.
Compatibility
Implemented in the Palm OS 3.5 SDK.
See Also
TxtGlueCharIsVirtual
EvtKeyQueueEmpty

Purpose
Return true if the key queue is currently empty.
Prototype
Boolean EvtKeyQueueEmpty (void)
Parameters
Result
Returns true if the key queue is currently empty, otherwise returns false.
Comments
Usually called by the key manager to determine if it should enqueue auto-repeat keys.
EvtKeyQueueSize

Purpose
Return the size of the current key queue in bytes.
Prototype
UInt32 EvtKeyQueueSize (void)
Parameters
Result
Returns size of queue in bytes.
Comments
Called by applications that wish to see how large the current key queue is.
EvtPenQueueSize

Purpose
Return the size of the current pen queue in bytes.
Prototype
UInt32 EvtPenQueueSize (void)
Parameters
Result
Returns size of queue in bytes.
Comments
Call this function to see how large the current pen queue is.
EvtProcessSoftKeyStroke

Purpose
Translate a stroke in the system area of the digitizer and enqueue the appropriate key events in to the key queue.
Prototype
Err EvtProcessSoftKeyStroke (PointType *startPtP, PointType *endPtP)
Parameters
-> startPtP | Start point of stroke. |
-> endPtP | End point of stroke. |
Result
Returns 0 if recognized, -1 if not recognized.
See Also
EvtGetPenBtnList, GrfProcessStroke
EvtResetAutoOffTimer

Purpose
Reset the auto-off timer.
Prototype
Err EvtResetAutoOffTimer (void)
Parameters
Result
Always returns 0.
Comments
Called by the serial link manager; can be called periodically by other managers.
EvtResetAutoOffTimer resets the auto-off timer so that the device does not turn off until at least the default amount of idle time has passed. You can use this function to ensure that the device doesn't automatically power off during a long operation without user input (for example, when there is a lot of serial port activity).
If you need more control over the auto-off timer and the 3.5 New Feature Set is present, consider using EvtSetAutoOffTimer instead of this function.
See Also
SysSetAutoOffTime
EvtSetAutoOffTimer

Purpose
Set the auto-off timer.
Prototype
Err EvtSetAutoOffTimer (EvtSetAutoOffCmd cmd, UInt16 timeout)
Parameters
-> cmd | One of the defined commands. |
-> timeout | A new timeout value in seconds. If cmd is ResetTimer, this parameter is ignored. |
Result
Always returns errNone.
Comments
Use EvtSetAutoOffTimer to ensure that the device doesn't automatically power off during a long operation that has no user input (for example, when there is a lot of serial port activity).
The cmd parameter specifies the operation you want to perform. It takes one of the following EvtSetAutoOffCmd constants:
SetAtLeast |
Make sure that the device won't turn off until timeout seconds of idle time has passed. (This operation only changes the current value if it's less than the value you specify.) |
SetExactly |
Set the timer to turn off in timeout seconds |
SetAtMost |
Make sure the device will turn before timeout seconds has passed. (This operation only changes the current value if it's greater than the value you specify.) |
SetDefault |
Change the default auto-off timeout to timeout seconds. |
ResetTimer |
Reset the auto-off timer so that the device does not turn off until at least the default seconds of idle time has passed. |
Compatibility
Implemented only if 3.5 New Feature Set is present.
See Also
EvtResetAutoOffTimer, SysSetAutoOffTime
EvtSetNullEventTick

Purpose
Make sure a nilEvent occurs in at least the specified number of ticks.
Prototype
Boolean EvtSetNullEventTick(UInt32 tick)
Parameters
-> tick | Maximum number of system ticks that should elapse before a nilEvent is added to the queue. |
Result
Returns true if timeout value changed, or false if it did not change.
Compatibility
In versions prior to Palm OS 3.5, this function was implemented as a macro.
EvtSysEventAvail

Purpose
Return true if a low-level system event (such as a pen or key event) is available.
Prototype
Boolean EvtSysEventAvail (Boolean ignorePenUps)
Parameters
ignorePenUps | If true, this routine ignores pen-up events when determining if there are any system events available. |
Result
Returns true if a system event is available.
Comment
Call EvtEventAvail to determine whether high-level software events are available.
Compatibility
Implemented only if 2.0 New Feature Set is present.
EvtWakeup

Purpose
Force the event manager to wake up and send a nilEvent to the current application.
Prototype
Err EvtWakeup (void)
Parameters
Result
Always returns 0.
Comments
Called by interrupt routines, like the sound manager and alarm manager.
See Also
EvtWakeupWithoutNilEvent
New EvtWakeupWithoutNilEvent

Purpose
Force the event manager to wake up without sending a nilEvent to the current application.
Prototype
Err EvtWakeupWithoutNilEvent()
Parameters
Result
Always returns 0.
Comments
Called by interrupt routines.
Compatibility
Implemented only if 4.0 New Feature Set is present.
See Also
EvtWakeup
|