---

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_COVERED
• 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_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_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

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

collector

Which region collected the event. When a process has many regions open, collector lets the process 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

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

Emitted when the pointer enters a region. By default, enter events are emitted to the frontmost region that's under the pointer, but only if that region is opaque or sensitive to Ph_EV_EXPOSE events.

An application can still force the Photon Manager to emit boundary events to the frontmost region under the pointer even if that region isn't sensitive or opaque to Ph_EV_EXPOSE. To do so, the application sets the region's Ph_FORCE_BOUNDARY flag (see the description of PhRegion_t).

---

Before entering a region, the pointer usually first enters the ancestors of that region. But with some pointing devices (for example, touchscreens), the pointer may bypass the ancestors and enter the region directly. If this happens, the Photon Manager emits an enter event to the region as well as to its ancestors.

---

Ph_EV_PTR_LEAVE

Emitted when the pointer leaves a region. A leave condition occurs only when the pointer enters a region that's not a child of the previously entered region. (Child regions are always located within the bounds of their parents. Thus, the pointer doesn't have to leave a parent to enter its child.)

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.

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.

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 that contains at least the following members:

PhPoint_t pos

Indicates the untranslated, absolute position of the current pointer focus. As a rule, you should use the event's rectangle set to determine coordinate positions. However, for situations that demand absolute coordinates (for example, calibrating a touchscreen), you can use pos.

unsigned char click_count

Indicates the number of clicks (for example, a value of 2 indicates a double-click). See the Ph_EV_RELEASE_ENDCLICK subtype for Ph_EV_BUT_RELEASE.

short z

Can be used with touchscreens to indicate touch pressure.

unsigned char flags

Indicates that the z field is valid.

unsigned short button_state

Indicates the current state of the buttons.

unsigned short buttons

Indicates which buttons the user pressed. For your convenience, we've defined the following manifests:

• Ph_BUTTON_SELECT-normally the left button. Because a pointing device might provide only this button, you should design most applications such that the user has the option to use this button to perform any task.
• Ph_BUTTON_MENU-can be used to invoke menus when they're available.
• Ph_BUTTON_ADJUST-use is currently unspecified.

unsigned long key_mods

The modifier keys that are currently pressed. See PhKeyEvent_t.

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 (see Ph_EV_BUT_PRESS). 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_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 (see Ph_EV_BUT_PRESS).

Ph_EV_COVERED

(Not yet implemented) Emitted by the Photon Manager when a region is created. The event travels away from the user and appears to originate from the newly created region.

Since any regions now covered by the new region see the covered event, an application can use this event to determine if its regions are partially covered. With this information, the application can then take appropriate action. For example, an animation program that consumes many processor cycles might choose to cease animation when covered, then resume animation when exposed again.

This event's rectangle set describes only those areas that have become covered. This event has no associated data.

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 that contains at least the following members:

PhRid_t rid

Indicates the region that initiated the drag operation. The application needs to set rid when the drag is initiated.

unsigned short flags

Indicates which edges of the drag rectangle track the pointer. You can OR the following values into flags:

• Ph_DRAG_NOBUTTON-Allow the drag to start even if the user isn't holding down a button.
• Ph_DRAG_KEY_MOTION-During the drag, emit drag events with the Ph_EV_DRAG_KEY_EVENT or the Ph_EV_DRAG_MOTION_EVENT subtype (these subtypes are described below).
• Ph_DRAG_TRACK-No drag outline is drawn, and Ph_EV_DRAG_MOVE events are emitted to the initiating region. This flag is used by applications that wish to implement their own visual interpretation of drag operations.
• Ph_TRACK_LEFT-left edge tracks the pointer.
• Ph_TRACK_RIGHT-right edge tracks the pointer.
• Ph_TRACK_TOP-top edge tracks the pointer.
• Ph_TRACK_BOTTOM-bottom edge tracks the pointer.
• Ph_TRACK_DRAG-all edges track the pointer (same as using all four of the above values).

PhRect_t rect

Contains the coordinates of the initial, current, or final drag rectangle, depending on the drag-event subtype value.

PhRect_t boundary

Contains the coordinates of the rectangle that constrains the drag operation.

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.

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 was set in the flag member of the PhDragEvent_t structure when the drag operation was 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_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 (see Ph_EV_BUT_PRESS). 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 (see Ph_EV_BUT_PRESS).

---

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

Origin of the region, relative to its parent rid.

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:

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

PhGetData(), PhGetRects(), PhKeyEvent_t, PhWindowEvent_t

Events chapter of the Photon Programmer's Guide

---