This is an old revision of the document!
Table of Contents
Start Page » DragonScript Scripting Language » Gui Themes » Define XML Widget Designer
Widget Designers
Widget designers can be defined inside gui themes using the designer tag or inside own XML files typically with the extension *.wdesigner.xml. The extension can be chosen differently if required. For both versions the same tag definition is used.
Widget designers are always based directly or indirectly on a type. This type is the Designer Prototype and defines what instance of WidgetDesigner is used in the scripts. It is important to choose the right prototype for a designer since the widget type and widget designer type are closely linked. For example you can use a Widget type designer for all kinds of widgets but a Button type designer is only working on Button widgets or subclasses thereof. If you choose the wrong designer type a run-time invalid cast exception is likely thrown.
The following prototypes are provided by default by the WidgetDesigners script class:
| Name | Script Class | Target Widget Class |
|---|---|---|
| Button | DefaultButtonDesigner | Button |
| CheckBox | DefaultCheckBoxDesigner | CheckBox |
| ComboBox | DefaultComboBoxDesigner | ComboBox |
| Desktop | DefaultWidgetDesigner | Desktop |
| Label | DefaultLabelDesigner | Label |
| ListBox | DefaultWidgetDesigner | ListBox |
| OptionBox | DefaultOptionBoxDesigner | OptionBox |
| PlayerChoiceEntry | DefaultLabelDesigner | OptionBox |
| ProgressBar | DefaultProgressBarDesigner | ProgressBar |
| ScrollBar | DefaultScrollBarDesigner | ScrollBar |
| SpinButton | DefaultSpinButtonDesigner | SpinButton |
| TextArea | DefaultTextAreaDesigner | TextArea |
| TextField | DefaultTextFieldDesigner | TextField |
| Widget | DefaultWidgetDesigner | Widget |
| Window | DefaultWindowDesigner | Window |
You can use custom prototypes by adding them to WidgetDesigners instance before loading gui themes. This is useful if you created custom widget subclasses requiring custom parameters.
This example defines a designer based on the Label prototype for use by Label widgets or subclasses thereof.
<designer name='MyLabelDesign' type='Label'> <!-- Creates designer as instance of DefaultLabelDesigner script class --> <!-- set parameters... --> </designer>
If you modify an existing designer the type of the original designer is taken over. These examples create designers by loading them from a file or from a previously defined designer.
<designer name='MyLabelDesign' extend='sharedDesign.wdesigner.xml'> <!-- Create designer by loading from an XML file. --> </designer> <designer name='MyLabelDesign2' extendNamed='MyLabelDesign'> <!-- Create designer by naming an already defined design. --> </designer>
Designer Parameters
Designers are configurated by setting parameters. For each supported parameter type an own tag exists. See Defining Parameters for an overview of the supported types. The supported parameters by designer type are listed below.
Widget
The most basic widget designer suitable for all widgets. If you do not know what type to use to style your widget use this one first unless another one matches better. Using this type creates an instance of DefaultWidgetDesigner as designer. All other widget designers subclass this type and thus share these parameters defined below. All types in the list above using DefaultWidgetDesigner belong to this category here.
The widget supports these display states to style individually:
- normal. Widget is in the normal or basic state.
- disabled. Widget is setEnabled(false) and does not accept input.
- hover. Mouse pointer is hovering over the widget or a child widget thereof
- focused. Widget has the input focus.
- focusedHover, Widget has the input focus and the mouse pointer is hovering over the widget or a child widget thereof.
In the list below replace {state} with one of the state names above. For example to define the background for disabled state the parameter name would be disabled.canvas.
| Parameter Name | Supported parameter type | Description |
|---|---|---|
| {state}.canvas | CanvasCreator | CanvasCreator to use to draw background of widget |
| {state}.border | BorderFactory | Border drawn around widget. Adds to the minimum size required of the widget |
| {state}.font | Font | Font to use for text if widget supports displaying text. |
| {state}.textColor | Color | Color to use for text if widget supports displaying text. |
| {state}.padding | BorderSize | Padding between widget content and widget border if the widget supports padding. Padding adds to the minimum size required by the widget. |
| {state}.minimumSize | Point | Explicit minimum size for widget. If not set (or set to null) the widget uses an appropriate minimum size. This is the default. Use explicit minimum size if you use background canvas creators requiring specifi sizes. In general it is best to let widgets calculate their size requirements on their own. |
| {state}.mousePointer | MousePointerFactory | Mouse pointer to use if the mouse is hovering over the widget. The first widget up the widget tree with a set mouse pointer (not null) is used. Typically you set this parameter only for Desktop widgets. To hide a mouse pointer in a widget use a Default mouse pointer with no parameters. This equals an invisible mouse pointer. |
Label
Widget designer suitable for Label widgets and subclasses thereof. Label widgets support text parameters defined in the Widget type. Furthermore they add some additional parameters.
| Parameter Name | Supported parameter type | Description |
|---|---|---|
| {state}.alignment | String | Horizontal and vertical alignment of text in the widget. String composes of comma-delimited alignment keywords. For horizontal alignment you can use left, right and center. For vertical alignment you can use top, bottom and middle. You can combine at most one keyword from both groups or use one group only. The default is center for horizontal alignment and middle for vertical alignment. The default value is thus center,middle. |
ProgressBar
Widget designer suitable for ProgressBar widgets and subclasses thereof. Progress bar widgets support text parameters defined in the Widget type. Additional parameters are present to design the progress bar shown behind the text.
| Parameter Name | Supported parameter type | Description |
|---|---|---|
| {state}.showPercentage | Boolean | Shows percentage text. Text always counts towards minimum size. Set minimum size explicitly if you need narrow progress bars |
| {state}.invertColorOverBar | Boolean | Invert {state}.textColor parameter for text parts overlapping with the progress bar to make it easier to read. |
Window
Widget designer suitable for Window widgets and subclasses thereof. Window widgets support a decoration to allow users to interact with the window. These additional parameters can be used.
| Parameter Name | Supported parameter type | Description |
|---|---|---|
| decoration | DecorationFactory | Factory used to create window Decoration instance. Can be null to create windows without decoration |
| modalDarken | Color | Color used to darken the entire window if a WindowModal is blocking this window. The default is 35% black color |
Button
Widget designer suitable for Button widgets and subclasses thereof. Button widgets support in addition to the regular widget state also a pressed button state. The label inside the button uses Label type with the designer selector Label.Button. This designer applies only to the button as a whole.
No additional parameters are supported except pressed as new possible value for {state}.XXX parameters.
CheckBox
Widget designer suitable for CheckBox widgets and subclasses thereof. Check box widgets are subclasses of Button widgets and share the pressed state. In addition they define images for the check box and tick mark. These additional parameters can be used.
OptionBox
Widget designer suitable for OptionBox widgets and subclasses thereof. Option box widgets are subclasses of Button widgets and share the pressed state. In addition they define images for the check box and selection mark. These additional parameters can be used.
ComboBox
Widget designer suitable for ComboBox widgets and subclasses thereof. Combo box widgets support in addition the regular widget states also a dropped-down state. The list is provided in a WindowPopup. The list box has the selector ListBox.ComboBox. The drop down button is drawn using a canvas creator and is no widget itself.
The new state droppedDown is a new possible value for {state}.XXX parameters. These additional parameters can be used.
| Parameter Name | Supported parameter type | Description |
|---|---|---|
| {state}.buttonDropDown | CanvasCreator | Canvas creator to draw drop down button |
| {state}.imageDropDown | Image | Image to use inside dropped down button |
