PhRegion_t

Data structure that describes a region

Synopsis:

See below.

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

Determines whether the cursor points at this region. Photon considers the cursor to point at the foremost region with this bit set. This affects the cursor color and type, and whether the region causes some types of Ph_EV_BOUNDARY 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

A PhPoint_t structure that 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.

unsigned short num_rects

Indicates the number of rectangles the region has. Currently, always set to 1.

Classification:

Photon

See also:

PgColor_t, PgGetRegion(), PgSetRegion(), PhPoint_t, PhRegionChange(), PhRegionClose(), PhRegionDataFindType(), PhRegionDataHdr_t, PhRegionInfo() PhRegionOpen(), PhRegionQuery()

Regions chapter of the Photon Programmer's Guide