- pif:[in] Pointer to the IRootContainer interface object that serves as the parent to the widget to locate.
- pw:[in] Pointer to the IWidget object to be located.
- ppRoot:[in/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 layout position of the object relative to the root container. Therefore, the function 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.
int IRootContainer_Locate(IRootContainer *pif, IWidget *pw, IContainer **ppr, AEERect *prc);
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.
Since the root container is the container making the location request the pointer returned in 'ppRoot' will be the same pointer passed into the function in the 'pif' parameter.
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.