Relintai/pandemonium_engine_docs
1
0
Fork 0
mirror of https://github.com/Relintai/pandemonium_engine_docs.git synced 2025-01-06 15:00:03 +01:00
Code Issues Packages Projects Releases Wiki Activity

Cleanups.

Browse Source
This commit is contained in:
Relintai 2024-04-27 14:22:20 +02:00
parent 525c3dbbdc
commit 80d98eb678
3 changed files with 33 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
03_usage/04_ui/skinning_and_themes/01_gui_skinning.md
View File

@ -1,7 +1,6 @@
Introduction to GUI skinning # Introduction to GUI skinning
============================
It is essential for a game to provide clear, informative, and yet visually It is essential for a game to provide clear, informative, and yet visually
pleasing user interface to its players. While `Control` pleasing user interface to its players. While `Control`
@ -13,10 +12,9 @@ the look of every control in your user interface, including your custom controls
Here is an example of this system in action — a game with the GUI that is Here is an example of this system in action — a game with the GUI that is
radically different from the default UI theme of the engine: radically different from the default UI theme of the engine:
.. figure:: img/tank-kings-by-winterpixel-games.png) ![](img/tank-kings-by-winterpixel-games.png)
:align: center
A "Gear Up!" screen in Tank Kings, courtesy of Winterpixel Games A "Gear Up!" screen in Tank Kings, courtesy of Winterpixel Games
Beyond achieving a unique look for your game, this system also enables developers Beyond achieving a unique look for your game, this system also enables developers
to provide customization options to the end users, including accessibility settings. to provide customization options to the end users, including accessibility settings.
@ -27,8 +25,7 @@ Of course this system can also be used for gameplay purposes: your hero-based ga
can change its style for the selected player character, or you can give different can change its style for the selected player character, or you can give different
flavors to the sides in your team-based project. flavors to the sides in your team-based project.
Basics of themes ## Basics of themes
----------------
The skinning system is driven by the `Theme` resource. Every The skinning system is driven by the `Theme` resource. Every
Pandemonium project has an inherent default theme that contains the settings used by Pandemonium project has an inherent default theme that contains the settings used by
@ -45,8 +42,7 @@ Note:
of the default one. In principle, this works exactly like it would in your game of the default one. In principle, this works exactly like it would in your game
as explained `below doc_gui_theme_in_project )`. as explained `below doc_gui_theme_in_project )`.
Theme items ### Theme items
~~~~~~~~~~~
The configuration that is stored in a theme consists of theme items. Each item has The configuration that is stored in a theme consists of theme items. Each item has
a unique name and must be one of the following data types: a unique name and must be one of the following data types:
@ -82,8 +78,7 @@ a unique name and must be one of the following data types:
not limited to the `Panel` control, as styleboxes not limited to the `Panel` control, as styleboxes
are used by many controls for their backgrounds and overlays. are used by many controls for their backgrounds and overlays.
Theme types ### Theme types
~~~~~~~~~~~
To help with the organization of its items each theme is separated into types, To help with the organization of its items each theme is separated into types,
and each item must belong to a single type. In other words, each theme item and each item must belong to a single type. In other words, each theme item
@ -144,8 +139,7 @@ Warning:
You can learn more about creating and using theme type variations in a You can learn more about creating and using theme type variations in a
`dedicated article doc_gui_theme_type_variations )`. `dedicated article doc_gui_theme_type_variations )`.
Customizing a control ## Customizing a control
---------------------
Each control node can be customized directly without the use of themes. This Each control node can be customized directly without the use of themes. This
is called local overrides. Every theme property from the control's class is called local overrides. Every theme property from the control's class
@ -154,8 +148,7 @@ the Inspector dock, or scripts. This allows to make granular changes to a
particular part of the UI, while not affecting anything else in the project, particular part of the UI, while not affecting anything else in the project,
including this control's children. including this control's children.
.. figure:: img/themecheck.png) ![](img/themecheck.png)
:align: center
Local overrides are less useful for the visual flair of your user interface, Local overrides are less useful for the visual flair of your user interface,
especially if you aim for consistency. However, for layout nodes these are especially if you aim for consistency. However, for layout nodes these are
@ -169,8 +162,7 @@ it uses. Values provided by the theme are ignored.
Customizing a project ## Customizing a project
---------------------
Out of the box each project adopts the default project theme provided by Pandemonium. The Out of the box each project adopts the default project theme provided by Pandemonium. The
default theme itself is constant and cannot be changed, but its items can be overridden default theme itself is constant and cannot be changed, but its items can be overridden
@ -224,8 +216,7 @@ like this:
Even if the item doesn't exist in any theme, a corresponding default value for that Even if the item doesn't exist in any theme, a corresponding default value for that
data type will be returned. data type will be returned.
Beyond controls ## Beyond controls
---------------
Naturally, themes are an ideal type of resource for storing configuration for Naturally, themes are an ideal type of resource for storing configuration for
something visual. While the support for theming is built into control nodes, something visual. While the support for theming is built into control nodes,

54
03_usage/04_ui/skinning_and_themes/02_gui_using_theme_editor.md
View File

@ -1,7 +1,6 @@
Using the theme editor # Using the theme editor
======================
This articles explains how to create and manage UI themes using the Pandemonium This articles explains how to create and manage UI themes using the Pandemonium
editor and its theme editor tool. We recommend getting familiar with the editor and its theme editor tool. We recommend getting familiar with the
@ -13,8 +12,7 @@ the necessary UI for adding, removing, and adjusting theme types and theme
items. It features a preview section for testing your changes live, as well items. It features a preview section for testing your changes live, as well
as a window dialog for doing bulk operations of the theme items. as a window dialog for doing bulk operations of the theme items.
Creating a theme ## Creating a theme
----------------
Like any other resources, themes can be created directly in the file system dock Like any other resources, themes can be created directly in the file system dock
by right-clicking and selecting **New Resource...**, then selecting **Theme** by right-clicking and selecting **New Resource...**, then selecting **Theme**
@ -25,8 +23,7 @@ Themes also can be created from any control node. Select a control node in the s
hierarchy, then in the inspector go to the `theme` property. From there you can hierarchy, then in the inspector go to the `theme` property. From there you can
select **New Theme**. select **New Theme**.
.. figure:: img/new_theme.png) ![](img/new_theme.png)
:align: center
This will create an empty theme and open up the theme editor. Keep in mind that This will create an empty theme and open up the theme editor. Keep in mind that
resources created this way are bundled with the scene by default. Use the context resources created this way are bundled with the scene by default. Use the context
@ -37,14 +34,11 @@ include the default, fallback font that you can edit only using the Inspector do
Same applies to the contents of complex resource types, such as `StyleBoxes` Same applies to the contents of complex resource types, such as `StyleBoxes`
and icons — they open for editing in the Inspector. and icons — they open for editing in the Inspector.
.. figure:: img/default_font.png) ![](img/default_font.png)
:align: center
Theme editor overview ## Theme editor overview
---------------------
.. figure:: img/theme_editor.png) ![](img/theme_editor.png)
:align: center
The theme editor has two main parts. The main theme editor, located at the bottom of The theme editor has two main parts. The main theme editor, located at the bottom of
the Pandemonium editor, aims to provide users with tools to quickly create, edit, and delete the Pandemonium editor, aims to provide users with tools to quickly create, edit, and delete
@ -53,22 +47,19 @@ the underlying theme concepts. The **Manage Theme Items** dialog, on the other h
tries to address the needs of those who want to change themes manually. It's also tries to address the needs of those who want to change themes manually. It's also
useful for creating a new editor theme. useful for creating a new editor theme.
Theme previews ### Theme previews
~~~~~~~~~~~~~~
The left-hand side of the main editor has a set of preview tabs. The **Default Preview** The left-hand side of the main editor has a set of preview tabs. The **Default Preview**
tab is visible out of the box and contains most of the frequently used controls in various tab is visible out of the box and contains most of the frequently used controls in various
states. Previews are interactive, so intermediate states (e.g. hover) can be previewed as well. states. Previews are interactive, so intermediate states (e.g. hover) can be previewed as well.
.. figure:: img/default_preview.png) ![](img/default_preview.png)
:align: center
Additional tabs can be created from arbitrary scenes in your project. The scene Additional tabs can be created from arbitrary scenes in your project. The scene
must have a control node as its root to function as a preview. To add a new tab must have a control node as its root to function as a preview. To add a new tab
click the **Add Preview** button and select the saved scene from your file system. click the **Add Preview** button and select the saved scene from your file system.
.. figure:: img/scene_preview.png) ![](img/scene_preview.png)
:align: center
If you make changes to the scene, they will not be reflected in the preview If you make changes to the scene, they will not be reflected in the preview
automatically. To update the preview click the reload button on the toolbar. automatically. To update the preview click the reload button on the toolbar.
@ -78,11 +69,9 @@ picker tool from the toolbar and hover over the preview area to highlight contro
nodes. Highlighted control nodes display their class name. Clicking on the highlighted nodes. Highlighted control nodes display their class name. Clicking on the highlighted
control opens it for editing on the right-hand side. control opens it for editing on the right-hand side.
.. figure:: img/theme_preview_picker.png) ![](img/theme_preview_picker.png)
:align: center
Theme types and items ### Theme types and items
~~~~~~~~~~~~~~~~~~~~~
The right-hand side of the theme editor provides a list of theme types available The right-hand side of the theme editor provides a list of theme types available
in the edited theme resource, and the contents of the selected type. The list of in the edited theme resource, and the contents of the selected type. The list of
@ -92,8 +81,7 @@ enabled, then for each built-in type its default theme values are displayed, gre
out. If the option is disabled, only the items available in the edited theme itself out. If the option is disabled, only the items available in the edited theme itself
are displayed. are displayed.
.. figure:: img/theme_type_editor.png) ![](img/theme_type_editor.png)
:align: center
Individual items from the default theme can be added to the current theme by Individual items from the default theme can be added to the current theme by
clicking on the **Override** button next to the item. You can also override all clicking on the **Override** button next to the item. You can also override all
@ -106,8 +94,7 @@ Overridden theme items can be edited directly in the right-hand panel, unless th
are resources. Resources have rudimentary controls available for them, but must be are resources. Resources have rudimentary controls available for them, but must be
edited in the Inspector dock instead. edited in the Inspector dock instead.
.. figure:: img/theme_item_inspector.png) ![](img/theme_item_inspector.png)
:align: center
Styleboxes have an unique feature available, where you can pin an individual Styleboxes have an unique feature available, where you can pin an individual
stylebox from the list. Pinned stylebox acts like the leader of the pack, and stylebox from the list. Pinned stylebox acts like the leader of the pack, and
@ -115,8 +102,7 @@ all styleboxes of the same type are updated alongside it when you change its
properties. This allows you to edit properties of several styleboxes at the properties. This allows you to edit properties of several styleboxes at the
same time. same time.
.. figure:: img/theme_pin_the_stylebox.png) ![](img/theme_pin_the_stylebox.png)
:align: center
While theme types can be picked from a preview, they can also be added manually. While theme types can be picked from a preview, they can also be added manually.
Clicking the plus button next to the type list opens the **Add item Type** menu. Clicking the plus button next to the type list opens the **Add item Type** menu.
@ -124,18 +110,15 @@ In that menu you can either select a type from the list, or you can enter an
arbitrary name to create a custom type. Text field also filters the list of control arbitrary name to create a custom type. Text field also filters the list of control
nodes. nodes.
.. figure:: img/add_item_type.png) ![](img/add_item_type.png)
:align: center
Manage and import items ## Manage and import items
-----------------------
Clicking the **Manage Items** button brings up the **Manage Theme Items** dialog. In Clicking the **Manage Items** button brings up the **Manage Theme Items** dialog. In
the **Edit Items** tab you can view and add theme types, as well as view and edit the **Edit Items** tab you can view and add theme types, as well as view and edit
the theme items of the selected type. the theme items of the selected type.
.. figure:: img/manage_items.png) ![](img/manage_items.png)
:align: center
You can create, rename and remove individual theme items here by clicking the You can create, rename and remove individual theme items here by clicking the
corresponding **Add X Item** and specifying their name. You can also mass delete corresponding **Add X Item** and specifying their name. You can also mass delete
@ -154,5 +137,4 @@ include the data will copy all theme items as they are to your theme. Omitting t
will create the items of the corresponding data type and name, but will leave them empty, will create the items of the corresponding data type and name, but will leave them empty,
creating a template of a theme in a way. creating a template of a theme in a way.
.. figure:: img/import_items.png) ![](img/import_items.png)
:align: center

15
03_usage/04_ui/skinning_and_themes/03_gui_theme_type_variations.md
View File

@ -1,15 +1,13 @@
Theme type variations # Theme type variations
=====================
When designing a user interface there may be times when a `Control` node When designing a user interface there may be times when a `Control` node
needs to have a different look than what is normally defined by a `Theme`. needs to have a different look than what is normally defined by a `Theme`.
Every control node has theme property overrides, which allow you to redefine the styling for Every control node has theme property overrides, which allow you to redefine the styling for
each individual UI element. each individual UI element.
.. figure:: img/themecheck.png) ![](img/themecheck.png)
:align: center
This approach quickly becomes hard to manage, if you need to share the same custom look This approach quickly becomes hard to manage, if you need to share the same custom look
between several controls. Imagine that you use gray, blue, and red variants of `Button` between several controls. Imagine that you use gray, blue, and red variants of `Button`
@ -37,8 +35,7 @@ Note:
theme is better described in the `Customizing a project doc_gui_theme_in_project )` theme is better described in the `Customizing a project doc_gui_theme_in_project )`
section of the "Introduction to GUI skinning" article. section of the "Introduction to GUI skinning" article.
Creating a type variation ## Creating a type variation
-------------------------
To create a type variation open the theme editor, then click the plus icon To create a type variation open the theme editor, then click the plus icon
next to the **Type** dropdown on the right side of the editor. Type in what next to the **Type** dropdown on the right side of the editor. Type in what
@ -47,8 +44,7 @@ you want to name your theme type variation in the text box, then click **Add Typ
Below the **Type** dropdown are the property tabs. Switch to the tab with a wrench Below the **Type** dropdown are the property tabs. Switch to the tab with a wrench
and screwdriver icon. and screwdriver icon.
.. figure:: img/base_type.png) ![](img/base_type.png)
:align: center
Click on the plus icon next to the **Base Type** field. You can select the base type Click on the plus icon next to the **Base Type** field. You can select the base type
there, which would typically be the name of a control node class (e.g., `Button`, `Label`, etc). there, which would typically be the name of a control node class (e.g., `Button`, `Label`, etc).
@ -59,8 +55,7 @@ inherits styles from `Button` because corresponding node types extend each other
After you select the base type, you should now be able to see its properties on the other After you select the base type, you should now be able to see its properties on the other
tabs in the theme editor. You can edit them as usual. tabs in the theme editor. You can edit them as usual.
Using a type variation ## Using a type variation
----------------------
Now that a type variation has been created you can apply it to your nodes. Now that a type variation has been created you can apply it to your nodes.
In the inspector dock, under the **Theme** property of a control node, In the inspector dock, under the **Theme** property of a control node,