User Tools

Site Tools


dragengine:modules:dragonscript:xmlguitheme:widgetdesigner

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:

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.

These additional additional parameters can be used.

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.

These additional parameters can be used.

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 DecorationFactory 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.

Parameter Name Supported parameter type Description
{state}.imageBox Image Image to use as check box. The image is used in original size if set
{state}.imageCheck Image Image to use as check mark. The image is used in original size if set and centred inside the box

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.

Parameter Name Supported parameter type Description
{state}.imageBox Image Image to use as option box. The image is used in original size if set
{state}.imageSelect Image Image to use as select mark. The image is used in original size if set and centred inside the box

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

SpinButton

Widget designer suitable for SpinButton widgets and subclasses thereof.

These additional parameters can be used.

Parameter Name Supported parameter type Description
size Integer Fixed width in pixels of the spin button arrow buttons
buttonUp WidgetDesigner Widget designer to use for the up arrow button
buttonDown WidgetDesigner Widget designer to use for the down arrow button
{state}.imageUp Image Image to use for the up arrow button
{state}.imageDown Image Image to use for the down arrow button

ScrollBar

Widget designer suitable for ScrollBar widgets and subclasses thereof.

These additional parameters can be used.

Parameter Name Supported parameter type Description
size Integer Fixed width/height in pixels of the scroll bar depending on orientation
buttonUp WidgetDesigner Widget designer to use for the up arrow button
buttonDown WidgetDesigner Widget designer to use for the down arrow button
buttonLeft WidgetDesigner Widget designer to use for the left arrow button
buttonRight WidgetDesigner Widget designer to use for the right arrow button
{state}.imageUp Image Image to use for the up arrow button
{state}.imageDown Image Image to use for the down arrow button
{state}.imageLeft Image Image to use for the left arrow button
{state}.imageRight Image Image to use for the right arrow button
{state}.canvasFrame CanvasCreator Canvas creator to use for the scroll area frame
{state}.canvasKnob CanvasCreator Canvas creator to use for the scroll area knob
{state}.paddingKnobFrame BorderSize Padding between scroll area knob and frame
You could leave a comment if you were logged in.
dragengine/modules/dragonscript/xmlguitheme/widgetdesigner.txt · Last modified: 2018/02/28 15:08 by dragonlord