Developer

API Reference

IGridContainer_GetWidget()

Brew Release
Brew MP 1.0.2
See Also
- IGridContainer Interface
- IWidget Interface
Description
This function provides facilities that allow an application to retrieve the widgets stored in a grid 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 grid container by repeatedly calling IGridContainer_GetWidget() and passing in the widget pointer returned from the previous call.
Parameters
  • p
    []:
    A pointer to an IGridContainer object.
  • pw
    []:
    Identifies the widget within the grid 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
  • d
    []:
    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 'pw' parameter. When 'd' is TRUE the function will retrieve the next widget on the stack (i.e. the widget closer to the top of the stack). When 'd' 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 'pw' is passed as NULL, the 'd' parameter explicitly indicates either the topmost or bottommost widget, as described above.
  • w
    []:
    Specifies whether or not the function should wrap when attempting to retrieve the next or previous widget from the top or bottom of the grid container's widget stack. When 'w' 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 *IGridContainer_GetWidget(IGridContainer *p, IWidget *pw, boolean d, boolean w);
Return
A pointer to a widget in the grid container's widget stack, or NULL when there is no widget to be returned.
Side Effect
None
Comment
Though the IGridContainer_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 = IGridContainer_GetWidget (pGridContainer, pWidget, TRUE, FALSE)) {
          //
          // Do fancy stuff with the widget pointer returned in pWidget
          //
       }
       // Drops out of the loop once IGridContainer_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 = IGridContainer_GetWidget (pGridContainer, pWidget, FALSE, FALSE)) {
          //
          // Do fancy stuff with the widget pointer returned in pWidget
          //
       }
       // Drops out of the loop once IGridContainer_GetWidget() returns NULL

  • Follow