Developer

API Reference

IContainer_Locate()

Brew Release
Brew MP 1.0.2
See Also
- IContainer Interface
- IWidget Interface
Description
This function will find the location of a particular widget, returning that widget's rectangle relative to the widget's root container. The function will also, optionally, return a pointer to the root container.
Parameters
  • pif
    []:
    [in] Pointer to the IContainer interface object that serves as the parent to the widget to locate.
  • pw
    []:
    [in] Pointer to the IWidget object to be located, or a constant that implies a particular widget within the container. The constants used to identify a relative position for the widget to be located, are defined as follows WIDGET_ZTOPMOST - Locate the widget at the top of the container's widget stack. WIDGET_ZBOTTOMMOST - Locate the widget at the bottom of the container's widget stack. WIDGET_ZNORMAL - Locate the widget placed at the container's most normal layout location. The base container treats the WIDGET_ZTOPMOST position as the "normal" location.
  • ppRoot
    []:
    [out] Pointer to an IContainer pointer, into which the function will return a pointer to the container's root container. This parameter may be specified as NULL if the caller does not wish to get the root container.
  • prcRelative
    []:
    [in/out] Pointer to an AEERect. On input, this rectangle will specify the current relative offset of the 'pw' object relative to its child. On output, this rectangle specifies the position of the object relative to the root container. Therefore, IContainer_Locate() should initially be called by passing in a rectangle with origin at (0, 0) -- otherwise, the returned rectangle will be expressed relative to the initial offset.
Interface
Prototype
   int IContainer_Locate(
      IContainer* pif,
      IWidget* pw,
      IContainer** ppRoot,
      AEERect* prcRelative);
Return
   AEE_SUCCESS - If the widget 'pw' was found and the information requested was successfully returned
   AEE_EFAILED - If the widget 'pw' was not found in the container.

The rectangle occupied by the widget is returned in 'prcRelative'.
A pointer to the widget's root container will be returned in 'ppRoot', which will increment the reference count of the root container.
Side Effect
None
Comment
The rectangle referenced by 'prcRelative' MUST be initialized prior to calling IContainer_Locate(), otherwise the results will be undefined.
The pointer passed in the 'ppRoot' parameter is a double-indirection -- i.e., it is a pointer to a pointer. Applications should use care in ensuring that the proper level of indirection is used in calling the function.
  • Follow