Developer

API Reference

IPropContainer_Insert()

Brew Release
Brew MP 1.0.2
See Also
- IPropContainer
- IWidget
- WidgetProp
- IPropContainer_Remove
Description
This function allows an application to insert a widget into the prop container's widget stack -- at the top of the stack, at the bottom, or someplace in between. By default, widgets will be created in the order that they will be laid out within the container (left to right, or top to bottom). However, a widget may be inserted anywhere in the widget stack depending on the needs of the application and container. An example would be an application that breeds widgets. Imagine an application that looks like the following:
   
       +-----------------------------------+
       |           Widget Breeder          |
       +-----------------------------------+
       |                                   |
       |                                   |
       |                                   |
       |                                   |
       |                                   |
       |                                   |
       |                                   |
       |                                   |
       |                                   |
       |                                   |
       |                                   |
       |                                   |
       +-----------------------------------+
       |   Press any key to breed widgets  |
       +-----------------------------------+

This prop container is initially laid out vertically with the following three widgets:
   
       1. Static widget with 'prop' = WIDGET_KEEP_EXTENT
       2. Dummy widget with 'prop' = 1
       3. Static widget with 'prop' = WIDGET_KEEP_EXTENT

The net result is the screen above -- two WIDGET_KEEP_EXTENT sized widgets with a variable sized widget in between that will occupy all the space not required by the WIDGET_KEEP_EXTENT widgets.
When the user presses a key, a new widget will be created and inserted into the widget stack before widget 3 (we'd also likely call IPropContainer_Remove() to get rid of the dummy widget we'd no longer need). With each subsequent key press, additional widgets would be inserted, all prior to the static widget located at the bottom of the screen, like so:
   
                                                             Following
                    Initial State                      several key presses
       +-----------------------------------+   +-----------------------------------+
       |           Widget Breeder          |   |           Widget Breeder          |
       +-----------------------------------+   +-----------------------------------+
       |                                   |   |+---------------------------------+|
       |                                   |   ||                                 ||
       |                                   |   ||  A baby widget has been born!   ||
       |                                   |   ||                                 ||
       |                                   |   |+---------------------------------+|
       |                                   |   ||                                 ||
       |                                   |   ||  A baby widget has been born!   ||
       |                                   |   ||                                 ||
       |                                   |   |+---------------------------------+|
       |                                   |   ||                                 ||
       |                                   |   ||  A baby widget has been born!   ||
       |                                   |   ||                                 ||
       |                                   |   |+---------------------------------+|
       +-----------------------------------+   +-----------------------------------+
       |   Press any key to breed widgets  |   |   Press any key to breed widgets  |
       +-----------------------------------+   +-----------------------------------+

At this point, the widget stack within the prop container would appear as follows.
   
       1. Static widget with 'prop' = WIDGET_KEEP_EXTENT
       2. Oldest baby widget
       3. 2nd Oldest baby widget
       4. 3rd Oldest baby widget
       5. Static widget with 'prop' = WIDGET_KEEP_EXTENT

Parameters
  • pif
    []:
    A pointer to an IPropContainer object.
  • pw
    []:
    Pointer to the widget to be inserted into the prop container's widget stack.
  • piwBefore
    []:
    Indicates where in the prop container's widget stack that the new widget should be inserted. This value may be expressed as either a pointer to a widget already in the widget stack, in which case the new widget will be inserted immediately before the widget pointed to by 'pb' -- or as a constant that identifies a relative position within the widget stack, as follows WIDGET_ZNORMAL - Allow BREW to place the inserted widget at the default location. For a prop container, this places the new widget at the top of container's widget stack. WIDGET_ZTOPMOST - The new widget should be inserted as the topmost widget in the container's widget stack. WIDGET_ZBOTTOMMOST - The new widget should be inserted at the bottommost widget in the container's widget stack.
  • pProp
    []:
    Pointer to a WidgetProp data structure, containing the proportional value for this widget, as well as its visibility attribute. If this parameter is NULL, pw will be inserted with WIDGET_KEEP_EXTENT for its proportion, and visibility will be set to TRUE.

Prototype
   int IPropContainer_Insert(IPropContainer *pif, IWidget *pw, IWidget *piwBefore, const WidgetProp *pProp);
Return
   
   AEE_SUCCESS   --  The widget was successfully inserted into the prop container's widget stack.
   AEE_EBADPARM  --  The widget pointer passed in 'pb' either does not exist, or refers to a widget
                     that is not in the prop container's widget stack.
   ENOMEMORY     --  The widget stack could not grow to accommodate a new widget.

Side Effect
Calling IPropContainer_Insert() will cause the prop container to adjust the object layout to include the newly added widget.
Comment
None
  • Follow