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_USER
• 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.

These flags are ignored when you emit an event, and always zero in a received 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.

The emitter.handle member is ignored, you can set it to zero.

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.

Note that for collector.rid:

• If the emitting application sets it to a non-zero rid, the event will not be delivered to any region other than this rid. Unless the DIRECT flag is set, the event still travels through the Photon space and gets clipped by opaque regions, but is not enqueued to any sensitive region other than the specified one.
• In a received event, this is the region that the event was delivered to.

Note that for collector.handle:

• Is ignored when you emit an event.
• In a received event, this is the “handle” taken from the collector region's PhRegion_t. Forced to zero if the region's owner was changed while the event was in the queue (which doesn't normally happen).

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.

If the Ph_EVENT_ABSOLUTE flag is set, the translation provided by the emitting application is ignored. In a received absolute event, the translation is what the rectangles have been translated by — the negative of the collecting region's origin (Photon has subtracted the region's origin from absolute co-ordinates to compute co-ordinates relative to the region's origin). Subttacting the translation from the rectangles reproduces the absolute co-ordinates that the emitting application gave to Photon.

When Ph_EVENT_ABSOLUTE flag is not set, the translation provided by the emitting application is added to the translation between the two regions. When you emit an event, Photon computes absolute co-ordinates by adding the position of your region to the numbers in your rectangle list. When the event is delivered to another region, the absolute rectangles are translated to the region's co-ordinates by subtracting the region's origin, but the translation is set to the emitter's origin, minus the collector's origin, plus the translation provided by the emitter.

num_rects

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

The number of rectangles can generally be different when you emit and when you receive the event.

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:

unsigned short xpos

New absolute x coordinate of the window.

unsigned short ypos

New absolute y coordinate of the window.

unsigned short height

New height dimension of the window.

unsigned short 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.

unsigned long flags

The region's flags.

unsigned long 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:

• PhRegion_t
• PhRegionOpen()
• PhRegionChange()
• <PhT.h>

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_USER

A custom event type that your application can use to interact with other applications.

If you can't rule out the possibility that your code might need to co-exist with code written independently by other vendors, you need to make sure that you never send a Ph_EV_USER event to any region that you don't own.

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