Caution: 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:

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


Note: 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:

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

See also:

PhCancelDrag(), PhDragEvent_t, PhEventRegion_t, PhGetData(), PhGetRects(), PhInitDrag(), PhKeyEvent_t, PhPoint_t, PhPointerEvent_t, PhRect_t, PhWindowEvent_t, PtDndFetch_t

Events chapter of the Photon Programmer's Guide