XML Gui Theme files typically have the file extension *.guitheme.xml. Gui Themes can be defined from scratch or based on an existing gui theme. To extend an existing gui theme file use the extend=“base.guitheme.xml” attribute. These are the two basic file contents:

<?xml version='1.0' encoding='ISO-8859-1'?>
<guiTheme>
   <!-- A brand new gui theme to be defined from scratch. -->
   <designer name='Desktop' type='Desktop'>
      <!-- content... -->
   </designer>
</guiTheme>

<?xml version='1.0' encoding='ISO-8859-1'?>
<guiTheme extend='/shareddata/guithemes/modern/modern.guitheme.xml'>
   <!-- Modify the DragonScript module provided modern gui theme with your own customizations. -->
   <designer name='Desktop' type='Desktop'>
      <!-- content... -->
   </designer>
</guiTheme>

Gui Theme XML files contain usually only designer tags defining widget designers. You can use any number of designer tags with designers defined later in the document overwriting those defined earlier. You can use different ways to define widget designers. You can create a designer from a Prototype provided by the game scripts. You can load designers from a *.wdesigner.xml file. Or you can modify a previously defined widget designer by name. See Define XML Widget Designer for the content you can use in those tags. The examples below show the three ways to define a widget designer. By default widget designers are shared. As soon as you add a modification the XML Loader creates a copy of the widget designer and applies the changes. This keeps loading times and memory consumption low.

<!-- Create a new widget designer using a Prototype named 'Desktop' provided by the game scripts. -->
<designer name='MyDesigner' type='Desktop'>
   <!-- content... -->
</designer>
 
<!-- Load widget designer from XML file and modify it with the content in the tag. -->
<designer name='MyDesigner2' extend='mydesigner.wdesigner.xml'>
   <!-- content... -->
</designer>
 
<!-- Modify a previously defined widget designer by name. -->
<designer name='MyDesigner3' extendNamed='MyDesigner'>
   <!-- content... -->
</designer>

Widget designers are selected using the setDesignerSelector parameter of widgets. Selectors compose of dot separated names, for example Label.MyUIComponent.SpecialVersion. The selector is matched first in its entire length against all defined widget designers. The last widget designer with the exact matching name is chosen. If no widget designer matches the last dot separated name is removed and the matching restarts. In the this example the next match attempt would be with the full name Label.MyUIComponent. If this does still not match another component is remove matching now against Label. If even this does not match no widget designer is used for the widget. In short the first matching designer from the list below is chosen:

• Label . MyUIComponent . SpecialVersion
• Label . MyUIComponent
• Label
• <nothing>

This system allows to create specializations of widgets with custom design while falling back to previous, broader definitions if missing. In this example Label is the top level designer matching all labels if nothing else applies. Using .MyUIComponent you can define a widget designer applying to all labels in a specific UI component of yours given they all have selectors set of the form Label.MyUIComponent{.XXX} where {.XXX} is optional. You can further customize individual labels in this UI component by adding yet another selector component. If the artists wants to style these labels individually he can use the full name. Otherwise he can define one of the broader upper level selectors. Hence it never hurts to have a selector component more attached if you want to give creative freedom to your artist.

Gui Themes define one set of widget designers. Sometimes it is useful to have named gui themes for individual UI parts. For example it can be simpler to use one gui theme for the main menu and another for an in-game component. You can create different gui themes for each of this situation but this requires storing and managing individual gui themes loaded from file. Using named gui themes this can be made simpler avoiding the need to manually track gui theme XML files.

Each gui theme has a list of named child gui themes. Widgets have a setThemeSelector() method. If set the widget uses not the gui theme found in the parent widget but instead picks the named child gui theme from it. Once chosen the gui theme is used as if set to the widget manually.

Named gui themes are organized in a tree. The top level gui theme has a list of child gui themes which in turn can have more child gui themes. The selector set for the widget composes of a dot separated name, for example InGame.InventoryWindow. The parent of the widget has the top level gui theme assigned. The widget then selects first the named gui theme InGame. If found it uses this gui theme to continue choosing the named gui theme InventoryWindow. This way the widget digs into the theme three picking the best gui theme it can find (meaning the last one which matches). If one gui theme along the path is not found the last found one is used.

<!-- Create named gui theme from scratch. -->
<guiTheme name='MyTheme'>
   <!-- content... -->
</guiTheme>
 
<!-- Load gui theme from XML file and modify it with the content in the tag. -->
<guiTheme name='MyTheme2' extend='mytheme.guitheme.xml'>
   <!-- content... -->
</guiTheme>
 
<!-- Modify a previously defined gui theme by name. -->
<guiTheme name='MyTheme3' extendNamed='MyTheme'>
   <!-- content... -->
</guiTheme>

setDesignerSelector() and setThemeSelector() both allow to select what widget designer to use for a widget widget but both work slightly different and have their specific use case. Using setDesignerSelector() you choose individual styles for individual widgets. Using setThemeSelector() you can use different sets of widget designers with the same name. For example If you use a designer selector Button.MyButton then you can have only one designer in your gui theme matching this name. If you use setThemeSelector() though you can have different themes for the same button. Each theme has a widget designer with the same name but depending on what theme is chosen a different designer is used. This allows to change a UI theme on-the-fly and allows easy modding with the help of named gui themes.

Parts of Gui Themes can be placed in external files to reuse definitions. This reduces typing effort and allows to better organize your gui themes. Importing works as if the tags in the referenced file are defined right instead of the import tag. This example shows how this is done:

<!-- Import definitions from XML file as if written here. -->
<import>sharedDefintions.guitheme.xml</import>