528 lines
24 KiB
ObjectPascal
528 lines
24 KiB
ObjectPascal
{
|
|
Copyright 2005-2012 Sandy Barbour and Ben Supnik All rights reserved. See
|
|
license.txt for usage. X-Plane SDK Version: 2.1.1
|
|
}
|
|
|
|
UNIT XPWidgets;
|
|
INTERFACE
|
|
{
|
|
## THEORY OF OPERATION AND NOTES
|
|
|
|
Widgets are persistent view 'objects' for X-Plane. A widget is an object
|
|
referenced by its opaque handle (widget ID) and the APIs in this file. You
|
|
cannot access the widget's guts directly. Every Widget has the following
|
|
intrinsic data:
|
|
|
|
- A bounding box defined in global screen coordinates with 0,0 in the
|
|
bottom left and +y = up, +x = right.
|
|
- A visible box, which is the intersection of the bounding box with the
|
|
widget's parents visible box.
|
|
- Zero or one parent widgets. (Always zero if the widget is a root widget.
|
|
- Zero or more child widgets.
|
|
- Whether the widget is a root. Root widgets are the top level plugin
|
|
windows.
|
|
- Whether the widget is visible.
|
|
- A text string descriptor, whose meaning varies from widget to widget.
|
|
- An arbitrary set of 32 bit integral properties defined by 32-bit integral
|
|
keys. This is how specific widgets store specific data.
|
|
- A list of widget callbacks proc that implements the widgets behaviors.
|
|
|
|
The Widgets library sends messages to widgets to request specific behaviors
|
|
or notify the widget of things.
|
|
|
|
Widgets may have more than one callback function, in which case messages
|
|
are sent to the most recently added callback function until the message is
|
|
handled. Messages may also be sent to parents or children; see the
|
|
XPWidgetDefs.h header file for the different widget message dispatching
|
|
functions. By adding a callback function to a window you can 'subclass' its
|
|
behavior.
|
|
|
|
A set of standard widgets are provided that serve common UI purposes. You
|
|
can also customize or implement entirely custom widgets.
|
|
|
|
Widgets are different than other view hierarchies (most notably Win32,
|
|
which they bear a striking resemblance to) in the following ways:
|
|
|
|
- Not all behavior can be patched. State that is managed by the XPWidgets
|
|
DLL and not by individual widgets cannot be customized.
|
|
- All coordinates are in global screen coordinates. Coordinates are not
|
|
relative to an enclosing widget, nor are they relative to a display
|
|
window.
|
|
- Widget messages are always dispatched synchronously, and there is no
|
|
concept of scheduling an update or a dirty region. Messages originate
|
|
from X-Plane as the sim cycle goes by. Since X-Plane is constantly
|
|
redrawing, so are widgets; there is no need to mark a part of a widget as
|
|
'needing redrawing' because redrawing happens frequently whether the
|
|
widget needs it or not.
|
|
- Any widget may be a 'root' widget, causing it to be drawn; there is no
|
|
relationship between widget class and rootness. Root widgets are
|
|
imlemented as XPLMDisply windows.
|
|
}
|
|
|
|
USES
|
|
XPWidgetDefs, XPLMDisplay;
|
|
{$A4}
|
|
{___________________________________________________________________________
|
|
* WIDGET CREATION AND MANAGEMENT
|
|
___________________________________________________________________________}
|
|
|
|
{
|
|
XPCreateWidget
|
|
|
|
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 then just be floating off in space
|
|
(and will not be drawn until it is placed in a 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.
|
|
}
|
|
FUNCTION XPCreateWidget(
|
|
inLeft : Integer;
|
|
inTop : Integer;
|
|
inRight : Integer;
|
|
inBottom : Integer;
|
|
inVisible : Integer;
|
|
inDescriptor : XPLMString;
|
|
inIsRoot : Integer;
|
|
inContainer : XPWidgetID;
|
|
inClass : XPWidgetClass) : XPWidgetID;
|
|
cdecl; external XPWIDGETS.DLL;
|
|
|
|
{
|
|
XPCreateCustomWidget
|
|
|
|
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.
|
|
}
|
|
FUNCTION XPCreateCustomWidget(
|
|
inLeft : Integer;
|
|
inTop : Integer;
|
|
inRight : Integer;
|
|
inBottom : Integer;
|
|
inVisible : Integer;
|
|
inDescriptor : XPLMString;
|
|
inIsRoot : Integer;
|
|
inContainer : XPWidgetID;
|
|
inCallback : XPWidgetFunc_t) : XPWidgetID;
|
|
cdecl; external XPWIDGETS.DLL;
|
|
|
|
{
|
|
XPDestroyWidget
|
|
|
|
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, the child widgets will simply end up with their parent set to 0.
|
|
}
|
|
PROCEDURE XPDestroyWidget(
|
|
inWidget : XPWidgetID;
|
|
inDestroyChildren : Integer);
|
|
cdecl; external XPWIDGETS.DLL;
|
|
|
|
{
|
|
XPSendMessageToWidget
|
|
|
|
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.
|
|
}
|
|
FUNCTION XPSendMessageToWidget(
|
|
inWidget : XPWidgetID;
|
|
inMessage : XPWidgetMessage;
|
|
inMode : XPDispatchMode;
|
|
inParam1 : intptr_t;
|
|
inParam2 : intptr_t) : Integer;
|
|
cdecl; external XPWIDGETS.DLL;
|
|
|
|
{___________________________________________________________________________
|
|
* WIDGET POSITIONING AND VISIBILITY
|
|
___________________________________________________________________________}
|
|
|
|
{
|
|
XPPlaceWidgetWithin
|
|
|
|
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.
|
|
}
|
|
PROCEDURE XPPlaceWidgetWithin(
|
|
inSubWidget : XPWidgetID;
|
|
inContainer : XPWidgetID);
|
|
cdecl; external XPWIDGETS.DLL;
|
|
|
|
{
|
|
XPCountChildWidgets
|
|
|
|
This routine returns the number of widgets another widget contains.
|
|
}
|
|
FUNCTION XPCountChildWidgets(
|
|
inWidget : XPWidgetID) : Integer;
|
|
cdecl; external XPWIDGETS.DLL;
|
|
|
|
{
|
|
XPGetNthChildWidget
|
|
|
|
This routine returns the widget ID of a child widget by index. Indexes are
|
|
0 based, from 0 to one minus the number of widgets in the parent,
|
|
inclusive. If the index is invalid, 0 is returned.
|
|
}
|
|
FUNCTION XPGetNthChildWidget(
|
|
inWidget : XPWidgetID;
|
|
inIndex : Integer) : XPWidgetID;
|
|
cdecl; external XPWIDGETS.DLL;
|
|
|
|
{
|
|
XPGetParentWidget
|
|
|
|
Returns the parent of a widget, or 0 if the widget has no parent. Root
|
|
widgets never have parents and therefore always return 0.
|
|
}
|
|
FUNCTION XPGetParentWidget(
|
|
inWidget : XPWidgetID) : XPWidgetID;
|
|
cdecl; external XPWIDGETS.DLL;
|
|
|
|
{
|
|
XPShowWidget
|
|
|
|
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.
|
|
}
|
|
PROCEDURE XPShowWidget(
|
|
inWidget : XPWidgetID);
|
|
cdecl; external XPWIDGETS.DLL;
|
|
|
|
{
|
|
XPHideWidget
|
|
|
|
Makes a widget invisible. See XPShowWidget for considerations of when a
|
|
widget might not be visible despite its own visibility state.
|
|
}
|
|
PROCEDURE XPHideWidget(
|
|
inWidget : XPWidgetID);
|
|
cdecl; external XPWIDGETS.DLL;
|
|
|
|
{
|
|
XPIsWidgetVisible
|
|
|
|
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.
|
|
}
|
|
FUNCTION XPIsWidgetVisible(
|
|
inWidget : XPWidgetID) : Integer;
|
|
cdecl; external XPWIDGETS.DLL;
|
|
|
|
{
|
|
XPFindRootWidget
|
|
|
|
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.
|
|
}
|
|
FUNCTION XPFindRootWidget(
|
|
inWidget : XPWidgetID) : XPWidgetID;
|
|
cdecl; external XPWIDGETS.DLL;
|
|
|
|
{
|
|
XPBringRootWidgetToFront
|
|
|
|
This routine makes the specified widget be in the front most 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.
|
|
}
|
|
PROCEDURE XPBringRootWidgetToFront(
|
|
inWidget : XPWidgetID);
|
|
cdecl; external XPWIDGETS.DLL;
|
|
|
|
{
|
|
XPIsWidgetInFront
|
|
|
|
This routine returns true if this widget's hierarchy is the front most
|
|
hierarchy. It returns false if the widget's hierarchy is not in front, or
|
|
if the widget is not in a rooted hierarchy.
|
|
}
|
|
FUNCTION XPIsWidgetInFront(
|
|
inWidget : XPWidgetID) : Integer;
|
|
cdecl; external XPWIDGETS.DLL;
|
|
|
|
{
|
|
XPGetWidgetGeometry
|
|
|
|
This routine returns the bounding box of a widget in global coordinates.
|
|
Pass NULL for any parameter you are not interested in.
|
|
}
|
|
PROCEDURE XPGetWidgetGeometry(
|
|
inWidget : XPWidgetID;
|
|
outLeft : PInteger; { Can be nil }
|
|
outTop : PInteger; { Can be nil }
|
|
outRight : PInteger; { Can be nil }
|
|
outBottom : PInteger); { Can be nil }
|
|
cdecl; external XPWIDGETS.DLL;
|
|
|
|
{
|
|
XPSetWidgetGeometry
|
|
|
|
This function changes the bounding box of a widget.
|
|
}
|
|
PROCEDURE XPSetWidgetGeometry(
|
|
inWidget : XPWidgetID;
|
|
inLeft : Integer;
|
|
inTop : Integer;
|
|
inRight : Integer;
|
|
inBottom : Integer);
|
|
cdecl; external XPWIDGETS.DLL;
|
|
|
|
{
|
|
XPGetWidgetForLocation
|
|
|
|
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.
|
|
}
|
|
FUNCTION XPGetWidgetForLocation(
|
|
inContainer : XPWidgetID;
|
|
inXOffset : Integer;
|
|
inYOffset : Integer;
|
|
inRecursive : Integer;
|
|
inVisibleOnly : Integer) : XPWidgetID;
|
|
cdecl; external XPWIDGETS.DLL;
|
|
|
|
{
|
|
XPGetWidgetExposedGeometry
|
|
|
|
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 elligible 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.
|
|
}
|
|
PROCEDURE XPGetWidgetExposedGeometry(
|
|
inWidgetID : XPWidgetID;
|
|
outLeft : PInteger; { Can be nil }
|
|
outTop : PInteger; { Can be nil }
|
|
outRight : PInteger; { Can be nil }
|
|
outBottom : PInteger); { Can be nil }
|
|
cdecl; external XPWIDGETS.DLL;
|
|
|
|
{___________________________________________________________________________
|
|
* ACCESSING WIDGET DATA
|
|
___________________________________________________________________________}
|
|
|
|
{
|
|
XPSetWidgetDescriptor
|
|
|
|
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.
|
|
}
|
|
PROCEDURE XPSetWidgetDescriptor(
|
|
inWidget : XPWidgetID;
|
|
inDescriptor : XPLMString);
|
|
cdecl; external XPWIDGETS.DLL;
|
|
|
|
{
|
|
XPGetWidgetDescriptor
|
|
|
|
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).
|
|
}
|
|
FUNCTION XPGetWidgetDescriptor(
|
|
inWidget : XPWidgetID;
|
|
outDescriptor : XPLMString;
|
|
inMaxDescLength : Integer) : Integer;
|
|
cdecl; external XPWIDGETS.DLL;
|
|
|
|
{
|
|
XPGetWidgetUnderlyingWindow
|
|
|
|
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.
|
|
}
|
|
FUNCTION XPGetWidgetUnderlyingWindow(
|
|
inWidget : XPWidgetID) : XPLMWindowID;
|
|
cdecl; external XPWIDGETS.DLL;
|
|
|
|
{
|
|
XPSetWidgetProperty
|
|
|
|
This function sets a widget's property. Properties are arbitrary values
|
|
associated by a widget by ID.
|
|
}
|
|
PROCEDURE XPSetWidgetProperty(
|
|
inWidget : XPWidgetID;
|
|
inProperty : XPWidgetPropertyID;
|
|
inValue : intptr_t);
|
|
cdecl; external XPWIDGETS.DLL;
|
|
|
|
{
|
|
XPGetWidgetProperty
|
|
|
|
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.
|
|
}
|
|
FUNCTION XPGetWidgetProperty(
|
|
inWidget : XPWidgetID;
|
|
inProperty : XPWidgetPropertyID;
|
|
inExists : PInteger) : intptr_t; { Can be nil }
|
|
cdecl; external XPWIDGETS.DLL;
|
|
|
|
{___________________________________________________________________________
|
|
* KEYBOARD MANAGEMENT
|
|
___________________________________________________________________________}
|
|
|
|
{
|
|
XPSetKeyboardFocus
|
|
|
|
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.
|
|
}
|
|
FUNCTION XPSetKeyboardFocus(
|
|
inWidget : XPWidgetID) : XPWidgetID;
|
|
cdecl; external XPWIDGETS.DLL;
|
|
|
|
{
|
|
XPLoseKeyboardFocus
|
|
|
|
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.
|
|
}
|
|
PROCEDURE XPLoseKeyboardFocus(
|
|
inWidget : XPWidgetID);
|
|
cdecl; external XPWIDGETS.DLL;
|
|
|
|
{
|
|
XPGetWidgetWithFocus
|
|
|
|
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.
|
|
}
|
|
FUNCTION XPGetWidgetWithFocus: XPWidgetID;
|
|
cdecl; external XPWIDGETS.DLL;
|
|
|
|
{___________________________________________________________________________
|
|
* CREATING CUSTOM WIDGETS
|
|
___________________________________________________________________________}
|
|
|
|
{
|
|
XPAddWidgetCallback
|
|
|
|
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.
|
|
}
|
|
PROCEDURE XPAddWidgetCallback(
|
|
inWidget : XPWidgetID;
|
|
inNewCallback : XPWidgetFunc_t);
|
|
cdecl; external XPWIDGETS.DLL;
|
|
|
|
{
|
|
XPGetWidgetClassFunc
|
|
|
|
Given a widget class, this function returns the callbacks that power that
|
|
widget class.
|
|
}
|
|
FUNCTION XPGetWidgetClassFunc(
|
|
inWidgetClass : XPWidgetClass) : XPWidgetFunc_t;
|
|
cdecl; external XPWIDGETS.DLL;
|
|
|
|
|
|
IMPLEMENTATION
|
|
|
|
END.
|