Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

7    Event

Programming Basics

Exploring Palm OS®

This chapter provides reference documentation for the structures and functions that you use to manipulate events and event queues. This includes functions that allow you to create and communicate with threads in the background process.

The contents of this chapter are organized as follows:

Event Structures and Types
Event Constants
Event Launch Codes
Event Functions and Macros
Application-Defined Functions

The header file Event.h declares the API that this chapter describes. For reference documentation on some common system events, see Chapter 8, "Event Codes." For conceptual information on events and event queues, see Chapter 3, "Events and the Event Loop."

Event Structures and Types ^TOP^

EventType Struct ^TOP^

Purpose

The EventType structure contains all of the data associated with a system event. All event types have some common data. Most events also have data specific to those events. The event-specific data uses a union that is part of the EventType data structure.

The common data is documented below the structure. Chapter 8, "Event Codes," documents each event and provides details on the important data associated with each type of event.

Declared In

Event.h

Prototype

typedef struct EventType {
   eventsEnum eType;
   Boolean penDown;
   uint8_t padding_1;
   uint16_t padding_2;
   uint32_t tapCount;
   Coord screenX;
   Coord screenY;
   union {
      ...
   } data;
} EventType;
typedef EventType *EventPtr

Fields

eType
The type of the event. See "Event Codes Events" for a complete list of events.
penDown
true if the pen was down at the time of the event, otherwise false.
padding_1
Padding bytes, for alignment purposes.
padding_2
Padding bytes, for alignment purposes.
tapCount
The number of taps received at this location. This value is used mainly by fields. When the user taps in a text field, two taps selects a word, and three taps selects the entire line.
screenX
Window-relative position of the pen in pixels (number of pixels from the left bound of the window).
screenY
Window-relative position of the pen in pixels (number of pixels from the top left of the window).
data
The specific data for an event, if any. The data is a union, and its exact contents depend on the eType field. See Chapter 8, "Event Codes," for more information on the event types and the structures that may accompany them.

EvtQueueHandle Typedef ^TOP^

Purpose

A handle for a thread's event queue.

Declared In

Event.h

Prototype

typedef void *EvtQueueHandle

See Also

EvtAddEventToEventQueue(), EvtCreateBackgroundThread(), EvtGetReplyEventQueue(), EvtGetThreadEventQueue()

SysAppLaunchCmdBackgroundType Struct ^TOP^

Purpose

Structure that accompanies a sysAppLaunchCmdBackground launch code and provides data supplied to the EvtCreateBackgroundThread() call that created the background thread.

Declared In

Event.h

Prototype

typedef struct SysAppLaunchCmdBackgroundType {
   EvtQueueHandle callerQueue;
   MemPtr data;
   size_t dataSize;
} SysAppLaunchCmdBackgroundType

Fields

callerQueue
Event queue handle supplied when EvtCreateBackgroundThread() was called, or NULL if no handle was supplied. This handle is automatically released by the system when the thread terminates. This queue allows the background thread to post events back to the calling application.
data
Pointer to a data block supplied when EvtCreateBackgroundThread() was called, or NULL if no data block pointer was supplied. This pointer is automatically released by the system when the thread terminates.
dataSize
Size of the data block pointed to by the data field. This is the value supplied to the call to EvtCreateBackgroundThread() that created the background thread.

Event Constants ^TOP^

Event Flags Enum ^TOP^

Purpose

Flags that accompany certain events.

Declared In

Event.h

Constants

evtPenPressureFlag = 0x0001
This flag is set in the flags field of the penDownMove structure that accompanies a penDownEvent or penMoveEvent if there is pen pressure information available. The pen pressure value, if available, can be found in the penDownMove structure's pressure field.

Event Dispatch Types Enum ^TOP^

Purpose

Values returned by your pen event filter function indicating how a given pen event should be handled.

Declared In

Event.h

Prototype

typedef uint32_t EvtDispatchType;

Constants

evtDispatchAbsorb = 0
Deliver the event to the window and consume it.
evtDispatchFallthrough = 1
Ignore the pen event, and send it to the next window. Note that once you have allowed an event to fall through, you will not see this or any more events in the current motion delivered to your window.

Event Error Codes ^TOP^

Purpose

Error codes returned by the various Event and System Event Manager functions (those defined here and those defined in SysEvtMgr.h).

Declared In

Event.h

Constants

#define evtErrNoQueue (evtErrorClass | 5)
The specified event queue does not exist.
#define evtErrParamErr (evtErrorClass | 1)
One of the specified parameters is invalid.
#define evtErrQueueBusy (evtErrorClass | 4)
#define evtErrQueueEmpty (evtErrorClass | 3)
There are no events in the specified event queue.
#define evtErrQueueFull (evtErrorClass | 2)
The event could not be added to the queue because the event queue is full.

Miscellaneous Event Constants ^TOP^

Purpose

The header file Event.h defines these constants.

Declared In

Event.h

Constants

#define evtNoWait 0
A timeout value you can supply to EvtGetEvent() to cause it to return immediately if there are no events waiting in the event queue.
#define evtWaitForever -1
A timeout value you can supply to EvtGetEvent() to cause the CPU to go into doze mode until the user provides input.
#define virtualKeyMask (appEvtHookKeyMask | libEvtHookKeyMask | commandKeyMask)
Mask value used by the EvtKeydownIsVirtual() macro to determine if a given event is a virtual character key down event.

Event Launch Codes ^TOP^

sysAppLaunchCmdBackground ^TOP^

Purpose

Sent to the executable module that is launched in a background thread with EvtCreateBackgroundThread().

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdBackground 73


Parameters

The launch code's parameter block pointer references a SysAppLaunchCmdBackgroundType structure.

Event Functions and Macros ^TOP^

EvtAcquireEventQueue Function ^TOP^

Purpose

Acquires a reference on the given queue so that it won't become invalid until another EvtReleaseEventQueue() call is made on it.

Declared In

Event.h

Prototype

void EvtAcquireEventQueue (
   EvtQueueHandle queue
)

Parameters

queue
Handle to the event queue.

Returns

Nothing.

Comments

This function is useful if, for example, you've gotten an EvtQueueHandle from somewhere and now want to give it to another thread. Call EvtAcquireEventQueue() and then pass the EvtQueueHandle to the other thread. When the other thread is done with the event queue, it should call EvtReleaseEventQueue(). Unlike EvtGetThreadEventQueue(), EvtAcquireEventQueue() allows you to pass a handle to any event queue, not just the one associated with your thread.

EvtAddEventToEventQueue Function ^TOP^

Purpose

Send an event to a specific event queue.

Declared In

Event.h

Prototype

status_t EvtAddEventToEventQueue (
   EvtQueueHandle queue,
   const EventType *event,
   EvtQueueHandle replyQueue
)

Parameters

queue
Handle of the event queue to which the event is to be sent.
event
Pointer to the event structure representing the event to be sent.
replyQueue
Handle of the event queue to which a reply is to be sent, or NULL if the event handler doesn't need to generate an event in reply. The event handler can retrieve this value by calling EvtGetReplyEventQueue().

Returns

Returns errNone if the event was successfully added to the queue, or one of the following otherwise:

bndErrorDead
The process that was hosting the event queue has gone away.
evtErrQueueFull
The event queue is full, or the target thread associated with the queue has gone away.
evtErrNoQueue
queue is NULL.

Comments

Events can be sent with the restriction that only the top-level contents of the event structure will be copied. The event structure cannot contain pointers to strings or other data or objects.

See Also

EvtCreateBackgroundThread(), EvtGetThreadEventQueue(), EvtLookupEventQueue()

EvtAddEventToQueue Function ^TOP^

Purpose

Add an event to the event queue.

Declared In

Event.h

Prototype

status_t EvtAddEventToQueue (
   const EventType *event
)

Parameters

event
Pointer to the structure that contains the event.

Returns

Returns errNone if the event was successfully added to the event queue, or evtErrQueueFull otherwise.

Comments

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

EvtAddEventToQueueAtTime Function ^TOP^

Purpose

Add an event to the event queue at a specified time.

Declared In

Event.h

Prototype

status_t EvtAddEventToQueueAtTime (
   uint64_t absoluteTime,
   const EventType *event
)

Parameters

absoluteTime
The time, in milliseconds. This value is the number of milliseconds since the device was last reset; you can get the current time by calling SysGetRunTime() and converting the resulting value to milliseconds with the P_NS2MS() macro.
event
Pointer to the structure that contains the event.

Returns

Returns errNone if the event was successfully added to the event queue.

Comments

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

EvtAddUniqueEventToEventQueue Function ^TOP^

Purpose

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

Declared In

Event.h

Prototype

status_t EvtAddUniqueEventToEventQueue (
   EvtQueueHandle queue,
   const EventType *event,
   uint32_t userCookie,
   Boolean inPlace
)

Parameters

queue
Handle of the event queue to which the event is to be sent.
event
Pointer to the structure that contains the event.
userCookie
Event identifier. If this value is 0, this function matches on the first existing event that has the given type. Otherwise, it matches only on an event that has both the given type and the identifier supplied in this parameter.
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 errNone if the event was successfully added to the event queue, or evtErrQueueFull otherwise.

Comments

This function looks in the specified event queue for an event of the same event type and userCookie (if specified). The function replaces it with the new event, if found.

If no existing event is found, the new event is copied to the specified queue.

If an existing event is found, the function 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.

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

status_t EvtAddUniqueEventToQueue (
   const EventType *eventP,
   uint32_t userCookie,
   Boolean inPlace
)

Parameters

eventP
Pointer to the structure that contains the event.
userCookie
Event identifier. If this value is 0, this function matches on the first existing event that has the given type. Otherwise, it matches only on an event that has both the given type and the identifier supplied in this parameter.
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 errNone if the event was successfully added to the event queue, or evtErrQueueFull otherwise.

Comments

This function looks in the event queue for an event of the same event type and userCookie (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.

EvtAddUniqueEventToQueueAtTime Function ^TOP^

Purpose

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

Declared In

Event.h

Prototype

status_t EvtAddUniqueEventToQueueAtTime (
   uint64_t absoluteTime,
   const EventType *eventP,
   uint32_t userCookie,
   Boolean inPlace
)

Parameters

absoluteTime
The time, in milliseconds. This value is the number of milliseconds since the device was last reset; you can get the current time by calling SysGetRunTime() and converting the resulting value to milliseconds with the P_NS2MS() macro.
eventP
Pointer to the structure that contains the event.
userCookie
Event identifier. If this value is 0, this function matches on the first existing event that has the given type. Otherwise, it matches only on an event that has both the given type and the identifier supplied in this parameter.
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 errNone if the event was successfully added to the event queue, or evtErrQueueFull otherwise.

Comments

This function looks for an event in the event queue of the same event type and userCookie (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.

EvtCreateBackgroundThread Function ^TOP^

Purpose

Create a thread in the background process and return a handle to the thread's event queue, through which you can communicate with the background thread.

Declared In

Event.h

Prototype

EvtQueueHandle EvtCreateBackgroundThread (
   DatabaseID db,
   size_t stackSize,
   uint8_t priority,
   EvtQueueHandle callerQueue,
   MemPtr data,
   size_t dataSize
)

Parameters

db
Unique identifier for the database containing the code to be executed in the background thread.
stackSize
Size, in bytes, to be allocated to the background thread's stack.
priority
The requested thread priority. See "Thread Priorities" of Exploring Palm OS: System Management for constants that represent commonly-used thread priorities.
callerQueue
Event queue handle for the queue that the background thread is to use to communicate with the calling thread, or NULL if the background thread doesn't need to send events back to the calling thread. This is usually the calling application's event queue, which can be obtained by calling EvtGetThreadEventQueue().
data
Pointer to a block of data that will be made accessible to the background thread. This pointer accompanies the sysAppLaunchCmdBackground launch code. The data block cannot be more than 3kb in size (approximately).
dataSize
Size, in bytes, of the data block pointed to by data. This value is passed to the code running in the background thread.

Returns

Returns a handle to the background thread's event queue, or NULL if the background thread couldn't be started.

Comments

Events can be sent to the background thread through the queue as in the local process, with the restriction that only top-level contents of the event structure will be copied. The event structure cannot contain pointers to strings or other data or objects.

The caller queue and data are propagated to the new thread through the launch code as described below. Supplying NULL for any of these is valid.

Be sure to call EvtReleaseEventQueue() when you are done with this queue (though only doing that will not make the thread go away). You'll need a handle to the caller queue; this means that you should not do something like this:


myHandle = EvtCreateBackgroundThread(..., 
EvtGetThreadEventQueue(), ...); 

The above function enters PilotMain() with the launch code sysAppLaunchCmdBackground and a SysAppLaunchCmdBackgroundType data structure.


NOTE: EvtCreateBackgroundThread() does not guarantee that the requested priority will be satisfied. A return value of errNone does not guarantee that the thread has been created at requested priority. Depending upon the context in which the function was called, the actual thread priority may be lower than what was requested.

See Also

SysThreadCreate()

EvtDequeueKeyEvent Function ^TOP^

Purpose

Obtain the next key event from the key queue.

Declared In

Event.h

Prototype

status_t EvtDequeueKeyEvent (
   EventType *event,
   Boolean peek
)

Parameters

event
Pointer to an event structure that is filled in with the details of the next event on the key queue.
peek
If false, the key event is removed from the key queue. If true, it is left in the key queue.

Returns

Returns errNone if the key queue contained at least one key event, or evtErrQueueEmpty if there are no key events in the key queue.

EvtDequeuePenPoint Function ^TOP^

Purpose

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

Declared In

Event.h

Prototype

status_t EvtDequeuePenPoint (
   PointType *retP
)

Parameters

retP
Return point.

Returns

Always returns errNone.

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

Event.h

Prototype

status_t EvtDequeuePenStrokeInfo (
   PointType *startPtP,
   PointType *endPtP
)

Parameters

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

Returns

Always returns errNone.

Comments

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.

EvtEnqueueKey Function ^TOP^

Purpose

Place keys into the key queue.

Declared In

Event.h

Prototype

status_t EvtEnqueueKey (
   wchar32_t ascii,
   uint16_t keycode,
   uint16_t 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 errNone if successful, or evtErrParamErr if an error occurs.

Comments


IMPORTANT: Make sure you pass a wchar32_t as the ascii parameter, not a char. If you pass a high-ASCII char, the compiler sign-extends it to be a 32-bit value, resulting in the wrong character being added to the key queue.

EvtEventAvail Function ^TOP^

Purpose

Determine 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.

EvtEventToString Function ^TOP^

Purpose

Creates a string representation of an event, for debugging purposes.

Declared In

Event.h

Prototype

void EvtEventToString (
   EventType *event,
   char *str,
   uint32_t bufsize
)

Parameters

event
The event for which a string representation is to be created.
str
A string buffer into which the string representation is written.
bufsize
The size of the string buffer str.

Returns

Nothing.

Comments

The string representation includes the event type, an indication of whether the pen was touching the screen at the time the event was generated, the tap count, and the x and y coordinates identifying the pen location. It also includes event-specific information, if appropriate. You can use the string produced by this function to log events as an aid to debugging.

EvtFinishLastEvent Function ^TOP^

Purpose

Indicate that you are done processing an event obtained before blocking on the IOS file descriptor for the event queue.

Declared In

Event.h

Prototype

void EvtFinishLastEvent (
   void
)

Parameters

None.

Returns

Nothing.

Comments

Normally you don't need to call this function. EvtGetEvent() and IOSPoll() both call it for you.

See Also

EvtGetEventDescriptor()

EvtFlushKeyQueue Function ^TOP^

Purpose

Flush all keys out of the key queue.

Declared In

Event.h

Prototype

status_t EvtFlushKeyQueue (
   void
)

Parameters

None.

Returns

Always returns errNone.

EvtFlushNextPenStroke Function ^TOP^

Purpose

Flush the next stroke out of the pen queue.

Declared In

Event.h

Prototype

status_t EvtFlushNextPenStroke (
   void
)

Parameters

None.

Returns

Always returns errNone.

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

Purpose

Flush all points out of the pen queue.

Declared In

Event.h

Prototype

status_t EvtFlushPenQueue (
   void
)

Parameters

None.

Returns

Always returns errNone.

EvtGetEvent Function ^TOP^

Purpose

Return the next available event from the current thread's event queue.

Declared In

Event.h

Prototype

void EvtGetEvent (
   EventType *event,
   int32_t 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, evtNoWait means don't wait at all).

Returns

Nothing.

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 (evtNoWait has a value of 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() returns 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.

EvtGetEventDescriptor Function ^TOP^

Purpose

Get an IOS file descriptor that you can block on until events arrive in your queue.

Declared In

Event.h

Prototype

int32_t EvtGetEventDescriptor (
   void
)

Parameters

None.

Returns

Returns the IOS file descriptor for the event queue, or a value less than zero if an error occurred while obtaining the file descriptor.

Comments

This function only works for the main UI thread. Outside of the main UI thread you should use the multithreading APIs to do I/O instead of multiplexing with an event thread.

Rather than making repeated calls to EvtGetEvent(), you can instead obtain an IOS file descriptor using this function and block on that file descriptor. When an event is posted to your event queue, your application will wake up and can then process the event. Note that when using this technique you must let the operating system know when you are done with the event. IOSPoll() does this for you, or you can make a call to EvtFinishLastEvent().

On debug ROMs, this function displays a fatal alert if the calling thread is not the main UI thread.

EvtGetFocusWindow Function ^TOP^

Purpose

Get a handle to the window that currently has the focus.

Declared In

Event.h

Prototype

WinHandle EvtGetFocusWindow (
   void
)

Parameters

None.

Returns

Returns a handle to the last window that received a winFocusGainedEvent, or, if a winFocusGainedEvent has not been returned from EvtGetEvent() since the last winFocusLostEvent, returns invalidWindowHandle (this constant is defined in Window.h).

EvtGetPen Function ^TOP^

Purpose

Return the current status of the pen.

Declared In

Event.h

Prototype

status_t EvtGetPen (
   Coord *pScreenX,
   Coord *pScreenY,
   Boolean *pPenDown
)

Parameters

pScreenX
x location, in standard coordinates, relative to the draw window.
pScreenY
y location, in standard coordinates, relative to the draw window.
pPenDown
true or false, indicating whether or not the pen is currently touching the screen.

Returns

Always returns errNone.

See Also

EvtGetPenNative()

EvtGetPenNative Function ^TOP^

Purpose

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

Declared In

Event.h

Prototype

status_t EvtGetPenNative (
   WinHandle winH,
   Coord *pScreenX,
   Coord *pScreenY,
   Boolean *pPenDown
)

Parameters

winH
Handle to a valid window.
pScreenX
x location, in active coordinates, relative to the window.
pScreenY
y location, in active coordinates, relative to the window.
pPenDown
true if the pen is down, false otherwise.

Returns

Always returns errNone.

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.

EvtGetReplyEventQueue Function ^TOP^

Purpose

Obtain the event queue through which you can post a reply to the event being processed.

Declared In

Event.h

Prototype

EvtQueueHandle EvtGetReplyEventQueue (
   void
)

Parameters

None.

Returns

A handle to the reply event queue, or NULL if the event handler isn't expected to post a reply.

Comments

Used by event handlers to post a response to the thread that sent the event. The reply queue handle is specified when the event is originally sent, as a parameter to EvtAddEventToEventQueue().

You must call EvtReleaseEventQueue() when done with the queue returned by this function.

See Also

EvtGetThreadEventQueue(), EvtLookupEventQueue()

EvtGetThreadEventQueue Function ^TOP^

Purpose

Obtain a handle to the current thread's event queue.

Declared In

Event.h

Prototype

EvtQueueHandle EvtGetThreadEventQueue (
   void
)

Parameters

None.

Returns

Returns a handle to the event queue.

Comments

Given a handle to a thread's event queue, you can use EvtAddEventToEventQueue() to add events to the thread's event queue from any other thread in the process. When you are done with the thread's event queue, call EvtReleaseEventQueue() to allow the system to reclaim the queue's resources.

See Also

EvtGetReplyEventQueue(), EvtLookupEventQueue()

EvtKeydownIsVirtual Macro ^TOP^

Purpose

Determine if a given event is a virtual character key down event.

Declared In

Event.h

Prototype

#define EvtKeydownIsVirtual (
   eventP
)

Parameters

eventP
Pointer to an EventType structure.

Returns

Evaluates to 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.

EvtKeyQueueEmpty Function ^TOP^

Purpose

Determine whether the key queue is currently empty.

Declared In

Event.h

Prototype

Boolean EvtKeyQueueEmpty (
   void
)

Parameters

None.

Returns

Returns true if the key queue is currently empty, otherwise returns false.

EvtLookupEventQueue Function ^TOP^

Purpose

Look up an event queue by name.

Declared In

Event.h

Prototype

EvtQueueHandle EvtLookupEventQueue (
   const char *name
)

Parameters

name
The name of the event queue, as published by EvtPublishEventQueue().

Returns

Returns a handle to the event queue if the named queue was found, or NULL if an event queue with the given name couldn't be located.

Comments

You must call EvtReleaseEventQueue() when you are done with the queue returned by this function.

Published queues persist across application switches, but note that if the queue refers to a thread in the Application process, after an application switch that queue will be dead and errors will be returned if you attempt to use it.

See Also

EvtGetReplyEventQueue(), EvtGetThreadEventQueue(), EvtPublishEventQueue()

EvtPublishEventQueue Function ^TOP^

Purpose

Publish (or withdraw from publication) an event queue name, so that code executing in other threads can gain access to the queue simply by knowing the event queue name.

Declared In

Event.h

Prototype

status_t EvtPublishEventQueue (
   const char *name,
   EvtQueueHandle queue
)

Parameters

name
The name by which the event queue is to be known (or the name of the published event queue that is to be withdrawn from publication).
queue
The event queue's handle, if publishing, or NULL to withdraw an event queue from publication.

Returns

Returns errNone if the operation was successfully completed, or an error value otherwise.

Comments

The functionality provided by this function and by EvtLookupEventQueue() allows an application that operates in conjunction with a background thread to attach to its already running background thread whenever the application starts. For instance, a media player that uses a background thread to perform playback or recording operations could use this to reestablish communications with the background thread after the user has switched away from and then back to the media player UI application.

Event queues should use Java-style naming conventions. For example, "com.palmsource.someapp.myqueue".

Published queues persist across application switches, but note that if the queue refers to a thread in the Application process, after an application switch that queue will be dead and errors will be returned if you attempt to use it.

See Also

EvtLookupEventQueue()

EvtReleaseEventQueue Function ^TOP^

Purpose

Release a reference on an event queue.

Declared In

Event.h

Prototype

void EvtReleaseEventQueue (
   EvtQueueHandle queue
)

Parameters

queue
Handle to the event queue to be released.

Returns

Nothing.

Comments

Call this function to release a reference on the queue. Once all references are gone—including the one implicitly held by the thread running the queue and from publishing the queue—the system will reclaim the queue's resources.

See Also

EvtCreateBackgroundThread(), EvtGetReplyEventQueue(), EvtGetThreadEventQueue(), EvtLookupEventQueue()

EvtSetNullEventTick Function ^TOP^

Purpose

Make sure that a nilEvent occurs in at least the specified amount of time.

Declared In

Event.h

Prototype

Boolean EvtSetNullEventTick (
   int64_t milliseconds
)

Parameters

milliseconds
Maximum amount of time, in milliseconds, that should elapse before a nilEvent is added to the queue.

Returns

Returns true if timeout value changed, or false if it did not change.

EvtSetPenDispatchFunc Function ^TOP^

Purpose

Set the pen event filter function for a given window.

Declared In

Event.h

Prototype

extern status_t EvtSetPenDispatchFunc (
   WinHandle winHandle,
   EvtPenDispatchFunc penDispatch,
   void *userData
)

Parameters

winHandle
Handle to the window for which the pen event filter function is being set.
penDispatch
Pointer to the filter function, which must have a prototype as defined by EvtPenDispatchFunc(). If this parameter is NULL, the default filter function (which always returns evtDispatchAbsorb) is used.
userData
Pointer that can be used to pass application-specific data to the pen event filter function. If the filter function requires no such data, pass NULL for this parameter.

Returns

Always returns errNone. On a debug ROM, this function generates a fatal error if the supplied window handle is invalid.

Comments

A pen event filter function is a function that you write that allows you to control which pen taps are passed on to your window's event queue, and which are passed on to other windows that may be beneath yours. Such "pen event filters" are used primarily by overlay pinlets, although they can be used by any window; they are not limited to use by pinlets.

EvtSysEventAvail Function ^TOP^

Purpose

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

Declared In

Event.h

Prototype

Boolean EvtSysEventAvail (
   Boolean ignorePenUps
)

Parameters

ignorePenUps
If true, this function 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.

EvtWakeup Function ^TOP^

Purpose

Force the Event Manager to wake up and send a nilEvent to the current application.

Declared In

Event.h

Prototype

status_t EvtWakeup (
   void
)

Parameters

None.

Returns

Always returns errNone.

Comments

Called by interrupt routines, like the Sound Manager and Alarm Manager.

See Also

EvtWakeupWithoutNilEvent()

EvtWakeupWithoutNilEvent Function ^TOP^

Purpose

Force the Event Manager to wake up without sending a nilEvent to the current application.

Declared In

Event.h

Prototype

status_t EvtWakeupWithoutNilEvent (
   void
)

Parameters

None.

Returns

Always returns errNone.

Comments

Called by interrupt routines.

See Also

EvtWakeup()

Application-Defined Functions ^TOP^

EvtPenDispatchFunc Function ^TOP^

Purpose

A callback function that allows you to control which pen taps are passed on to your window's event queue, and which are passed on to other windows that may be beneath yours. Such "pen event filters" are used primarily by overlay ("on screen input") pinlets, although they can be used by any window; they are not limited to use by pinlets. They can be used to implement windows with irregular shapes and more sophisticated effects.

Declared In

Event.h

Prototype

typedef EvtDispatchType (
   *EvtPenDispatchFunc
) (
   const EventType *penEvent,
   const RectangleType *nativeFrame,
   void *userData
)

Parameters

penEvent
The pen event to be filtered.
nativeFrame
The target window's frame.
userData
Pointer to an optional application-defined data block specified during the call to EvtSetPenDispatchFunc().

Returns

Return one of the values defined by the Event Dispatch Types enum to indicate whether the event should be absorbed or passed on to the next window layer.

Comments

This function is called for each pen event delivered to the window, allowing you to decide what to do with the event. Return evtDispatchAbsorb for those events that should be placed on your window's event queue, or evtDispatchFallthrough for those that should "fall through" to the next window beneath. Note that once you have allowed an event to fall through, any subsequent events in the current motion will not be delivered to your window.


NOTE: This function is called from outside of the window's event thread. You cannot access any UI state from it.

A typical EvtPenDispatchFunc() implementation will usually do nothing more than check if the pen is in a certain region of the window (and possibly check some internal state of the pinlet) before returning the appropriate value.

It is important to understand that the dispatch function set here is called as part of the system's lower-level event dispatching mechanism, before the event is placed in the target window's event queue. This means:

  • The function is called in a system thread, not in the window's event thread, and so it cannot access any of that thread's UI state. In particular it can't make any Window Manager or standard Event Manager calls. You can use the multi-threaded Event Manager functions to communicate from this thread to the UI thread, however. You can also count on the thread running in the same process as your window, so you can access common globals and the userData parameter can contain a pointer to a shared data structure on the local heap.
  • When using this function you must have a good understanding of multithreading to correctly synchronize calls to the dispatch function with whatever is going on in the UI thread. Not properly taking care of multi-threaded issues can result in application crashes and other bad behavior.
  • This dispatch function is called as part of the low-level system event dispatching, and thus should do as little possible to decide what to do with each event it is given.

This function provides very direct access to the operating system's event processing, and as such developers should be very careful when using it. Take care to call as few operating system functions as possible: avoid the Data Manager, any UI functions besides the multithreaded Event Manager functions, and any other high level functions such as those involving the status bar, the dynamic input area, and the like. While some of these functions may happen to work in current versions of the operating system, future versions of the system may not be able to support them.