PhQueryRids()

Get a list of regions

Synopsis:

int PhQueryRids( unsigned flags,
                 PhRid_t rid,
                 unsigned input_group,
                 unsigned type,
                 unsigned sense,
                 PhRid_t emitter,
                 const PhRect_t *rect,
                 PhRid_t rids[],
                 int num );

Description:

This function builds a list of up to num regions in the rids array. The other parameters specify which regions are to be included in the list:

flags

The possible flag bits are:

• Ph_RIDQUERY_IG_POINTER - use input_group's pointer position as rect.
• Ph_RIDQUERY_TOWARD - act as if the event were emitted towards the user (away from the root region).

rid

Consider regions that intersect with the region with this ID. Set rid to 0 to consider all regions.

input_group

Consider regions that belong to this input group (0 means any). You can determine the current input group as follows:

• If you have the event that triggered the clipboard operation, use its input group (e.g. cbinfo->event->input_group) if it's nonzero.
• If that fails, get the value of the PHIG environment variable. If this value is nonzero, use it.
• If neither of the above if nonzero, specify an input group of 1.

type

Consider regions of these types:

• Ph_WINDOW_REGION
• Ph_WND_MGR_REGION
• Ph_GRAFX_REGION
• Ph_PTR_REGION
• Ph_KBD_REGION
• Ph_PRINT_REGION
• Ph_INPUTGROUP_REGION
• Ph_AUXPTR_REGION
• Ph_FORCE_FRONT
• Ph_FORCE_BOUNDARY

Set type to 0 (i.e. all bits off) to consider all types of regions.

sense

Consider regions that are sensitive or opaque to these event types. The possible bits are:

• Ph_EV_KEY
• Ph_EV_BUT_PRESS
• Ph_EV_BUT_RELEASE
• Ph_EV_PTR_MOTION_NOBUTTON
• Ph_EV_PTR_MOTION_BUTTON
• Ph_EV_BOUNDARY
• Ph_EV_EXPOSE
• Ph_EV_DRAW
• Ph_EV_AMIN
• Ph_EV_DRAG
• Ph_EV_COVERED
• Ph_EV_BLIT
• Ph_EV_SYSTEM
• Ph_EV_WM
• Ph_EV_BUT_REPEAT
• Ph_EV_RAW
• Ph_EV_TIMER
• Ph_EV_LB_SYSTEM
• Ph_EV_SERVICE
• Ph_EV_INFO

Set sense to 0 (i.e. all bits off) to consider regions regardless of their sensitivity.

emitter

The region to begin the query from.

rect

A pointer to a structure that specifies the area (relative to emitter's origin) that other regions must intersect to be considered in the query. This can be NULL.

Returns:

The number of regions found, or -1 if an error occurred.

If this function returns -1, check errno. If it's ENOMSG, there are no pending Photon events; this isn't really an error.

Classification:

Photon