(68K) System Event Manager | Palm OS® Programmer's API Reference

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 ^TOP^

The following system event manager data structures are documented in the "Palm OS Events" chapter:

System Event Manager Functions ^TOP^

EvtAddEventToQueue Function ^TOP^

Purpose

Add an event to the event queue.

Declared In

Event.h

Prototype

void EvtAddEventToQueue (
   const EventType *event
)

Parameters

→ event: Pointer to the structure that contains the event.

Returns

Returns nothing.

Comments

This function makes a copy of the structure that you pass in and adds it to the event queue.

EvtAddUniqueEventToQueue Function ^TOP^

Purpose

Add an event to the event queue, replacing one of the same type if it is found.

Declared In

Event.h

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.

Returns

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 Function ^TOP^

Purpose

Copy an event.

Declared In

Event.h

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.

Returns

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 Function ^TOP^

Purpose

Get the next pen point out of the pen queue. This function is called by recognizers.

Declared In

SysEvtMgr.h

Prototype

Err EvtDequeuePenPoint (
   PointType *retP
)

Parameters

← retP: Return point.

Returns

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 Function ^TOP^

Purpose

Initiate the extraction of a stroke from the pen queue.

Declared In

SysEvtMgr.h

Prototype

Err EvtDequeuePenStrokeInfo (
   PointType *startPtP,
   PointType *endPtP
)

Parameters

← startPtP: Start point returned here.
← endPtP: End point returned here.

Returns

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.

EvtEnableGraffiti Function ^TOP^

Purpose

Enable or disable Graffiti^® or Graffiti 2 handwriting recognition.

Declared In

SysEvtMgr.h

Prototype

void EvtEnableGraffiti (
   Boolean enable
)

Parameters

→ enable: true to enable handwriting recognition, false to disable it.

Returns

Returns nothing.

EvtEnqueueKey Function ^TOP^

Purpose

Place keys into the key queue.

Declared In

SysEvtMgr.h

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.

Returns

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 Function ^TOP^

Purpose

Return true if an event is available.

Declared In

Event.h

Prototype

Boolean EvtEventAvail (
   void
)

Parameters

None.

Returns

Returns true if an event is available, false otherwise.

Compatibility

Implemented only if 2.0 New Feature Set is present.

EvtFlushKeyQueue Function ^TOP^

Purpose

Flush all keys out of the key queue.

Declared In

SysEvtMgr.h

Prototype

Err EvtFlushKeyQueue (
   void
)

Parameters

None.

Returns

Always returns 0.

Comments

Called by the system function EvtSetPenQueuePtr.

EvtFlushNextPenStroke Function ^TOP^

Purpose

Flush the next stroke out of the pen queue.

Declared In

SysEvtMgr.h

Prototype

Err EvtFlushNextPenStroke ()

Parameters

None.

Returns

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.

EvtFlushPenQueue Function ^TOP^

Purpose

Flush all points out of the pen queue.

Declared In

SysEvtMgr.h

Prototype

Err EvtFlushPenQueue (
   void
)

Parameters

None

Returns

Always returns 0.

Comments

Called by the system function EvtSetKeyQueuePtr.

EvtGetEvent Function ^TOP^

Purpose

Return the next available event.

Declared In

Event.h

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.

Returns

Returns nothing.

EvtGetPen Function ^TOP^

Purpose

Return the current status of the pen.

Declared In

Event.h

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.

Returns

Returns nothing.

Comments

Called by various UI routines.

EvtGetPenBtnList Function ^TOP^

Purpose

Return a pointer to the silk-screen button array.

Declared In

SysEvtMgr.h

Prototype

const PenBtnInfoType *EvtGetPenBtnList(
   UInt16 *numButtons
)

Parameters

← numButtons: The number of elements in the returned array.

Returns

Returns a pointer to an array of the silk-screen buttons.

Comments

This function returns an array of PenBtnInfoType structures:

Prototype

typedef struct PenBtnInfoType {
  RectangleType boundsR;
  WChar asciiCode;
  UInt16 keyCode;
  UInt16 modifiers;
} PenBtnInfoType;

Fields

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.

Compatibility

If Palm OS Cobalt Feature Set is present this function is unimplemented.

EvtGetPenNative Function ^TOP^

Purpose

Get the current status of the pen using a window's active coordinate system.

Declared In

Window.h

Prototype

void EvtGetPenNative (
   WinHandle winH,
   Int16 *pScreenX,
   Int16 *pScreenY,
   Boolean *pPenDown
)

Parameters

→ winH: Handle to a valid window.
← pScreenX: x location relative to the window.
← pScreenY: y location relative to the window.
← pPenDown: true if the pen is down, false otherwise.

Returns

Returns nothing.

Comments

This function is a variation on EvtGetPen(). EvtGetPen returns a pen sample using the standard coordinate system, relative to the draw window, whereas EvtGetPenNative returns a pen sample using the active coordinate system of winH, relative to the window origin. If the active coordinate system is high density, the returned pen sample uses high-density coordinates.

On a debug ROM this function displays an error if winH doesn't reference a valid window object.

Compatibility

Implemented only if the High-Density Display Feature Set is present.

EvtGetSilkscreenAreaList Function ^TOP^

Purpose

Returns a pointer to the silk-screen area array. This array contains the bounds of each silk-screen area.

Declared In

SysEvtMgr.h

Prototype

const SilkscreenAreaType *EvtGetSilkscreenAreaList(
   UInt16 *numAreas
)

Parameters

← numAreas: The number of elements in the returned array.

Returns

Returns a pointer to an array containing the bounds of each silk-screen area.

Comments

This function returns an array of the SilkscreenAreaType structures:

Prototype

typedef struct SilkscreenAreaType {
  RectangleType bounds;
  UInt32 areaType;
  UInt16 index;
  } SilkscreenAreaType;

Fields

bounds: The area's bounds.
areaType: The area type, can be one of the following:; Depending on the handheld manufacturer, Palm Powered^™ devices 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. If 5.0 New Feature Set is present, this function should be considered "System Use Only"; applications should do what they can to avoid using it.

EvtKeydownIsVirtual Macro ^TOP^

Purpose

Indicates if eventP is a pointer to a virtual character key down event.

Declared In

Event.h

Prototype

#define EvtKeydownIsVirtual (
   eventP
)

Parameters

→ eventP: Pointer to an EventType structure.

Returns

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.

EvtKeyQueueEmpty Function ^TOP^

Purpose

Return true if the key queue is currently empty.

Declared In

SysEvtMgr.h

Prototype

Boolean EvtKeyQueueEmpty (
   void
)

Parameters

None.

Returns

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 Function ^TOP^

Purpose

Return the size of the current key queue in bytes.

Declared In

SysEvtMgr.h

Prototype

UInt32 EvtKeyQueueSize (
   void
)

Parameters

None.

Returns

Returns size of queue in bytes.

Comments

Called by applications that wish to see how large the current key queue is.

Compatibility

If Palm OS Cobalt Feature Set is present this function is unimplemented.

EvtPenQueueSize Function ^TOP^

Purpose

Return the size of the current pen queue in bytes.

Declared In

SysEvtMgr.h

Prototype

UInt32 EvtPenQueueSize (
   void
)

Parameters

None.

Returns

Returns size of queue in bytes.

Comments

Call this function to see how large the current pen queue is.

Compatibility

If Palm OS Cobalt Feature Set is present this function is unimplemented.

EvtProcessSoftKeyStroke Function ^TOP^

Purpose

Translate a stroke in the system area of the digitizer and enqueue the appropriate key events in to the key queue.

Declared In

SysEvtMgr.h

Prototype

Err EvtProcessSoftKeyStroke (
   PointType *startPtP,
   PointType *endPtP
)

Parameters

→ startPtP: Start point of stroke.
→ endPtP: End point of stroke.

Returns

Returns 0 if recognized, -1 if not recognized.

Compatibility

If Palm OS Cobalt Feature Set is present this function is unimplemented.

EvtResetAutoOffTimer Function ^TOP^

Purpose

Reset the auto-off timer.

Declared In

SysEvtMgr.h

Prototype

Err EvtResetAutoOffTimer (
   void
)

Parameters

None.

Returns

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.

EvtSetAutoOffTimer Function ^TOP^

Purpose

Set the auto-off timer.

Declared In

SysEvtMgr.h

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.

Returns

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.

EvtSetNullEventTick Function ^TOP^

Purpose

Make sure a nilEvent occurs by the specified time, specified in ticks since the last reset.

Declared In

SysEvtMgr.h

Prototype

Boolean EvtSetNullEventTick(
   UInt32 tick
)

Parameters

→ tick: The time, in ticks, since the last reset by which a nilEvent is to be added to the queue.

Returns

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 Function ^TOP^

Purpose

Return true if a low-level system event (such as a pen or key event) is available.

Declared In

SysEvtMgr.h

Prototype

Boolean EvtSysEventAvail (
   Boolean ignorePenUps
)

Parameters

ignorePenUps: If true, this routine ignores pen-up events when determining if there are any system events available.

Returns

Returns true if a system event is available.

Comments

Call EvtEventAvail() to determine whether high-level software events are available.

Compatibility

Implemented only if 2.0 New Feature Set is present.

EvtWakeup Function ^TOP^

Purpose

Force the event manager to wake up and send a nilEvent to the current application.

Declared In

SysEvtMgr.h

Prototype

Err EvtWakeup (
   void
)

Parameters

None.

Returns

Always returns 0.

Comments

Called by interrupt routines, like the sound manager and alarm manager.

EvtWakeupWithoutNilEvent Function ^TOP^

Purpose

Force the event manager to wake up without sending a nilEvent to the current application.

Declared In

SysEvtMgr.h

Prototype

Err EvtWakeupWithoutNilEvent()

Parameters

None.

Returns

Always returns 0.

Comments

Called by interrupt routines.

Compatibility

Implemented only if 4.0 New Feature Set is present.

53 System Event Manager

System Event Manager Data Structures ^TOP^

System Event Manager Functions ^TOP^

EvtAddEventToQueue Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

EvtAddUniqueEventToQueue Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

Compatibility

EvtCopyEvent Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

EvtDequeuePenPoint Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

EvtDequeuePenStrokeInfo Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

See Also

EvtEnableGraffiti Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

EvtEnqueueKey Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

EvtEventAvail Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Compatibility

EvtFlushKeyQueue Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

EvtFlushNextPenStroke Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

See Also

EvtFlushPenQueue Function ^TOP^

Purpose

Declared In

Prototype

Parameters