XPCreateWidget

WIDGET_API XPWidgetID XPCreateWidget(
                         int                  inLeft,
                         int                  inTop,
                         int                  inRight,
                         int                  inBottom,
                         int                  inVisible,
                         const char *         inDescriptor,
                         int                  inIsRoot,
                         XPWidgetID           inContainer,
                         XPWidgetClass        inClass);

This function creates a new widget and returns the new widget’s ID to you. If the widget creation fails for some reason, it returns NULL. Widget creation will fail either if you pass a bad class ID or if there is not adequate memory.

Input Parameters:

  • Top, left, bottom, and right in global screen coordinates defining the widget’s location on the screen.
  • inVisible is 1 if the widget should be drawn, 0 to start the widget as hidden.
  • inDescriptor is a null terminated string that will become the widget’s descriptor.
  • inIsRoot is 1 if this is going to be a root widget, 0 if it will not be.
  • inContainer is the ID of this widget’s container. It must be 0 for a root widget. For a non-root widget, pass the widget ID of the widget to place this widget within. If this widget is not going to start inside another widget, pass 0; this new widget will be created but will not be drawn until it is placed inside another widget.
  • inClass is the class of the widget to draw. Use one of the predefined class-IDs to create a standard widget.

A note on widget embedding: a widget is only called (and will be drawn, etc.) if it is placed within a widget that will be called. Root widgets are always called. So it is possible to have whole chains of widgets that are simply not called. You can preconstruct widget trees and then place them into root widgets later to activate them if you wish.