Caution: This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

PtFindSurfaceByAction()

Find the control surface associated with a given action

Synopsis:

PtSurface_t *PtFindSurfaceByAction( 
                 PtWidget_t *widget,
                 PtWidgetClassRef_t const *cref,
                 unsigned short action_id,
                 PtSurface_t const *surface );

Library:

ph

Description:

This function locates a control surface using its associated action as a search key.

The widget argument specifies the widget to search, while cref and action_id specify the class and manifest of the action to seek. The surface argument specifies the surface at which to start the search, letting you find all the surfaces in a widget associated with a particular action. If this argument is NULL, the search begins at the first surface within the widget.


Note: This function ignores regular surfaces (i.e. those created using PtCreateSurface() as opposed to PtCreateActionSurface()).

Returns:

A pointer to the structure representing the control surface, or NULL if no more surfaces associated with the specified action could be found.


Note: Since control surfaces are maintained internally as an array, it's not uncommon for them to shift around in memory as surfaces are added and removed, thereby possibly invalidating a pointer returned by this function. As such, all surface pointers should be regarded as transient, and you should retrieve an updated copy whenever there's a chance that the widget's surface configuration might have changed.

Classification:

Photon

Safety:
Interrupt handler No
Signal handler No
Thread No

See also:

PtFindSurface(), PtWidgetActiveSurface()

Control Surfaces chapter of the Photon Programmer's Guide