XPStandardWidgets¶
To use:
import xp
The standard widgets are widgets built into the widgets library. While you
can gain access to the widget function that drives them, you generally use
them by calling createWidget() and then listening for special messages,
etc.
The standard widgets often send mesages to themselves when the user performs an event; these messages are sent up the widget hierarchy until they are handled. So you can add a widget proc directly to a push button (for example) to intercept the message when it is clicked, or you can put one widget proc on a window for all of the push buttons in the window. Most of these messages contain the original widget ID as a parameter so you can know which widget is messaging no matter who it is sent to.
Widgets have properties which can be accessed using getWidgetProperty() and
setWidgetProperty(). Common properties (applicable to all most widgets are
listed XPWidgetPropertyID
Widget also receiving messages common to all widgets. These are listed XPWidgetMessage.
Main Window¶
The main window widget class provides a “window” as the user knows it. These windows are dragable and can be selected. Use them to create floating windows and non-modal dialogs.
Properties¶
- Property_MainWindowType = 1100¶
This property specifies the type of window. Set to one of the main window styles:
- MainWindowStyle_MainWindow¶
=0
The standard main window; pin stripes on XP7+
- MainWindowStyle_Translucent¶
=1
A translucent dark gray window, like the one ATC messages appear in.
- Property_MainWindowHasCloseBoxes = 1200¶
This property specifies whether the main window has close boxes in its corners.
Sub Window¶
X-Plane dialogs are divided into separate areas; the sub window widgets allow you to make these areas. Create one main window and place several subwindows inside it. Then place your controls inside the subwindows.
Properties¶
- Property_SubWindowType = 1200¶
This property specifies the type of window. Set to one of the subwindow types:
- SubWindowStyle_SubWindow¶
=0
A panel that sits inside a main window.
- SubWindowStyle_Screen¶
=2
A screen that sits inside a panel for showing text information.
- SubWindowStyle_ListView¶
=3
A list view for scrolling lists.
Button¶
The button class provides a number of different button styles and behaviors, including push buttons, radio buttons, check boxes, etc. The button label appears on or next to the button depending on the button’s appearance, or type.
The button’s behavior is a separate property that dictates who it hilights and what kinds of messages it sends. Since behavior and type are different, you can do strange things like make check boxes that act as push buttons or push buttons with radio button behavior.
Properties¶
- Property_ButtonType = 1300¶
This property sets the visual type of button. Use one of the button types:
- PushButton¶
=0
This is a standard push button, like an ‘OK’ or ‘Cancel’ button in a dialog box.
- RadioButton¶
=1
A check box or radio button. Use this and the button behaviors below to get the desired behavior.
- WindowCloseBox¶
=3
A window close box.
- LittleDownArrow¶
=5
A small down arrow.
- LittleUpArrow¶
=6
A small up arrow.
- Property_ButtonBehavior = 1301¶
This property sets the button’s behavior. Use one of the button behaviors below.
- ButtonBehaviorPushButton¶
=0
Standard push button behavior. The button hilites while the mouse is clicked over it and unhilites when the mouse is moved outside of it or released. If the mouse is released over the button, the Msg_PushButtonPressed message is sent.
- ButtonBehaviorCheckBox¶
=1
Check box behavior. The button immediately toggles its value when the mouse is clicked and sends out a Msg_ButtonStateChanged message.
- ButtonBehaviorRadioButton¶
=2
Radio button behavior. The button immediately sets its state to one and sends out a Msg_ButtonStateChanged message if it was not already set to one. You must turn off other radio buttons in a group in your code.
- Property_ButtonState = 1302¶
This property tells whether a check box or radio button is “checked” or not. Not used for push buttons.
Messages¶
- Msg_PushButtonPressed = 1300¶
This message is sent when the user completes a click and release in a button with push button behavior. Parameter one of the message is the widget ID of the button. This message is dispatched up the widget hierarchy.
Param 1
Param 2
WidgetID of the button
N/A
- Msg_ButtonStateChanged = 1301¶
This message is sent when a button is clicked that has radio button or check box behavior and its value changes. (Note that if the value changes by setting a property you do not receive this message!) Parameter one is the widget ID of the button, parameter 2 is the new state value, either zero or one. This message is dispatched up the widget hierarchy.
Param 1
Param 2
WidgetID of the button
New state value (0 or 1)
Text Field¶
The text field widget provides an editable text field including mouse selection and keyboard navigation. The contents of the text field are its descriptor. (The descriptor changes as the user types.)
The text field can have a number of types, that effect the visual layout of the text field. The text field sends messages to itself so you may control its behavior.
If you need to filter keystrokes, add a new handler and intercept the key press message. Since key presses are passed by pointer, you can modify the keystroke and pass it through to the text field widget.
Properties¶
- Property_EditFieldSelStart = 1400¶
This is the character position the selection starts at, zero based. If it is the same as the end insertion point, the insertion point is not a selection.
- Property_EditFieldSelEnd = 1401¶
This is the character position of the end of the selection.
- Property_EditFieldSelDragStart = 1402¶
This is the character position a drag was started at if the user is dragging to select text, or -1 if a drag is not in progress.
- Property_TextFieldType = 1403¶
This is the type of text field to display:
- TextEntryField¶
=0
A field for text entry.
- TextTransparent¶
=3
A transparent text field. The user can type and the text is drawn, but no background is drawn. You can draw your own background by adding a widget handler and prehandling the draw message.
- TextTranslucent¶
=4
A translucent edit field, dark gray.
- Property_PasswordMode = 1404¶
Set this property to 1 to password protect the field. Characters will be drawn as *s even though the descriptor will contain plain-text.
- Property_MaxCharacters = 1405¶
The max number of characters you can enter, if limited. Zero means unlimited.
- Property_ScrollPosition = 1406¶
The first visible character on the left. This effectively scrolls the text field.
- Property_Font = 1407¶
The font to draw the field’s text with. (An XPLMFontID.)
- Property_ActiveEditSide = 1408¶
This is the active side of the insert selection. (Internal)
Scroll Bar¶
A standard scroll bar or slider control. The scroll bar has a minimum, maximum and current value that is updated when the user drags it. The scroll bar sends continuous messages as it is dragged.
Properties¶
- Property_ScrollBarSliderPosition = 1500¶
The current position of the thumb (in between the min and max, inclusive)
- Property_ScrollBarMin = 1501¶
The value the scroll bar has when the thumb is in the lowest position.
- Property_ScrollBarMax = 1502¶
The value the scroll bar has when the thumb is in the highest position.
- Property_ScrollBarPageAmount = 1503¶
How many units to moev the scroll bar when clicking next to the thumb. The scroll bar always moves one unit when the arrows are clicked.
- Property_ScrollBarType = 1504¶
The type of scrollbar:
- ScrollBarTypeScrollBar¶
=0
A standard X-Plane scroll bar (with arrows on the ends).
- ScrollBarTypeSlider¶
=1
A slider, no arrows.
- Property_ScrollBarSlop = 1505¶
Used internally.
Caption¶
A caption is a simple widget that shows its descriptor as a string, useful for labeling parts of a window. It always shows its descriptor as its string and is otherwise transparent.
General Graphics¶
The general graphics widget can show one of many icons available from X-Plane.
Properties¶
- Property_GeneralGraphicsType¶
This property controls the type of icon that is drawn:
- Ship¶
=4
- ILSGlideScope¶
=5
- MarkerLeft¶
=6
- _Airport¶
=7
- NDB¶
=8
- VOR¶
=9
- RadioTower¶
=10
- AircraftCarrier¶
=11
- Fire¶
=12
- MarkerRight¶
=13
- CustomObject¶
=14
- CoolingTower¶
=15
- SmokeStack¶
=16
- Building¶
=17
- PowerLine¶
=18
- VORWithCompassRose¶
=19
- OilPlatform¶
=21
- OilPlatformSmall¶
=22
- WayPoint¶
=23
Progress Indicator¶
This widget implements a progress indicator as seen when X-Plane starts up.
