`PhRegion_t`

Data structure that describes a region

Synopsis:

typedef struct Ph_region {
    PhRid_t             rid;
    long                handle;
    PhConnectId_t       owner;
    ulong_t             flags;
    ushort_t            state;
    unsigned long       events_sense;
    unsigned long       events_opaque;
    PhPoint_t           origin;
    PhRid_t             parent,
                        child,
                        bro_in_front,
                        bro_behind;
    PgColor_t           cursor_color;
    ushort_t            input_group;
    ushort_t            data_len;
    unsigned long       zero[2];
    ushort_t            cursor_type;
} PhRegion_t;

Description:

The PhRegion_t structure describes a region. It contains at least the following members:

PgColor_t cursor_color

The cursor color for this region.

unsigned short cursor_type

Sets the cursor type for this region. See <PhCursor.h>. A cursor_type of Ph_CURSOR_INHERIT indicates this region inherits the cursor from the parent region.

If you OR cursor_type with Ph_CURSOR_NO_INHERIT, then children of this region won't inherit its cursor type. The children inherit the cursor from their first ancestor that doesn't have the Ph_CURSOR_NO_INHERIT flag set.

PhRid_t rid

This region's ID. The Photon Manager assigns this when the region is opened.

long handle

A user-definable handle that is included as part of the event structure. Applications can use handle to quickly pass a small amount of information along with events. For example, the widget toolkit functions (Pt*()) use handle to point to a widget in memory so that they can quickly find the appropriate callback.

PhConnectId_t owner

Indicates the owner of this region. See PhGetConnectInfo().

unsigned long flags

Controls certain aspects of this region and also indicates the region's type. Of the following flags, Ph_FORCE_BOUNDARY and Ph_FORCE_FRONT affect how the region behaves. The others simply indicate the region type.

These type flags are set by the API functions for the convenience of applications that wish to identify a region's purpose. For example, an application can use these flags when querying the Photon Manager for a list of regions that have a specific type.

You can OR the following into flags:

Ph_FORCE_BOUNDARY: Forces the Photon Manager to emit Ph_EV_BOUNDARY events to this region. If you don't set this flag, the Photon Manager determines if the region should get boundary events by verifying that the region is opaque or sensitive to Ph_EV_EXPOSE events.
Ph_FORCE_FRONT: Forces the Photon Manager to place this region in front of any of its brothers that don't have this flag set, and behind any brothers that do have this flag set.
Ph_GRAFX_REGION: Indicates that this region belongs to a graphics driver.
Ph_INPUTGROUP_REGION: Indicates that this region is an input group.
Ph_KBD_REGION: Indicates that this region belongs to an input/keyboard driver.
Ph_PTR_REGION: Indicates that this region belongs to an pointer/mouse driver.
Ph_WINDOW_REGION: Indicates that this region is a window.
Ph_WND_MGR_REGION: Indicates that the Window Manager owns this region.

unsigned long events_sense

Determines which event types this region is sensitive to. If an event is one of these types and it passes through the region, the event is enqueued to the application.

unsigned long events_opaque

Determines which event types this region is opaque to. If an event is one of these types and it passes through the region, any portion of the event that intersects with the region is clipped out.

PhPoint_t origin

Determines the region's origin relative to its parent's origin. All coordinates returned in events and elsewhere in this structure are relative to origin.

In almost all cases, the coordinates used by the API functions are relative to the origin of the caller's region. However, when emitting events, the application may use absolute coordinates by setting the Ph_EVENT_ABSOLUTE flag.

PhRid_t parent

Indicates the region's parent.

PhRid_t child

Indicates the frontmost child region (that is, closest to the user). If no child regions exist, the Photon Manager sets child to -1.

PhRid_t bro_in_front

Indicates the brother region that's located immediately in front. If there's no brother in front, the Photon Manager sets bro_in_front to -1.

PhRid_t bro_behind

Indicates the brother region that's located immediately behind. If there's no brother behind, the Photon Manager sets bro_behind to -1.

unsigned short data_len

The length of the data portion of this region. The data is stored in a single block of memory; to get a copy of it, call PhRegionQuery().

The region data may consist of blocks of data of different types, each preceded by a PhRegionDataHdr_t structure. There's at most one block of a given type. To find a specific type of data in the region's data, call PhRegionDataFindType().

If you need to change the region data, modify your copy or create a new block (starting with a PhRegionDataHdr_t structure) and pass it to PhRegionChange().

unsigned short input_group

Indicates the number of the input group. A value of 0 means this region isn't an input group.

Classification:

Photon

PhRegion_t

Synopsis:

Description:

Classification:

See also:

`PhRegion_t`