Widget Positioning And Visibility

XPPlaceWidgetWithin

function

This function changes which container a widget resides in. You may NOT use this function on a root widget! inSubWidget is the widget that will be moved. Pass a widget ID in inContainer to make inSubWidget be a child of inContainer. It will become the last/closest widget in the container. Pass 0 to remove the widget from any container. Any call to this other than passing the widget ID of the old parent of the affected widget will cause the widget to be removed from its old parent. Placing a widget within its own parent simply makes it the last widget.

NOTE: this routine does not reposition the sub widget in global coordinates. If the container has layout management code, it will reposition the subwidget for you, otherwise you must do it with SetWidgetGeometry.

XPLM_API void       XPPlaceWidgetWithin(
                         XPWidgetID           inSubWidget,
                         XPWidgetID           inContainer
                    );

XPCountChildWidgets

function

This routine returns the number of widgets another widget contains.

XPLM_API int        XPCountChildWidgets(
                         XPWidgetID           inWidget
                    );

XPGetNthChildWidget

function

This routine returns the widget ID of a child widget by index. Indexes are 0 based, from 0 to the number of widgets in the parentone minus one, inclusive. If the index is invalid, 0 is returned.

XPLM_API XPWidgetID XPGetNthChildWidget(
                         XPWidgetID           inWidget,
                         int                  inIndex
                    );

XPGetParentWidget

function

Returns the parent of a widget, or 0 if the widget has no parent. Root widgets never have parents and therefore always return 0.

XPLM_API XPWidgetID XPGetParentWidget(
                         XPWidgetID           inWidget
                    );

XPShowWidget

function

This routine makes a widget visible if it is not already. Note that if a widget is not in a rooted widget hierarchy or one of its parents is not visible, it will still not be visible to the user.

XPLM_API void       XPShowWidget(
                         XPWidgetID           inWidget
                    );

XPHideWidget

function

Makes a widget invisible. See XPShowWidget for considerations of when a widget might not be visible despite its own visibility state.

XPLM_API void       XPHideWidget(
                         XPWidgetID           inWidget
                    );

XPIsWidgetVisible

function

This returns 1 if a widget is visible, 0 if it is not. Note that this routine takes into consideration whether a parent is invisible. Use this routine to tell if the user can see the widget.

XPLM_API int        XPIsWidgetVisible(
                         XPWidgetID           inWidget
                    );

XPFindRootWidget

function

Returns the Widget ID of the root widget that contains the passed in widget or NULL if the passed in widget is not in a rooted hierarchy.

XPLM_API XPWidgetID XPFindRootWidget(
                         XPWidgetID           inWidget
                    );

XPBringRootWidgetToFront

function

This routine makes the specified widget be in the frontmost widget hierarchy. If this widget is a root widget, its widget hierarchy comes to front, otherwise the widget's root is brought to the front. If this widget is not in an active widget hiearchy (e.g. there is no root widget at the top of the tree), this routine does nothing.

XPLM_API void       XPBringRootWidgetToFront(
                         XPWidgetID           inWidget
                    );

XPIsWidgetInFront

function

This routine returns true if this widget's hierarchy is the frontmost hierarchy. It returns false if the widget's hierarchy is not in front, or if the widget is not in a rooted hierarchy.

XPLM_API int        XPIsWidgetInFront(
                         XPWidgetID           inWidget
                    );

XPGetWidgetGeometry

function

This routine returns the bounding box of a widget in global coordinates. Pass NULL for any parameter you are not interested in.

XPLM_API void       XPGetWidgetGeometry(
                         XPWidgetID           inWidget,
                         int *                outLeft,    /* Can be NULL */
                         int *                outTop,    /* Can be NULL */
                         int *                outRight,    /* Can be NULL */
                         int *                outBottom    /* Can be NULL */
                    );

XPSetWidgetGeometry

function

This function changes the bounding box of a widget.

XPLM_API void       XPSetWidgetGeometry(
                         XPWidgetID           inWidget,
                         int                  inLeft,
                         int                  inTop,
                         int                  inRight,
                         int                  inBottom
                    );

XPGetWidgetForLocation

function

Given a widget and a location, this routine returns the widget ID of the child of that widget that owns that location. If inRecursive is true then this will return a child of a child of a widget as it tries to find the deepest widget at that location. If inVisibleOnly is true, then only visible widgets are considered, otherwise all widgets are considered. The widget ID passed for inContainer will be returned if the location is in that widget but not in a child widget. 0 is returned if the location is not in the container.

NOTE: if a widget's geometry extends outside its parents geometry, it will not be returned by this call for mouse locations outside the parent geometry. The parent geometry limits the child's eligibility for mouse location.

XPLM_API XPWidgetID XPGetWidgetForLocation(
                         XPWidgetID           inContainer,
                         int                  inXOffset,
                         int                  inYOffset,
                         int                  inRecursive,
                         int                  inVisibleOnly
                    );

XPGetWidgetExposedGeometry

function

This routine returns the bounds of the area of a widget that is completely within its parent widgets. Since a widget's bounding box can be outside its parent, part of its area will not be eligible for mouse clicks and should not draw. Use XPGetWidgetGeometry to find out what area defines your widget's shape, but use this routine to find out what area to actually draw into. Note that the widget library does not use OpenGL clipping to keep frame rates up, although you could use it internally.

XPLM_API void       XPGetWidgetExposedGeometry(
                         XPWidgetID           inWidgetID,
                         int *                outLeft,    /* Can be NULL */
                         int *                outTop,    /* Can be NULL */
                         int *                outRight,    /* Can be NULL */
                         int *                outBottom    /* Can be NULL */
                    );