IXYContainer_Insert()

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.

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

Qualcomm and Brew are trademarks of Qualcomm Incorporated, registered in the United States and other countries. Trademarks of Qualcomm Incorporated are used with permission. Other products and brand names may be trademarks or registered trademarks of their respective owners.