System Event Manager
 

 < 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

-> eventPointer 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

-> eventPPointer to the structure that contains the event.
-> idID of the event. 0 means match only on the type.
-> inPlaceIf 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

-> sourcePointer to the structure containing the event to copy.
<- destPointer 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

<- retPReturn 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

<- startPtPStart point returned here.
<- endPtPEnd 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

-> enabletrue 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

-> asciiCharacter code for the key.
-> keycodeVirtual key code of key. This is the keyCode field of the keyDownEvent and is currently unused.
-> modifiersModifiers 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

<- eventPointer to the structure to hold the event returned.
-> timeoutMaximum 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

<- pScreenXx location relative to display.
<- pScreenYy location relative to display.
<- pPenDowntrue 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

<- numButtonsThe 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.
silkscreenRectScreenThe 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

-> eventPPointer 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

-> startPtPStart point of stroke.
-> endPtPEnd 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

-> cmdOne of the defined commands.
-> timeoutA 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

-> tickMaximum 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

ignorePenUpsIf 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