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.

XPCreateCustomWidget

WIDGET_API XPWidgetID XPCreateCustomWidget(
                         int                  inLeft,
                         int                  inTop,
                         int                  inRight,
                         int                  inBottom,
                         int                  inVisible,
                         const char *         inDescriptor,
                         int                  inIsRoot,
                         XPWidgetID           inContainer,
                         XPWidgetFunc_t       inCallback);

This function is the same as XPCreateWidget except that instead of passing a class ID, you pass your widget callback function pointer defining the widget. Use this function to define a custom widget. All parameters are the same as XPCreateWidget, except that the widget class has been replaced with the widget function.

XPDestroyWidget

WIDGET_API void       XPDestroyWidget(
                         XPWidgetID           inWidget,
                         int                  inDestroyChildren);

This class destroys a widget. Pass in the ID of the widget to kill. If you pass 1 for inDestroyChilren, the widget’s children will be destroyed first, then this widget will be destroyed. (Furthermore, the widget’s children will be destroyed with the inDestroyChildren flag set to 1, so the destruction will recurse down the widget tree.) If you pass 0 for this flag, direct child widgets will simply end up with their parent set to 0.

XPSendMessageToWidget

WIDGET_API int        XPSendMessageToWidget(
                         XPWidgetID           inWidget,
                         XPWidgetMessage      inMessage,
                         XPDispatchMode       inMode,
                         intptr_t             inParam1,
                         intptr_t             inParam2);

This sends any message to a widget. You should probably not go around simulating the predefined messages that the widgets library defines for you. You may however define custom messages for your widgets and send them with this method.

This method supports several dispatching patterns; see XPDispatchMode for more info. The function returns 1 if the message was handled, 0 if it was not.

For each widget that receives the message (see the dispatching modes), each widget function from the most recently installed to the oldest one receives the message in order until it is handled.

XPPlaceWidgetWithin

WIDGET_API void       XPPlaceWidgetWithin(
                         XPWidgetID           inSubWidget,
                         XPWidgetID           inContainer);

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.

XPCountChildWidgets

WIDGET_API int        XPCountChildWidgets(
                         XPWidgetID           inWidget);

This routine returns the number of widgets another widget contains.

XPGetNthChildWidget

WIDGET_API XPWidgetID XPGetNthChildWidget(
                         XPWidgetID           inWidget,
                         int                  inIndex);

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.

XPGetParentWidget

WIDGET_API XPWidgetID XPGetParentWidget(
                         XPWidgetID           inWidget);

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

XPShowWidget

WIDGET_API void       XPShowWidget(
                         XPWidgetID           inWidget);

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.

XPHideWidget

WIDGET_API void       XPHideWidget(
                         XPWidgetID           inWidget);

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

XPIsWidgetVisible

WIDGET_API int        XPIsWidgetVisible(
                         XPWidgetID           inWidget);

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.

XPFindRootWidget

WIDGET_API XPWidgetID XPFindRootWidget(
                         XPWidgetID           inWidget);

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.

XPBringRootWidgetToFront

WIDGET_API void       XPBringRootWidgetToFront(
                         XPWidgetID           inWidget);

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.

XPIsWidgetInFront

WIDGET_API int        XPIsWidgetInFront(
                         XPWidgetID           inWidget);

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.

XPGetWidgetGeometry

WIDGET_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 */

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

XPSetWidgetGeometry

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

This function changes the bounding box of a widget.

XPGetWidgetForLocation

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

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.

XPGetWidgetExposedGeometry

WIDGET_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 */

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.

XPSetWidgetDescriptor

WIDGET_API void       XPSetWidgetDescriptor(
                         XPWidgetID           inWidget,
                         const char *         inDescriptor);

Every widget has a descriptor, which is a text string. What the text string is used for varies from widget to widget; for example, a push button’s text is its descriptor, a caption shows its descriptor, and a text field’s descriptor is the text being edited. In other words, the usage for the text varies from widget to widget, but this API provides a universal and convenient way to get at it. While not all UI widgets need their descriptor, many do.

XPGetWidgetDescriptor

WIDGET_API int        XPGetWidgetDescriptor(
                         XPWidgetID           inWidget,
                         char *               outDescriptor,
                         int                  inMaxDescLength);

This routine returns the widget’s descriptor. Pass in the length of the buffer you are going to receive the descriptor in. The descriptor will be null terminated for you. This routine returns the length of the actual descriptor; if you pass NULL for outDescriptor, you can get the descriptor’s length without getting its text. If the length of the descriptor exceeds your buffer length, the buffer will not be null terminated (this routine has ‘strncpy’ semantics).

XPGetWidgetUnderlyingWindow

WIDGET_API XPLMWindowID XPGetWidgetUnderlyingWindow(
                         XPWidgetID           inWidget);

Returns the window (from the XPLMDisplay API) that backs your widget window. If you have opted in to modern windows, via a call to XPLMEnableFeature(“XPLM_USE_NATIVE_WIDGET_WINDOWS”, 1), you can use the returned window ID for display APIs like XPLMSetWindowPositioningMode(), allowing you to pop the widget window out into a real OS window, or move it into VR.

XPSetWidgetProperty

WIDGET_API void       XPSetWidgetProperty(
                         XPWidgetID           inWidget,
                         XPWidgetPropertyID   inProperty,
                         intptr_t             inValue);

This function sets a widget’s property. Properties are arbitrary values associated by a widget by ID.

XPGetWidgetProperty

WIDGET_API intptr_t   XPGetWidgetProperty(
                         XPWidgetID           inWidget,
                         XPWidgetPropertyID   inProperty,
                         int *                inExists);    /* Can be NULL */

This routine returns the value of a widget’s property, or 0 if the property is not defined. If you need to know whether the property is defined, pass a pointer to an int for inExists; the existence of that property will be returned in the int. Pass NULL for inExists if you do not need this information.

XPSetKeyboardFocus

WIDGET_API XPWidgetID XPSetKeyboardFocus(
                         XPWidgetID           inWidget);

Controls which widget will receive keystrokes. Pass the widget ID of the widget to get the keys. Note that if the widget does not care about keystrokes, they will go to the parent widget, and if no widget cares about them, they go to X-Plane.

If you set the keyboard focus to widget ID 0, X-Plane gets keyboard focus.

This routine returns the widget ID that ended up with keyboard focus, or 0 for X-Plane.

Keyboard focus is not changed if the new widget will not accept it. For setting to X-Plane, keyboard focus is always accepted.

XPLoseKeyboardFocus

WIDGET_API void       XPLoseKeyboardFocus(
                         XPWidgetID           inWidget);

This causes the specified widget to lose focus; focus is passed to its parent, or the next parent that will accept it. This routine does nothing if this widget does not have focus.

XPGetWidgetWithFocus

WIDGET_API XPWidgetID XPGetWidgetWithFocus(void);

This routine returns the widget that has keyboard focus, or 0 if X-Plane has keyboard focus or some other plugin window that does not have widgets has focus.

XPAddWidgetCallback

WIDGET_API void       XPAddWidgetCallback(
                         XPWidgetID           inWidget,
                         XPWidgetFunc_t       inNewCallback);

This function adds a new widget callback to a widget. This widget callback supercedes any existing ones and will receive messages first; if it does not handle messages they will go on to be handled by pre-existing widgets.

The widget function will remain on the widget for the life of the widget. The creation message will be sent to the new callback immediately with the widget ID, and the destruction message will be sent before the other widget function receives a destruction message.

This provides a way to ‘subclass’ an existing widget. By providing a second hook that only handles certain widget messages, you can customize or extend widget behavior.

XPGetWidgetClassFunc

WIDGET_API XPWidgetFunc_t XPGetWidgetClassFunc(
                         XPWidgetClass        inWidgetClass);

Given a widget class, this function returns the callbacks that power that widget class.