Caution: This version of this document is no longer maintained. For the latest documentation, see


Data structure that describes a region


See below.


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:

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.
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.
Indicates that this region belongs to a graphics driver.
Indicates that this region is an input group.
Indicates that this region belongs to an input/keyboard driver.
Indicates that this region belongs to an pointer/mouse driver.
Indicates that this region is a window.
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.



See also:

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

Regions chapter of the Photon Programmer's Guide