[[:start|Start Page]] >> [[dragengine:modules:dragonscript:main|DragonScript Scripting Language]] >> [[dragengine:modules:dragonscript:guitheme|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 #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1Designers_1_1WidgetDesigners.html,WidgetDesigners~@# script class: ^ Name ^ Script Class ^ Target Widget Class ^ | [[#button|Button]] | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1Designers_1_1DefaultButtonDesigner.html,DefaultButtonDesigner~@# | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1Button.html,Button~@# | | [[#checkbox|CheckBox]] | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1Designers_1_1DefaultCheckBoxDesigner.html,DefaultCheckBoxDesigner~@# | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1CheckBox.html,CheckBox~@# | | [[#combobox|ComboBox]] | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1Designers_1_1DefaultComboBoxDesigner.html,DefaultComboBoxDesigner~@# | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1ComboBox.html,ComboBox~@# | | [[#widget|Desktop]] | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1Designers_1_1DefaultWidgetDesigner.html,DefaultWidgetDesigner~@# | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1Desktop.html,Desktop~@# | | [[#label|Label]] | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1Designers_1_1DefaultLabelDesigner.html,DefaultLabelDesigner~@# | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1Label.html,Label~@# | | [[#widget|ListBox]] | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1Designers_1_1DefaultWidgetDesigner.html,DefaultWidgetDesigner~@# | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1ListBox.html,ListBox~@# | | [[#optionbox|OptionBox]] | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1Designers_1_1DefaultOptionBoxDesigner.html,DefaultOptionBoxDesigner~@# | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1OptionBox.html,OptionBox~@# | | [[#label|PlayerChoiceEntry]] | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1Designers_1_1DefaultLabelDesigner.html,DefaultLabelDesigner~@# | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1OptionBox.html,OptionBox~@# | | [[#progressbar|ProgressBar]] | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1Designers_1_1DefaultProgressBarDesigner.html,DefaultProgressBarDesigner~@# | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1ProgressBar.html,ProgressBar~@# | | [[#scrollbar|ScrollBar]] | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1Designers_1_1DefaultScrollBarDesigner.html,DefaultScrollBarDesigner~@# | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1ScrollBar.html,ScrollBar~@# | | [[#spinbutton|SpinButton]] | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1Designers_1_1DefaultSpinButtonDesigner.html,DefaultSpinButtonDesigner~@# | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1SpinButton.html,SpinButton~@# | | [[#widget|TextArea]] | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1Designers_1_1DefaultTextAreaDesigner.html,DefaultTextAreaDesigner~@# | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1TextArea.html,TextArea~@# | | [[#widget|TextField]] | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1Designers_1_1DefaultTextFieldDesigner.html,DefaultTextFieldDesigner~@# | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1TextField.html,TextField~@# | | [[#widget|Widget]] | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1Designers_1_1DefaultWidgetDesigner.html,DefaultWidgetDesigner~@# | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1Widget.html,Widget~@# | | [[#window|Window]] | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1Designers_1_1DefaultWindowDesigner.html,DefaultWindowDesigner~@# | #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1Window.html,Window~@# | You can use custom prototypes by adding them to #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1Designers_1_1WidgetDesigners.html,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. 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 Parameters ====== Designers are configurated by setting parameters. For each supported parameter type an own tag exists. See [[dragengine:modules:dragonscript:xmlguitheme:parameters|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 #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1Designers_1_1DefaultWidgetDesigner.html,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 | [[dragengine:modules:dragonscript:xmlguitheme:parameters#canvas_creator|CanvasCreator]] | CanvasCreator to use to draw background of widget | | {state}.border | [[dragengine:modules:dragonscript:xmlguitheme:parameters#border|BorderFactory]] | Border drawn around widget. Adds to the minimum size required of the widget | | {state}.font | [[dragengine:modules:dragonscript:xmlguitheme:parameters#font|Font]] | Font to use for text if widget supports displaying text. | | {state}.textColor | [[dragengine:modules:dragonscript:xmlguitheme:parameters#color|Color]] | Color to use for text if widget supports displaying text. | | {state}.padding | [[dragengine:modules:dragonscript:xmlguitheme:parameters#border_size|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 | [[dragengine:modules:dragonscript:xmlguitheme:parameters#point|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 | [[dragengine:modules:dragonscript:xmlguitheme:parameters#mouse_pointer|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 #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1Label.html,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 | [[dragengine:modules:dragonscript:xmlguitheme:parameters#string|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 #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1ProgressBar.html,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 | [[dragengine:modules:dragonscript:xmlguitheme:parameters#boolean|Boolean]] | Shows percentage text. Text always counts towards minimum size. Set minimum size explicitly if you need narrow progress bars | | {state}.invertColorOverBar | [[dragengine:modules:dragonscript:xmlguitheme:parameters#boolean|Boolean]] | Invert {state}.textColor parameter for text parts overlapping with the progress bar to make it easier to read. | ===== Window ===== Widget designer suitable for #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1Window.html,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 | [[dragengine:modules:dragonscript:xmlguitheme:parameters#decoration|DecorationFactory]] | #@LinkApiDocDEDS2_HTML~interfaceDragengine_1_1Gui_1_1Decorations_1_1Factories_1_1DecorationFactory.html,DecorationFactory~@# used to create window #@LinkApiDocDEDS2_HTML~interfaceDragengine_1_1Gui_1_1Decorations_1_1Decoration.html,Decoration~@# instance. Can be null to create windows without decoration | | modalDarken | [[dragengine:modules:dragonscript:xmlguitheme:parameters#color|Color]] | Color used to darken the entire window if a #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1WindowModal.html,WindowModal~@# is blocking this window. The default is 35% black color | ===== Button ===== Widget designer suitable for #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1Button.html,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 #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1CheckBox.html,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 | [[dragengine:modules:dragonscript:xmlguitheme:parameters#image|Image]] | Image to use as check box. The image is used in original size if set | | {state}.imageCheck | [[dragengine:modules:dragonscript:xmlguitheme:parameters#image|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 #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1OptionBox.html,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 | [[dragengine:modules:dragonscript:xmlguitheme:parameters#image|Image]] | Image to use as option box. The image is used in original size if set | | {state}.imageSelect | [[dragengine:modules:dragonscript:xmlguitheme:parameters#image|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 #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1ComboBox.html,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 #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1WindowPopup.html,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 | [[dragengine:modules:dragonscript:xmlguitheme:parameters#canvas_creator|CanvasCreator]] | Canvas creator to draw drop down button | | {state}.imageDropDown | [[dragengine:modules:dragonscript:xmlguitheme:parameters#image|Image]] | Image to use inside dropped down button | ===== SpinButton ===== Widget designer suitable for #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1SpinButton.html,SpinButton~@# widgets and subclasses thereof. These additional parameters can be used. ^ Parameter Name ^ Supported parameter type ^ Description ^ | size | [[dragengine:modules:dragonscript:xmlguitheme:parameters#integer|Integer]] | Fixed width in pixels of the spin button arrow buttons | | buttonUp | [[dragengine:modules:dragonscript:xmlguitheme:parameters#widget_designer|WidgetDesigner]] | Widget designer to use for the up arrow button | | buttonDown | [[dragengine:modules:dragonscript:xmlguitheme:parameters#widget_designer|WidgetDesigner]] | Widget designer to use for the down arrow button | | {state}.imageUp | [[dragengine:modules:dragonscript:xmlguitheme:parameters#image|Image]] | Image to use for the up arrow button | | {state}.imageDown | [[dragengine:modules:dragonscript:xmlguitheme:parameters#image|Image]] | Image to use for the down arrow button | ===== ScrollBar ===== Widget designer suitable for #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1ScrollBar.html,ScrollBar~@# widgets and subclasses thereof. These additional parameters can be used. ^ Parameter Name ^ Supported parameter type ^ Description ^ | size | [[dragengine:modules:dragonscript:xmlguitheme:parameters#integer|Integer]] | Fixed width/height in pixels of the scroll bar depending on orientation | | buttonUp | [[dragengine:modules:dragonscript:xmlguitheme:parameters#widget_designer|WidgetDesigner]] | Widget designer to use for the up arrow button | | buttonDown | [[dragengine:modules:dragonscript:xmlguitheme:parameters#widget_designer|WidgetDesigner]] | Widget designer to use for the down arrow button | | buttonLeft | [[dragengine:modules:dragonscript:xmlguitheme:parameters#widget_designer|WidgetDesigner]] | Widget designer to use for the left arrow button | | buttonRight | [[dragengine:modules:dragonscript:xmlguitheme:parameters#widget_designer|WidgetDesigner]] | Widget designer to use for the right arrow button | | {state}.imageUp | [[dragengine:modules:dragonscript:xmlguitheme:parameters#image|Image]] | Image to use for the up arrow button | | {state}.imageDown | [[dragengine:modules:dragonscript:xmlguitheme:parameters#image|Image]] | Image to use for the down arrow button | | {state}.imageLeft | [[dragengine:modules:dragonscript:xmlguitheme:parameters#image|Image]] | Image to use for the left arrow button | | {state}.imageRight | [[dragengine:modules:dragonscript:xmlguitheme:parameters#image|Image]] | Image to use for the right arrow button | | {state}.canvasFrame | [[dragengine:modules:dragonscript:xmlguitheme:parameters#canvas_creator|CanvasCreator]] | Canvas creator to use for the scroll area frame | | {state}.canvasKnob | [[dragengine:modules:dragonscript:xmlguitheme:parameters#canvas_creator|CanvasCreator]] | Canvas creator to use for the scroll area knob | | {state}.paddingKnobFrame | [[dragengine:modules:dragonscript:xmlguitheme:parameters#bordersize|BorderSize]] | Padding between scroll area knob and frame |