| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| dragengine:modules:dragonscript:guitheme [2018/02/26 13:18] – [Gui Themes] dragonlord | dragengine:modules:dragonscript:guitheme [2024/03/14 16:43] (current) – dragonlord |
|---|
| | {{tag>dragonscript ui theme}} |
| <WRAP youarehere> | <WRAP youarehere> |
| [[:start|Start Page]] >> [[dragengine:modules:dragonscript:main|DragonScript Scripting Language]] >> **Gui Themes** | [[:start|Start Page]] >> [[dragengine:modules:dragonscript:main|DragonScript Scripting Language]] >> **Gui Themes** |
| |
| ====== Gui Themes ====== | ====== Gui Themes ====== |
| The DragonScript module provides a Gui Toolkit based on the [[gamedev:canvassystem:introduction|canvas system]]. This is a non-mandatory implementation and can be easily replaced by a different toolkit or custom implementation. To help customize the toolkit visually and if required functionally [[http://dragengine.rptd.ch/docs/dragonscript/scriptapi/latest/interfaceDragengine_1_1Gui_1_1GuiThemes_1_1GuiTheme.html|gui themes]] are used. A gui theme defines a set of designer factories which produce designers able to design the visual aspects of certain [[http://dragengine.rptd.ch/docs/dragonscript/scriptapi/latest/classDragengine_1_1Gui_1_1Widget.html|widgets]]. A button for example consists of the [[http://dragengine.rptd.ch/docs/dragonscript/scriptapi/latest/classDragengine_1_1Gui_1_1Button.html|button widget]] defining the structure and functionality of the button and the [[http://dragengine.rptd.ch/docs/dragonscript/scriptapi/latest/interfaceDragengine_1_1Gui_1_1Designers_1_1ButtonDesigner.html|button designer]] which defines how the button is visualized on screen. Designers usually define the [[gamedev:canvassystem:canvascreators|canvas creators]] to use for a widget. For some widgets designers even create sub-widgets managing their canvas creators. Similar to canvas creators designers are created by designer factories, one for each designer type. In the case of a button this would be [[http://dragengine.rptd.ch/docs/dragonscript/scriptapi/latest/interfaceDragengine_1_1Gui_1_1Designers_1_1Factories_1_1ButtonDesignerFactory.html|button designer factories]]. This allows to define gui themes using XML files or programatically without having to know the actual designer implementation. Like canvas creators designers have a setParameter method allowing to set named parameters without needing to know the implementation. The [[http://dragengine.rptd.ch/docs/dragonscript/scriptapi/latest/classDragengine_1_1Gui_1_1Designers_1_1Factories_1_1DesignerFactories.html|designer factories]] class stored lists of named designers for all kinds of widget types. You can simply add your own designer factories to this list if you like to customize the appearance of your GUI beyond using designer parameters. You can create gui themes using script code but it is simpler to use XML files. For this purpose a ready made [[http://dragengine.rptd.ch/docs/dragonscript/scriptapi/latest/classDragengine_1_1LoadSave_1_1LoadGuiTheme.html|load xml gui theme]] class exists supporting designer factories list and customizing designers using parameters. | The DragonScript module provides a Gui Toolkit based on the [[gamedev:canvassystem:introduction|canvas system]]. This is a non-mandatory implementation and can be replaced by a different or custom toolkit implementation. To customize the toolkit visually and in some cases also functionally #@LinkApiDocDEDS2_HTML~interfaceDragengine_1_1Gui_1_1GuiThemes_1_1GuiTheme.html,gui themes~@# are used. |
| | |
| | A gui theme defines a set of widget designers which modify the design of #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1Widget.html,widgets~@# in different states. A button for example consists of the #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1Button.html,button widget~@# defining the structure and functionality of the button and the #@LinkApiDocDEDS2_HTML~interfaceDragengine_1_1Gui_1_1Designers_1_1ButtonDesigner.html,button designer~@# which defines how the button looks like in all used button states. |
| | |
| | Designers usually use [[gamedev:canvassystem:canvascreators|canvas creators]] to set the background, border or decoration design of widgets. For some widgets designers even create sub-widgets managing using their own widget designer. Designers are shared across gui themes and other designers to improve loading speed and reducing memory consumption. For this reason widget designers can be duplicated using the copyDesigner method. |
| | |
| | You rarely need to modify the gui theme content by yourself. You fully define gui themes using XML files. Widget designers are configured in XML files by defining named parameters. The #@LinkApiDocDEDS2_HTML~classDragengine_1_1Gui_1_1Designers_1_1WidgetDesigners.html,widget designers~@# class stores a lists of named designers used as templates . You can add your own designer template to this list if you like. You can create gui themes using script code but it highly recommended to use XML files. It makes the life of your artists much simpler. To load XML files use #@LinkApiDocDEDS2_HTML~classDragengine_1_1LoadSave_1_1LoadGuiTheme.html,load gui theme~@# class. #@LinkApiDocDEDS2_HTML~classDragengine_1_1LoadSave_1_1Loaders.html,Loaders~@# provides a ready to use gui theme loader. |
| | |
| | The example below shows an example usage. |
| |
| <code> | <code> |
| // keep in mind the guiTheme you receive is shared. Do not change the received guitheme | // keep in mind the guiTheme you receive is shared. Do not change the received guitheme |
| var GuiTheme guiTheme = loadGuiTheme.loadFromFile("/guithemes/fancy.guitheme.xml") | var GuiTheme guiTheme = loadGuiTheme.loadFromFile("/guithemes/fancy.guitheme.xml") |
| | </code> |
| |
| // still if you need to change the gui theme create first a copy and apply the changes. keep in | The example below shows how a gui theme is manually modified. This is rarely what you want or need. XML loading is recommended any time. |
| | <code> |
| | // if you need to change the gui theme create first a copy and apply the changes. keep in |
| // mind that all designers inside the gui theme are shared too. hence if you need to modify a | // mind that all designers inside the gui theme are shared too. hence if you need to modify a |
| // designer create a copy, apply the changes then assign it back to your gui theme copy. in | // designer create a copy, apply the changes then assign it back to your gui theme copy. in |
| This is an example of the ready to use modern gui theme included in the DragonScript module. | This is an example of the ready to use modern gui theme included in the DragonScript module. |
| <WRAP center box 600px> | <WRAP center box 600px> |
| {{ :dragengine:modules:dragonscript:guitheme.png |Moden gui theme example}} | {{ :dragengine:modules:dragonscript:guitheming.png |XML Gui Theme Example}} |
| <WRAP centeralign>Moden gui theme example.</WRAP> | <WRAP centeralign>XML Gui Theme Example.</WRAP> |
| </WRAP> | </WRAP> |
| | |
| | ====== XML Gui Themeing ====== |
| | These topic help to create a valid Gui Theme XML files. You can take a look at the //modern.guitheme.xml// file located in the shared data directory. Under Unix you can find this for example under // /usr/share/dragengine/modules/scripting/dragonscript/1.0/data/guithemes/modern //. You can load this gui theme in your project using the in-game path // /shareddata/guithemes/modern/modern.guitheme.xml //. This is present for all projects using the DragonScript module. It's recommended to go through the list from top to bottom. |
| | |
| | * [[dragengine:modules:dragonscript:xmlguitheme:guitheme|Define XML Gui Theme (*.guitheme.xml)]] |
| | * [[dragengine:modules:dragonscript:xmlguitheme:widgetdesigner|Define XML Widget Designer]] |
| | * [[dragengine:modules:dragonscript:xmlguitheme:parameters|Defining Parameters]] |
| | * [[dragengine:modules:dragonscript:xmlguitheme:canvascreator|Define XML Canvas Creator]] |
| | * [[dragengine:modules:dragonscript:xmlguitheme:borderfactory|Define XML Border Factory]] |
| | * [[dragengine:modules:dragonscript:xmlguitheme:decoration|Define XML Decoration]] |
| | * [[dragengine:modules:dragonscript:xmlguitheme:mousepointer|Define XML Mouse Pointer]] |
| |
