Developer

API Reference

IXYContainer_GetWidget()

Brew Release
Brew MP 1.0.2
See Also
- IXYContainer Interface
- IWidget Interface
- IXYContainer_GetLastWidget()
- IXYContainer_GetFirstWidget()
Description
This function provides facilities that allow an application to retrieve the widgets stored in an XY 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 XY container by repeatedly calling IXYContainer_GetWidget() and passing in the widget pointer returned from the previous call.
Parameters
  • pif
    []:
    [in] A pointer to an IXYContainer object.
  • pwRef
    []:
    [in] Identifies the widget within the XY container's widget stack that will serve as a reference point for the widget to be retrieved. This widget 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 XY 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, IXYContainer_GetWidget() 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 XY 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.

Interface
Prototype
   IWidget *IXYContainer_GetWidget(IXYContainer *pif,
                                    IWidget *pwRef,
                                    boolean bNext,
                                    boolean bWrap);
Return
A pointer to a widget in the XY container's widget stack, or NULL when there is no widget to be returned.
Side Effect
None
Comment
Though IXYContainer_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 entire widget stack -- from bottom to top -- with the following code:
   
       IWidget *pWidget = NULL;
       
       while (pWidget = IXYContainer_GetWidget (pXYContainer, pWidget, TRUE, FALSE)) {
          //
          // Do fancy stuff with the widget pointer returned in pWidget
          //
       }
       // Drops out of the loop once IXYContainer_GetWidget() returns NULL


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

  • Follow