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
EventType Struct
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, otherwisefalse
. -
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
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
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, orNULL
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, orNULL
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 toEvtCreateBackgroundThread()
that created the background thread.
Event Constants
Event Flags Enum
Purpose
Flags that accompany certain events.
Declared In
Event.h
Constants
-
evtPenPressureFlag = 0x0001
- This flag is set in the
flags
field of thepenDownMove
structure that accompanies apenDownEvent
orpenMoveEvent
if there is pen pressure information available. The pen pressure value, if available, can be found in thepenDownMove
structure'spressure
field.
Event Dispatch Types Enum
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
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
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
sysAppLaunchCmdBackground
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
EvtAcquireEventQueue Function
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
Returns
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
Purpose
Send an event to a specific event queue.
Declared In
Event.h
Prototype
status_t EvtAddEventToEventQueue ( EvtQueueHandlequeue
, const EventType*event
, EvtQueueHandlereplyQueue
)
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 callingEvtGetReplyEventQueue()
.
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
isNULL
.
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
Purpose
Add an event to the event queue.
Declared In
Event.h
Prototype
status_t EvtAddEventToQueue (
const EventType *event
)
Parameters
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
Purpose
Add an event to the event queue at a specified time.
Declared In
Event.h
Prototype
status_t EvtAddEventToQueueAtTime ( uint64_tabsoluteTime
, 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 theP_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
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 ( EvtQueueHandlequeue
, const EventType*event
, uint32_tuserCookie
, BooleaninPlace
)
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. Iffalse
, 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
istrue
, the existing event is replaced with a copy of the new event. - If
inPlace
isfalse
, the existing event is removed and the new event is added to the end of the queue.
EvtAddUniqueEventToQueue Function
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_tuserCookie
, BooleaninPlace
)
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. Iffalse
, 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
istrue
, the existing event is replaced with a copy of the new event. - If
inPlace
isfalse
, the existing event is removed and the new event is added to the end of the queue.
EvtAddUniqueEventToQueueAtTime Function
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_tabsoluteTime
, const EventType*eventP
, uint32_tuserCookie
, BooleaninPlace
)
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 theP_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. Iffalse
, 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 false
, the existing event is removed and the new event is added to the end of the queue.
EvtCreateBackgroundThread Function
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 ( DatabaseIDdb
, size_tstackSize
, uint8_tpriority
, EvtQueueHandlecallerQueue
, MemPtrdata
, size_tdataSize
)
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 callingEvtGetThreadEventQueue()
. -
→ 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
EvtDequeueKeyEvent Function
Purpose
Obtain the next key event from the key queue.
Declared In
Event.h
Prototype
status_t EvtDequeueKeyEvent ( EventType*event
, Booleanpeek
)
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. Iftrue
, 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
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
Returns
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
Purpose
Initiate the extraction of a stroke from the pen queue.
Declared In
Event.h
Prototype
status_t EvtDequeuePenStrokeInfo ( PointType*startPtP
, PointType*endPtP
)
Parameters
Returns
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
Purpose
Place keys into the key queue.
Declared In
Event.h
Prototype
status_t EvtEnqueueKey ( wchar32_tascii
, uint16_tkeycode
, uint16_tmodifiers
)
Parameters
-
→ ascii
- Character code for the key.
-
→ keycode
- Virtual key code of key. This is the
keyCode
field of thekeyDownEvent
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
Purpose
Determine if an event is available.
Declared In
Event.h
Prototype
Boolean EvtEventAvail ( void )
Parameters
Returns
Returns true
if an event is available, false
otherwise.
EvtEventToString Function
Purpose
Creates a string representation of an event, for debugging purposes.
Declared In
Event.h
Prototype
void EvtEventToString ( EventType*event
, char*str
, uint32_tbufsize
)
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
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
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
Returns
Comments
Normally you don't need to call this function. EvtGetEvent()
and IOSPoll()
both call it for you.
See Also
EvtFlushKeyQueue Function
Purpose
Flush all keys out of the key queue.
Declared In
Event.h
Prototype
status_t EvtFlushKeyQueue ( void )
Parameters
Returns
EvtFlushNextPenStroke Function
Purpose
Flush the next stroke out of the pen queue.
Declared In
Event.h
Prototype
status_t EvtFlushNextPenStroke ( void )
Parameters
Returns
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
EvtFlushPenQueue Function
Purpose
Flush all points out of the pen queue.
Declared In
Event.h
Prototype
status_t EvtFlushPenQueue ( void )
Parameters
Returns
EvtGetEvent Function
Purpose
Return the next available event from the current thread's event queue.
Declared In
Event.h
Prototype
void EvtGetEvent ( EventType*event
, int32_ttimeout
)
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
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
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
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
Purpose
Get a handle to the window that currently has the focus.
Declared In
Event.h
Prototype
WinHandle EvtGetFocusWindow ( void )
Parameters
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
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
orfalse
, indicating whether or not the pen is currently touching the screen.
Returns
See Also
EvtGetPenNative Function
Purpose
Get the current status of the pen using a window's active coordinate system.
Declared In
Event.h
Prototype
status_t EvtGetPenNative ( WinHandlewinH
, 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
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
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
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
Purpose
Obtain a handle to the current thread's event queue.
Declared In
Event.h
Prototype
EvtQueueHandle EvtGetThreadEventQueue ( void )
Parameters
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
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
Purpose
Determine whether the key queue is currently empty.
Declared In
Event.h
Prototype
Boolean EvtKeyQueueEmpty ( void )
Parameters
Returns
Returns true
if the key queue is currently empty, otherwise returns false
.
EvtLookupEventQueue Function
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
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
, EvtQueueHandlequeue
)
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
EvtReleaseEventQueue Function
Purpose
Release a reference on an event queue.
Declared In
Event.h
Prototype
void EvtReleaseEventQueue (
EvtQueueHandle queue
)
Parameters
Returns
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
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
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 isNULL
, the default filter function (which always returnsevtDispatchAbsorb
) 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
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
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
Returns
Comments
Called by interrupt routines, like the Sound Manager and Alarm Manager.
See Also
EvtWakeupWithoutNilEvent Function
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
Returns
Comments
See Also
Application-Defined Functions
EvtPenDispatchFunc Function
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.