[[:start|Start Page]] >> [[dragengine:modules:dragonscript:main|DragonScript Scripting Language]] >> [[dragengine:modules:dragonscript:guitheme|Gui Themes]] >> **Define XML Gui Theme** ====== Basic Format ====== 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: ====== Widget Designers ====== 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 [[dragengine:modules:dragonscript:xmlguitheme:widgetdesigner|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. 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 * 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. ====== Named Gui Themes ====== 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. //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. ====== Importing ====== 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: sharedDefintions.guitheme.xml