Cleanups.

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

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
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
radically different from the default UI theme of the engine:
.. figure:: img/tank-kings-by-winterpixel-games.png)
:align: center
![](img/tank-kings-by-winterpixel-games.png)
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
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
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
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
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
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
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,
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
`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
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,
including this control's children.
.. figure:: img/themecheck.png)
:align: center
![](img/themecheck.png)
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
@ -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
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
data type will be returned.
Beyond controls
---------------
## Beyond controls
Naturally, themes are an ideal type of resource for storing configuration for
something visual. While the support for theming is built into control nodes,

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
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
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
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
select **New Theme**.
.. figure:: img/new_theme.png)
:align: center
![](img/new_theme.png)
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
@ -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`
and icons — they open for editing in the Inspector.
.. figure:: img/default_font.png)
:align: center
![](img/default_font.png)
Theme editor overview
---------------------
## Theme editor overview
.. figure:: img/theme_editor.png)
:align: center
![](img/theme_editor.png)
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
@ -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
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**
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.
.. figure:: img/default_preview.png)
:align: center
![](img/default_preview.png)
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
click the **Add Preview** button and select the saved scene from your file system.
.. figure:: img/scene_preview.png)
:align: center
![](img/scene_preview.png)
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.
@ -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
control opens it for editing on the right-hand side.
.. figure:: img/theme_preview_picker.png)
:align: center
![](img/theme_preview_picker.png)
Theme types and items
~~~~~~~~~~~~~~~~~~~~~
### Theme types and items
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
@ -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
are displayed.
.. figure:: img/theme_type_editor.png)
:align: center
![](img/theme_type_editor.png)
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
@ -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
edited in the Inspector dock instead.
.. figure:: img/theme_item_inspector.png)
:align: center
![](img/theme_item_inspector.png)
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
@ -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
same time.
.. figure:: img/theme_pin_the_stylebox.png)
:align: center
![](img/theme_pin_the_stylebox.png)
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.
@ -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
nodes.
.. figure:: img/add_item_type.png)
:align: center
![](img/add_item_type.png)
Manage and import items
-----------------------
## Manage and import items
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 theme items of the selected type.
.. figure:: img/manage_items.png)
:align: center
![](img/manage_items.png)
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
@ -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,
creating a template of a theme in a way.
.. figure:: img/import_items.png)
:align: center
![](img/import_items.png)

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
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
each individual UI element.
.. figure:: img/themecheck.png)
:align: center
![](img/themecheck.png)
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`
@ -37,8 +35,7 @@ Note:
theme is better described in the `Customizing a project doc_gui_theme_in_project )`
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
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
and screwdriver icon.
.. figure:: img/base_type.png)
:align: center
![](img/base_type.png)
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).
@ -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
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.
In the inspector dock, under the **Theme** property of a control node,