Developer

API Reference

IRootContainer_GetWidget()

Brew Release
Brew MP 1.0.2
See Also
- IRootContainer Interface
- IWidget Interface
Description
This function provides facilities that allow an application to retrieve the widgets stored in the root container's widget stack. The function may be instructed to return the widget from an explicit location, such as the top or bottom of the stack, or from some position relative to another widget in the widget stack -- for example, returning the widget that appears before or after another widget in the stack. An application can easily iterate over all of the widgets in the root container by repeated calls to IRootContainer_GetWidget(), passing in the widget pointer returned from the previous call.
Parameters
  • pif
    []:
    [in] A pointer to an IRootContainer object.
  • pwRef
    []:
    [in] Identifies the widget within the root container's widget stack that will serve as a reference point for the widget to be retrieved. 'pwRef' may be expressed explicitly as a widget pointer, or implicitly as a constant that identifies a relative position within the widget stack, as follows WIDGET_ZNORMAL - Use the widget at the root container's default location as the retrieval reference point. BREW interprets this to be the widget at the top of the widget stack. WIDGET_ZTOPMOST - Use the widget at the top of the widget stack as the retrieval reference point. WIDGET_ZBOTTOMMOST - Use the widget at the bottom of the widget stack as the retrieval reference point. When 'pwRef' is NULL, the function will return either the top or bottom widget on the stack, depending on the value of 'bNext'. When 'pwRef' is NULL and 'bNext' is TRUE, the function will return the bottommost widget. When 'pwRef' is NULL and 'bNext' is FALSE, the function will return the topmost widget.
  • bNext
    []:
    [in] Specifies whether the function should retrieve the next widget in the widget stack, or the previous widget on the stack -- always relative to the reference widget determined by the value passed in the 'pwRef' parameter. When 'bNext' is TRUE the function will retrieve the next widget on the stack (i.e., the widget closer to the top of the stack). When 'bNext' is FALSE the function will retrieve the previous widget on the stack (i.e., the widget closer to the bottom of the stack). Note, however, that when 'pwRef' is passed as NULL, the 'bNext' parameter explicitly indicates either the topmost or bottommost widget, as described above.
  • bWrap
    []:
    [in] Specifies whether or not the function should wrap when attempting to retrieve the next or previous widget from the top or bottom of the root container's widget stack. When 'bWrap'is TRUE, the function will wrap at either end of the stack, otherwise the function will return NULL indicating that there are no more widgets to be retrieved.

Prototype
   IWidget *IRootContainer_GetWidget(IRootContainer *pif,
                                       IWidget *pwRef,
                                       boolean bNext,
                                       boolean bWrap);
Return
A pointer to a widget in the root container's widget stack, or NULL when there is no widget to be returned.
Side Effect
None
Comment
Though IRootContainer_GetWidget() function returns a pointer to a widget, the function does not add a reference to the returned IWidget for the caller.
An application may iterate over the root container's entire widget stack -- from bottom to top -- with the following code:
   
       IWidget *pWidget = NULL;
       
       while (pWidget = IRootContainer_GetWidget (pRootContainer, pWidget, TRUE, FALSE)) {
          //
          // Do fancy stuff with the widget pointer returned in pWidget
          //
       }
       // Drops out of the loop once IRootContainer_GetWidget() returns NULL


To iterate over all the widgets on the root container's widget stack from top to bottom, the application's code would look like the following:
   
       IWidget *pWidget = NULL;
       
       while (pWidget = IRootContainer_GetWidget (pRootContainer, pWidget, FALSE, FALSE)) {
          //
          // Do fancy stuff with the widget pointer returned in pWidget
          //
       }
       // Drops out of the loop once IRootContainer_GetWidget() returns NULL

  • Follow