45 System Event Manager

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. 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 elsewhere:

• eventsEnumfs
  
  
• 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.

EvtAddUniqueEventToQueue

Purpose

Look 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 added.

If an existing event is found, the routine proceeds as follows:

• If inPlace is true, the existing event is replaced with the new event.
  
  
• If inPlace is false, the existing event is removed and the new event will be added to the end.
  

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, existing event are replaced. If false, existing event is deleted and new event added to end of queue.

Result

Returns nothing.

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.

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.

See Also

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 penUp event 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

ASCII code of key.

keycode

Virtual key code of key.

modifiers

Modifiers for key event.

Result

Returns 0 if successful, or evtErrParamErr if an error occurs.

Comments

Called by the keyboard interrupt routine and the Graffiti and soft key recognizers. Note that because both interrupt- and noninterrupt-level code can post keys into the queue, this routine disables interrupts while the queue header is being modified.

Most keys in the queue take only 1 byte if they have no modifiers and no virtual key code, and are 8-bit ASCII. If a key event in the queue has modifiers or is a non-standard ASCII code, it takes up to 7 bytes of storage and has the following format:

evtKeyStringEscape	1 byte
ASCII code	2 bytes
virtual key code	2 bytes
modifiers	2 bytes

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 (void)

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 (-1 means wait indefinitely).

Comments

Pass timeout= -1 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 timeout >= 0.

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

Pointer to the variable to contain the number of buttons in the array.

Result

Returns a pointer to the array.

Comments

The array returned contains the bounds of each silk-screened button and the ASCII code and modifiers byte to generate for each button.

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

pointer to area count variable

Result

returns a pointer to the array and the number of elements in the array.

EvtKeydownIsVirtual

Purpose

Macro that indicates if eventP is a pointer to a virtual character key down event.

Prototype

#define EvtKeydownIsVirtual(eventP)
(((eventP)->data.keyDown.modifiers & virtualKeyMask) != 0)

Parameters

eventP

pointer to the structure that contains the event.

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 key down. With earlier versions of the OS, use TxtGlueCharIsVirtual in the PalmOSGlue Library.

Compatibility

Implemented in the Palm OS^® 3.5 SDK, but will work on older devices (at least on 3.0, perhaps on 2.0 and 1.0.)

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 to assure that the device doesn't automatically power off during a long operation without user input (for example, serial port activity).

Prototype

Err EvtResetAutoOffTimer (void)

Parameters

Result

Always returns 0.

Comments

Called by the serial link manager; can be called periodically by other managers. EvtResetAutoOffTimer just resets the timer, while EvtSetAutoOffTimer allows you to specify a time.

See Also

SysSetAutoOffTime EvtSetAutoOffTimer

EvtSetAutoOffTimer

Purpose

EvtSetAutoOffTimer can be called periodically by other managers to reset the auto-off timer.

Prototype

Err EvtSetAutoOffTimer(EvtSetAutoOffCmd cmd, UInt16 timeoutSecs)

Parameters

cmd

One of the defined commands.

timeout

A new timeout in seconds, ignored for the 'reset' command.

Result

Returns 0 if no error.

Comments

This assures that the device doesn't automatically power off during a long operation that doesn't have user input (like a lot of serial port activity, for example). It is also used to manage the auto-off timer in general.

These commands are currently defined:

SetAtLeast

Turn off in at least xxx seconds

SetExactly:

Set the timer to turn off in xxx seconds

SetAtMost:

Set the device to turn off in <= xxx seconds

SetDefault:

Change default auto-off timeout to xxx seconds

ResetTimer:

Reset the auto off timer.

---

NOTE:  

This functionality is only available in Palm OS 3.5 and later.

---

See Also

EvtResetAutoOffTimer SysSetAutoOffTime

EvtSetNullEventTick

Purpose

Set the tick when a null event is due, unless one is due sooner.

Prototype

Boolean EvtSetNullEventTick(UInt32 tick)

Parameters

tick

the tick when a null event should occur.

Result

Returns true if null tick count setting changed.

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.