Developer

API Reference

IXYContainer_Insert()

Brew Release
Brew MP 1.0.2
See Also
- IXYContainer Interface
- IWidget Interface
- WidgetPos
- IXYContainer_Remove()
Description
This function allows an application to insert a widget into the XY container's widget stack -- at the top of the stack, at the bottom, or some place inbetween. By default, widgets will be inserted at the top of the stack. However, an application may choose to instead insert widgets anywhere within the container's widget stack. For example, consider an application that periodically wishes to flash subliminal messages to the user behind the current focus of the user's attention. Such an application might want to create an image widget, then insert this widget directly behind the front-most widget, displaying a quick image of Happy Couples sitting at a bar drinking frosty beverages (just for an instant) immediately behind the widget in the foreground, then remove that widget from the display before the user even knows what hit them (call your local broker now and start loading up on frosty beverage stocks). Where the widget is inserted in the XY container's widget stack depends on the value passed in the 'piwBefore' parameter.
Parameters
  • pif
    []:
    [in] A pointer to an IXYContainer object.
  • pw
    []:
    [in] Pointer to the widget to be inserted into the XY container's widget stack.
  • piwBefore
    []:
    [in] Indicates where in the XY 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 'piwBefore' -- 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 an XY 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.
  • ppos
    []:
    [in] Const pointer to a WidgetPos data structure, specifying the location where the widget should be displayed within the container, as well as its visibility attribute for this widget. If this parameter is set to NULL, 'piwBefore' will be inserted at (0,0), and visibility will be set to TRUE.

Interface
Prototype
   int IXYContainer_Insert(IXYContainer* pif,
                           IWidget* pw,
                           IWidget* piwBefore,
                           const WidgetPos* ppos);
Return
   
   AEE_SUCCESS   --  The widget was successfully inserted into the XY container's widget stack.
   AEE_EBADPARM  --  The widget pointer passed in 'piwBefore' either does not exist,
                     or refers to a widget that is not in the XY container's widget stack.
   ENOMEMORY     --  The widget stack could not grow to accomodate a new widget.

Side Effect
None
Comment
Do not forget to set the extent of widget's inserted to an XY container! All widgets are initially created with an extent of 0x0. If you create a widget and insert it to an XY container without setting its extent it will not be visible
  • Follow