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:
- 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.
Photon
PgColor_t,
PgGetRegion(),
PgSetRegion(),
PhPoint_t,
PhRegionChange(),
PhRegionClose(),
PhRegionDataFindType(),
PhRegionDataHdr_t,
PhRegionInfo()
PhRegionOpen(),
PhRegionQuery()
Regions chapter of the
Photon Programmer's Guide
![[Previous]](../prev.gif)
![[Contents]](../contents.gif)
![[Index]](../keyword_index.gif)
![[Next]](../next.gif)
