PhRegionQuery()

Retrieve information about a region

Synopsis:

int PhRegionQuery( PhRid_t rid,
                   PhRegion_t *region,
                   PhRect_t *rect,
                   void *data,
                   unsigned data_len );

Library:

ph

Description:

This function returns information about the region identified by rid. On completion, the PhRegion_t structure pointed to by region and the PhRect_t structure pointed to by rect contain a description of the region.

If the region has data attached to it, then the data, up to data_len bytes, is copied into data. This data may consist of smaller blocks of data of different types, each preceded by a PhRegionDataHdr_t structure. To find a specific type of data in the region's data, call PhRegionDataFindType().

---

This function is similar to PhRegionInfo(), but it doesn't support multiple rectangles. In a future release, it may be possible to create regions with multiple rectangles. If you want your code to be prepared to handle such regions correctly, you should consider using PhRegionInfo() instead of PhRegionQuery(). When multiple rectangles are supported, this function will return just the bounding box of the region rather than an acurate shape.

---

Returns:

0

Success.

-1

An error occurred.

Examples:

The following example gets information about the device region:

PhRegion_t region; PhRect_t rect;

if( !PhRegionQuery( Ph_DEV_RID, &region,
                    &rect, NULL, 0 ) ) {
  printf( "Sensitive to: %.8x Opaque to: %.8x\n",
    region.events_sense, region.events_opaque );
  printf( "Located at: {(%d,%d),(%d,%d)}\n",
     region.origin.x + rect.ul.x,
     region.origin.y + rect.ul.y,
     region.origin.x + rect.lr.x,
     region.origin.y + rect.lr.y );
}

Classification:

Photon

See also:

PhRect_t, PhRegion_t, PhRegionChange(), PhRegionInfo() PhRegionOpen()

Regions chapter of the Photon Programmer's Guide