This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

`PhEvent_t`

Data structure describing an event

Synopsis:

typedef struct Ph_event {
    unsigned long       type;
    unsigned short      subtype;
    unsigned short      processing_flags;
    PhEventRegion_t     emitter;
    PhEventRegion_t     collector;
    unsigned short      input_group;
    unsigned short      flags;
    unsigned long       timestamp;
    PhPoint_t           translation;
    unsigned short      num_rects;
    unsigned short      data_len;
} PhEvent_t;

Description:

The PhEvent_t structure describes an event. It contains at least the following members:

type

One -- and only one -- of the predefined event types:

Ph_EV_BOUNDARY
Ph_EV_BUT_PRESS
Ph_EV_BUT_RELEASE
Ph_EV_BUT_REPEAT
Ph_EV_DNDROP
Ph_EV_DRAG
Ph_EV_DRAW
Ph_EV_EXPOSE
Ph_EV_INFO
Ph_EV_KEY
Ph_EV_PTR_MOTION_BUTTON
Ph_EV_PTR_MOTION_NOBUTTON
Ph_EV_RAW
Ph_EV_SERVICE
Ph_EV_SYSTEM
Ph_EV_TIMER
Ph_EV_WM

These types are described below. The event type determines how the data associated with the event is interpreted.

subtype

Further information about the event. For the possible values of subtype, see the description of each event type.

processing_flags

Flags used or set in processing the event:

Ph_BACK_EVENT -- the event has gone down the widget family hierarchy and is now on its way back up.
Ph_CONSUMED -- the event has been consumed. (When a widget has processed an event and prevents another widget from interacting with the event, the first widget is said to have consumed the event.)
Ph_DIRECTED_FOCUS -- the event has caused focus to change.
Ph_FAKE_EVENT -- set this bit if the event is a fake one created by your application.
Ph_FOCUS_BRANCH -- focus is changing, and the current widget is on the focus path, but isn't the destination.
Ph_TYPE_SPECIFIC -- a mask for bits that are specific to the type of event.
Ph_USER_RSRVD_BITS -- a mask for bits that you can use for your own purposes.

emitter

A PhEventRegion_t structure identifying the region that emitted the event.

Your application can emit an event from a region -- even one it doesn't own -- by setting emitter to the ID of that region. You can use this approach when to target the device region by setting the Ph_EVENT_INCLUSIVE flag.

collector

A PhEventRegion_t structure identifying the region that collected the event. When your process has many regions open, collector lets you distinguish which of its regions was involved.

input_group

The number of the input group. A value of 0 means there's no input group.

flags

Event-modifier flags. You can OR the following values into flags:

Ph_EVENT_ABSOLUTE: Forces the rectangle set associated with the event to be relative to the root region's origin. By default, the coordinates of the rectangle set are relative to the origin of the emitting region.
Ph_EVENT_DIRECT: Emits the event directly from emitter to collector.
Ph_EVENT_INCLUSIVE: Emits the event first to the emitting region and then through the event space. Using this flag, an application can guarantee that the emitter sees the event (assuming the emitter is sensitive to that event type).
Ph_EMIT_TOWARD: Emits the event toward the user. By default, events are emitted away from the user.

timestamp

When the event was emitted, in milliseconds. The Photon Manager generates this member.

translation

A PhPoint_t structure that specifies the translation between the emitting region's origin and the collecting region's origin. An application uses this member to convert coordinates that are relative to the emitter's region to coordinates that are relative to the collector's region.

For example, let's say the graphics driver wants to render Ph_EV_DRAW events. When these events reach the driver, they contain coordinates relative to the region that emitted them. To render these events within its own region, the graphics driver uses translation to convert the coordinates.

num_rects

The number of rectangles associated with the event. To extract the list of rectangles, see PhGetRects().

data_len

The length of the data associated with the event. Since event data is optional, you can set data_len to 0 when there's no data. To extract the data from an event, see PhGetData().

Ph_EV_BOUNDARY

Emitted when the pointer crosses region boundaries. The subtype member of the PhEvent_t structure indicates one of the following boundary conditions:

Ph_EV_PTR_ENTER* Ph_EV_PTR_LEAVE*

Emitted when the region the cursor points at changes. Both the previous and current regions must have the Ph_FORCE_BOUNDARY flag set, since Photon only considers regions with this bit set to be pointed at by the cursor. The cursor will always point at something, since the root region has this bit set. When the region pointed to changes, any regions between the previous and new regions (that is, regions in the common ancestor tree) regardless of whether they have the Ph_FORCE_BOUNDARY flag set also receive boundary events. Since these events are emitted directly to the region, they are not affected by opacity to boundary events. The event subtypes are:

Ph_EV_PTR_ENTER_FROM_PARENT -- emitted to a child region when the pointer enters it from a parent region. Formerly Ph_EV_PTR_ENTER, which is deprecated.
Ph_EV_PTR_ENTER_FROM_CHILD -- emitted to a parent region when the pointer enters it from a child region.
Ph_EV_PTR_LEAVE_TO_PARENT -- emitted to a child region when the pointer leaves it to a parent region. Formerly Ph_EV_PTR_LEAVE, which is deprecated.
Ph_EV_PTR_LEAVE_TO_CHILD -- emitted to a parent region when the pointer leaves it to a parent region.

Ph_EV_PTR_STEADY

Emitted when the pointer remains motionless for 1.25 seconds. Another Ph_EV_PTR_STEADY won't be emitted until the user moves the pointer and then lets it remain motionless again. This event is propagated through the Photon space, starting from the device region, and therefore is affected by opacity to boundary events.

Ph_EV_PTR_UNSTEADY

Emitted when the pointer is moved after a Ph_EV_PTR_STEADY is emitted. Another Ph_EV_PTR_UNSTEADY won't be emitted until the user allows the pointer to remain motionless and then moves it again. This event is propagated through the Photon space, starting from the device region, and therefore is affected by opacity to boundary events.

Ph_EV_BUT_PRESS

Emitted when the user presses a button on a pointing device. This event's rectangle set consists of a point source that indicates the current pointer focus. The event data is a PhPointerEvent_t structure.

Ph_EV_BUT_RELEASE

Emitted when the user releases a pointing-device button. This event's rectangle set consists of a point source that indicates the current pointer focus. The event data is a PhPointerEvent_t structure. However, in this case, the buttons member indicates the buttons that were released.

This event type has the following subtypes:

Ph_EV_RELEASE_REAL: Emitted at the current position of the pointer (that is, where the user actually released the button).
Ph_EV_RELEASE_PHANTOM: Emitted where the user pressed the button.
Ph_EV_RELEASE_ENDCLICK: Emitted when multiclicks are no longer possible, i.e. when the user moves the mouse or stops clicking for a while.
Ph_EV_RELEASE_OUTBOUND: Emitted when the user starts dragging, i.e. when the mouse is moved a few pixels but the button hasn't been released.

Ph_EV_BUT_REPEAT

Emitted when the user presses an auto-repeating button on a pointing device. This event is emitted each time the button repeats. Its rectangle set consists of a point source that indicates where the button was pressed. The event data is a PhPointerEvent_t structure.

Ph_EV_DNDROP

These events are emitted during a drag-and-drop operation.

Ph_EV_DNDROP events with these subtypes are emitted to the source of the operation:

Ph_EV_DND_INIT: The operation has started successfully.
Ph_EV_DND_CANCEL: The operation was canceled (for example, if the drop occurred when not over a drop zone, or the destination terminated the operation before receiving the drop or before it finished fetching requestable data).
If the operation is canceled in this way, the library cleans up the data structures automatically.
Ph_EV_DND_COMPLETE: The drag-and-drop event is enqueued at the destination (the destination hasn't seen it yet).
Ph_EV_DND_DELIVERED: The destination has dequeued the drag-and-drop event.

These subtypes of a drag-and-drop event are emitted to the destination of the operation:

Ph_EV_DND_ENTER: The pointer has moved into the widget's region but no drop has occurred. This is the reason_subtype the first time that the drag-and-drop callback is called.
Ph_EV_DND_MOTION: The pointer is moving inside the widget's region. This type of event is emitted only if the Pt_DND_SELECT_MOTION bit is set in the select_flags member of the PtDndFetch_t structure for a piece of selected data.
Ph_EV_DND_REPEAT: This type of event is emitted periodically when Ph_EV_DND_MOTION events have been requested. The destination might want to track Ph_EV_DND_REPEAT events in, for example, a list widget, to select more than one item to be replaced by dropped data.
Ph_EV_DND_DROP: The user has dropped the data.
Ph_EV_DND_LEAVE: The pointer has moved out of the widget's region, but the user didn't drop the data.

Events with these subtypes are emitted internally to the Photon server to accept or deny a drop:

Ph_EV_DND_ACK
Ph_EV_DND_NAK

Ph_EV_DRAG

Used by an application to initiate drag events, to determine their completion, and to indicate intermediate drag-motion events.

The event data is a PhDragEvent_t structure.

The Ph_EV_DRAG event can have any of the following subtypes:

Ph_EV_DRAG_BOUNDARY: Emitted when rect hits a boundary. The flags member of the PhDragEvent_t structure specifies which boundary.
Ph_EV_DRAG_COMPLETE: When the user completes the drag operation, the device region emits a Ph_EV_DRAG event with this subtype toward the root region so that the initiating application collects the event. This event is direct.
Ph_EV_DRAG_INIT: To initiate a drag operation, an application must emit a Ph_EV_DRAG event with this subtype to the device region. The Photon Manager takes care of the user's interaction with the screen pointer and the drag outline.
The PhInitDrag() function, which emits Ph_EV_DRAG_INIT, provides a convenient way to initiate drag operations. You can cancel drag operations with PhCancelDrag()
Ph_EV_DRAG_KEY_EVENT: Emit the event with a PhKeyEvent_t structure.
Ph_EV_DRAG_MOTION_EVENT: Emit the event with a PhPointerEvent_t structure.
Ph_EV_DRAG_MOVE: Indicates intermediate drag motion. The Photon Manager emits this drag-event subtype if the Ph_DRAG_TRACK flag is set in the flags member of the PhDragEvent_t structure when the drag operation is initiated.
Ph_EV_DRAG_START: Emitted when the server begins the drag operation.

Ph_EV_DRAW

Emitted by the Pg functions when applications perform draw operations. The event travels toward the user and is collected by the graphics driver.

The event data is a PhDrawEvent_t structure that contains at least the following members:

unsigned short cmd_buffer_size: Size of the draw buffer, in bytes.
unsigned long id: An ID number that's unique for each application in this Photon space. The Pg functions set this number, which is used to optimize drawing operations.

Ph_EV_EXPOSE

Emitted by the Photon Manager on behalf of a region being moved, resized, or removed from the event space. The event travels away from the user and appears to originate from the removed region.

Since any regions now exposed see the expose event, an application can determine which of its regions have been uncovered. It can then redraw any portion of the regions that become visible by passing the rectangle set to PgSetClipping(). This event's rectangle set describes those areas that are now exposed. This event has no associated data.

The Ph_EV_EXPOSE event can have any of the following subtypes:

Ph_NORMAL_EXPOSE

Emitted when a region is moved, resized, or removed from the event space. This is the most common type of expose.

Ph_CAPTURE_EXPOSE

Emitted by an application (typically a printer driver) that wishes to receive an encapsulated draw event starting with:

            PgFFlush (Ph_START_DRAW);

and ending with:

            PgFFlush (Ph_DONE_DRAW);

when the applications that received the expose have completed their updates.

This type of event indicates that the expose wasn't caused by a region change. You can use this event type to collect data for the purpose of producing some form of hardcopy.

Ph_GRAPHIC_EXPOSE

Emitted by a graphics driver. This subtype indicates that no region was moved, removed, or resized to generate the expose event.

Ph_EV_INFO

All regions must always be transparent to Ph_EV_INFO events. They are emitted by applications or service providers to disseminate information or respond to requests. The currently defined subtypes are:

Ph_EV_INVALIDATE_SYSINFO

Emitted by Photon as regions are moved, created, or destroyed. The application must ask Photon for updated system information should a need for this information arise. This is handled automatically by the widget library. The event data is NULL.

Ph_EV_FEP

Emitted primarily by FEP service providers to inform applications of their presence or impending absence. The data portion of the event is a PhFEPInfo_t structure that contains at least the following members:

long type

The valid types are:

Ph_FEP_REGISTER -- a FEP has been launched (all applications can see the event), or is responding to a Ph_FEP_BROADCAST service message (seen only by the application requesting the broadcast).
Ph_FEP_DEREGISTER -- a FEP is shutting down.

long subtype

The language type of the FEP. The valid subtypes are:

Ph_FEP_JAPANESE
Ph_FEP_CHINESE
Ph_FEP_KOREAN

long len

Not currently used.

char data[1]

Not currently used.

Ph_OFFSCREEN_INVALID

Emitted when when an offscreen context is invalidated by the graphics driver for any reason. Applications planning on using offscreen contexts should be sensitive to this event and reinitialize their off screen contexts accordingly. The data portion of this event is a single long describing why the offscreen areas have been invalidated. The defined types are:

Pg_VIDEO_MODE_SWITCHED: The graphics driver has changed video modes.
Pg_ENTERED_DIRECT: An application has entered direct mode.
Pg_EXITED_DIRECT: An application has left direct mode.
Pg_DRIVER_STARTED: The video driver has just started execution.

Ph_EV_KEY

Emitted when a key state changes (for example, the user presses or releases a key). This event's rectangle set consists of a point source that indicates the current focus. The event data is a PhKeyEvent_t structure.

The processing_flags member of the PhEvent_t structure for this event type also include:

Ph_NOT_CUAKEY: Force PtContainer not to use the key for traversal (CUA).
Ph_NOT_HOTKEY: Force PtContainer not to treat the key as a hotkey.

Ph_EV_PTR_MOTION_BUTTON

Emitted when the user moves the pointing device while pressing a button. This event's rectangle set consists of a point source that indicates the current pointer focus. The event data is a PhPointerEvent_t structure. The buttons member indicates which buttons the user is pressing.

Ph_EV_PTR_MOTION_NOBUTTON

Emitted when the user moves the pointing device without pressing a button. This event's rectangle set consists of a point source that indicates the current pointer focus. The event data is a PhPointerEvent_t structure.

Large numbers of Ph_EV_PTR_MOTION_NOBUTTON events can slow down your system. To avoid this, you should make your applications sensitive to Ph_EV_PTR_MOTION_BUTTON whenever possible, rather than to Ph_EV_PTR_MOTION_NOBUTTON.

Ph_EV_RAW

These are raw, unfocused events that the Photon server handles.

Ph_EV_SERVICE

These events may be emitted by applications requesting services or providing information to services, other applications that provide some kind of service in a Photon system. The currently defined subtypes are:

Ph_EV_REMOTE_WM

Handled by relay-type services such as phrelay (see the QNX Neutrino Utilities Reference). Normally only emitted by a Window Manager to synchronize a remote Window Manager's state. The event data is a PhRemoteWMEvent_t structure that contains at least the following members:

short type: Valid values of type are REMOTE_WM_WINDOW or REMOTE_WM_TITLE.
short len: Not used.

If type is REMOTE_WM_WINDOW, the window member is also defined. The window member has at least the following members:

ushort_t xpos

New absolute x coordinate of the window.

ushort_t ypos

New absolute y coordinate of the window.

ushort_t height

New height dimension of the window.

ushort_t width

New width dimension of the window.

short flags

Valid flag bits are:

REMOTE_FLAG_FIXED: Window shouldn't be resized by the Window Manager; the application resizes it.
REMOTE_FLAG_INITIAL: New window.
REMOTE_FLAG_IS_ORIGIN: Use xpos, ypos as the new origin.
REMOTE_FLAG_NO_DIM: The dim variable shouldn't be modified.

If type is REMOTE_WM_TITLE, the title member is defined as follows:

char title[64]: A title for the window.

Ph_EV_FEP

Handled by Front End Processor (FEP) service providers (e.g. Japanese input). The event data is a PhFEPService_t structure that contains at least the following members:

long type

The valid types are:

Ph_FEP_BROADCAST: Request a broadcast from FEP service. If a FEP is present, it responds with an Ph_FEP_REGISTER register event.
Ph_FEP_RECT: Give rectangle (for pre-edit window and cursor) to FEP services. The pre-edit rectangle is defined by the event rectangle. The cursor rectangle is defined by this structure's rectangle member.
Ph_FEP_NORECT: Invalidate rectangle in FEP service.
Ph_FEP_ACTIVATE: Request activation of FEP filter.
Ph_FEP_DEACTIVATE: Request deactivation of FEP filter.

long len

Not used.

PhRect_t rect

The cursor rectangle relative to the event rectangle.

long num_rids

The number of regions that are parents of this region (the region owned by the currently focused widget). An array of num_rids RIDs should be appended to the event data. The first RID in this list should be the RID of the focused widget; otherwise num_rids should be set to 0.

Ph_EV_SYSTEM

Ph_EV_SYSTEM events are emitted when Photon or a service wants to inform applications of changes in the system. The event data is a PhSystemEvent_t union. The valid member is dictated by the subtype of the system event.

If the event subtype is Ph_SYSTEM_REGION_CHANGE, the valid union member is RegionChange, which contains at least the following members:

PhRid_t rid

ID of the region that changed.

PhPoint_t origin

A PhPoint_t structure that specifies the origin of the region, relative to its parent's region.

PhRect_t rect

Its rectangle, relative to its origin.

ulong_t flags

The region's flags.

ulong_t fields

A set of bits indicating which fields of the PhRegion_t structure were modified:

0xFFFFFFFF -- the region was opened.
0x00000000 -- the region was closed.
Other values -- fields with a 1 bit were changed.

For more information, see:

unsigned short input_group

Nonzero if the region being changed belongs to an input group.

Ph_EV_TIMER

Emitted by an application directly to the Device region to request a reciprocal event after a specific amount of time has elapsed (arm a timer). This is usually done via PtTimerArm() or PhTimerArm().

It is also emitted by Photon when an armed timer expires. In both cases, the event data is a PhTimerEvent_t structure that contains the following members:

unsigned msec
unsigned zero
PhEventRegion_t region

region.rid is the RID, and region.handle is a pointer to the widget specified as the handle in a PtTimerArm() call.

When this event is received by the widget library, it delivers the event directly to the widget designated by region.handle. It's best to avoid setting region.handle to anything other than a valid widget pointer.

Ph_EV_WM

Both the Window Manager and applications can emit this event. The Window Manager emits this event when an application has asked to be notified. An application can emit this event to communicate to the Window Manager regarding windows.

Ph_EV_WM can have the following subtype:

Ph_EV_WM_EVENT: The rectangle set of the event has no useful value. The event data is a PhWindowEvent_t structure.

Classification:

Photon