< Home < Developers < Development Support < Documentation

## 49 System Event Manager

Table of Contents | < Previous | Next > | Index

| Title - Palm OS® Programmer's API Reference Part II: System Management 49 System Event Manager System Event Manager Data Structures System Event Manager Functions EvtAddEventToQueue EvtAddUniqueEventToQueue EvtCopyEvent EvtDequeuePenPoint EvtDequeuePenStrokeInfo EvtEnableGraffiti EvtEnqueueKey EvtEventAvail EvtFlushKeyQueue EvtFlushNextPenStroke EvtFlushPenQueue EvtGetEvent EvtGetPen EvtGetPenBtnList EvtGetSilkscreenAreaList EvtKeydownIsVirtual EvtKeyQueueEmpty EvtKeyQueueSize EvtPenQueueSize EvtProcessSoftKeyStroke EvtResetAutoOffTimer EvtSetAutoOffTimer EvtSetNullEventTick EvtSysEventAvail EvtWakeup EvtWakeupWithoutNilEvent |  |  |  | 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 #####
<- retP | Return point.
#### 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 #####
None.
#### 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 #####
None.
#### 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 #####
None.
#### 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 #####
None
#### 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 #####
-> eventP | Pointer to an EventType structure.
#### 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 #####
None.
#### 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 #####
None.
#### 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 #####
None.
#### 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 #####
None.
#### 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 #####
None.
#### 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 #####
None.
#### Result Always returns 0. #### Comments Called by interrupt routines. #### Compatibility Implemented only if 4.0 New Feature Set is present. #### See Also EvtWakeup |