diff --git a/development/editor/introduction_to_editor_development.rst b/development/editor/introduction_to_editor_development.rst index 7694a169fa7..892bc489667 100644 --- a/development/editor/introduction_to_editor_development.rst +++ b/development/editor/introduction_to_editor_development.rst @@ -22,7 +22,7 @@ Technical choices ----------------- The Godot editor is drawn using Godot's renderer and -:ref:`UI system `. It does *not* rely on a toolkit +:ref:`UI system `. It does *not* rely on a toolkit such as GTK or Qt. This is similar in spirit to software like Blender. While using toolkits makes it easier to achieve a "native" appearance, they are also quite heavy and their licensing is not compatible with Godot's. diff --git a/tutorials/ui/gui_skinning.rst b/tutorials/ui/gui_skinning.rst index e2f2dcf5738..74c1c35a67c 100644 --- a/tutorials/ui/gui_skinning.rst +++ b/tutorials/ui/gui_skinning.rst @@ -1,183 +1,241 @@ .. _doc_gui_skinning: -GUI skinning -============ - -Themes ------- - -All control nodes are skinned through the :ref:`Theme ` -resource. Theme contains all the information required to change the -entire visual styling of all controls. - -A Theme can be applied to any control node in the scene. As a result, -all children and grand-children controls will use that same theme, too -(unless another theme is specified further down the tree). If a value is -not found in a theme, it will be searched in themes higher up in the -hierarchy, towards the root. If nothing was found, the default theme is -used. This system allows for flexible overriding of themes in complex -user interfaces. - -.. attention:: - - Don't use the custom theme option in the Project Settings, as there - are known bugs with theme propagation. Instead, apply your theme to the - root Control node's Theme property. It will propagate to instanced scenes - automatically. To get correct theming in the editor for instanced scenes, - you can apply the theme resource to the instanced scene's root node as well. - -Creating a theme +Introduction to GUI skinning +============================ + +It is essential for a game to provide clear, informative, and yet visually +pleasing user interface to its players. While :ref:`Control ` +nodes come with a decently functional look out of the box, there is always +room for uniqueness and case-specific tuning. For this purpose Godot engine +includes a system for GUI skinning (or theming), which allows you to customize +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 + + 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. +UI themes are applied in a cascading manner (i.e. they propagate from parent +controls to their children), which means that font settings or adjustments for +colorblind users can be applied in a single place and affect the entire UI tree. +Of course this system can also be used for gameplay purposes: your hero-based game +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 ---------------- -Themes can be created from any control node. Select a control node in the scene -hierarchy, then in the inspector go to the theme property. From there you can -select **New Theme**. +The skinning system is driven by the :ref:`Theme ` resource. Every +Godot project has an inherent default theme that contains the settings used by +the built-in control nodes. This is what gives the controls their distinct look +out of the box. A theme only describes the configuration, however, and it is still +the job of each individual control to use that configuration in the way it requires +to display itself. This is important to remember when implementing +:ref:`your own custom controls `. -.. image:: img/new_theme.png - -This will create an empty theme and open up the theme editor. - -.. image:: img/theme_editor.png - -In the theme editor you can customize everything about a theme except for -the default font the theme uses. That can only be customized in the inspector under -the selected theme. - -.. image:: img/default_font.png +.. note:: + Even the Godot editor itself relies on the default theme. But it doesn't look the + same as a Godot project, because it applies its own heavily customized theme on top + of the default one. In principle, this works exactly like it would in your game + as explained :ref:`below `. Theme items ------------ - -In the theme editor, next to the default preview window, is where you make changes -to your theme. Clicking the plus button opens the **Add item Type** menu. - -.. image:: img/add_item_type.png +~~~~~~~~~~~ -From here select the control node you want your theme to modify and click **Ok**. You -should now see theme items for that node in the theme editor. Theme items are what defines -the look of a theme, each kind of item in a theme can be: +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: -- **Color**: A single color, with or without transparency. Colors are - usually applied to fonts and icons. -- **Constant**: A single numerical constant. Generally used - to define spacing between components or alignment. -- **Font**: Every control that uses text can be assigned the fonts - used to draw strings. -- **Icon**: A single image. Textures are not often used, but when - they are, they represent handles to pick or icons in a complex control - (such as a file dialog). -- **StyleBox**: Stylebox is a resource that defines how to draw a - panel in varying sizes (more information on them later). +- **Color** -Every item is associated with: + A :ref:`color ` value, which is often used for fonts + and backgrounds. Colors can also be used for modulation of controls + and icons. -- A name (the name of the item) -- A Control (the name of the control) +- **Constant** -To customize a theme item click on the plus sign next to it. Your theme -will now override the default theme for that item. To modify it click on **Empty**, -then select the new theme item you want to create. Click on it again and you can -now modify it in the inspector. + An integer value, which can be used either for numeric properties of + controls (such as the item separation in a :ref:`BoxContainer `), + or for boolean flags (such as the drawing of relationship lines in a :ref:`Tree `). -.. image:: img/theme_item_inspector.png +- **Font** -You can also add custom theme items to a control node under the built in theme items. + A :ref:`font ` resource, which is used by controls that + display text. Fonts contain most text rendering settings, except for + its size and color. On top of that, alignment and text direction are + controlled by individual controls. -In the theme editor, above the theme items, is the **Show Default** toggle. It will hide -or show any theme items that are using the default theme settings. Next to it is the -**Override Defaults** button, which will override the default theme for all theme items -of the currently selected control node. +- **Font size** -Manage theme Items ------------------- + An integer value, which is used alongside a font to determine the + size at which the text should be displayed. -Clicking the **Manage Items** button brings up the Manage theme items menu. In -the edit items tab you can view all the theme items for your theme, add a custom -theme item, or a custom control node type. +- **Icon** -.. image:: img/manage_items.png + A :ref:`texture ` resource, which is normally used + to display an icon (on a :ref:`Button `, for example). -You can also mass delete theme items from here. **Remove Class Items** will remove -all built in theme items you have customized for the control node. **Remove Custom -Items** will remove all the custom theme items for the selected node. And **Remove -All Items** will remove everything. +- **StyleBox** -From the **Import Items** tab you can import theme items from other themes. You can -import items from the default Godot theme, the Godot editor theme, or another custom -theme. You can import all of the theme items for a control node or only one. You need -to select **Data** when importing to actually import the theme item. Otherwise your -theme will just have a blank override for that theme option. + A :ref:`StyleBox ` resource, a collection of configuration + options which define the way a UI panel should be displayed. This is + not limited to the :ref:`Panel ` control, as styleboxes + are used by many controls for their backgrounds and overlays. -.. image:: img/import_items.png +Theme types +~~~~~~~~~~~ -Preview -------- - -The **Default Preview** tab of the theme editor shows you how every control node in -Godot will look with your theme settings applied. If you haven't applied a setting -then the default theme setting will be used. - -.. image:: img/default_preview.png - -You can also preview how other scenes will look by clicking the **Add Preview** button -and selecting a tscn file that has a control node as the root node. - -.. image:: img/scene_preview.png - -Theme overrides ---------------- +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 +is defined by its name, its data type and its theme type. This combination +must be unique within the theme. For example, there cannot be two color items named +``font_color`` in a type called ``Label``, but there can be another ``font_color`` +item in a type ``LineEdit``. -If only a few controls need to be skinned, it is often not necessary to -create a new theme. Controls offer their theme items as special kinds -of properties. If checked, overriding will take place: +The default Godot theme comes with multiple theme types already defined, +one for every built-in control node that uses UI skinning. The example above +contains actual theme items present in the default theme. You can refer to the +**Theme Properties** section in the class reference for each control to see +which items are available to it and its child classes. -.. image:: img/themecheck.png +.. note:: + Child classes can use theme items defined for their parent class (``Button`` + and its derivatives being a good example of that). In fact, every control can + use every theme item of any theme type, if it needs to (but for the clarity and + predictability we try to avoid that in the engine). -As can be seen in the image above, theme items have little check boxes. -If checked, they can be used to override the value of the theme just for -that control. + It is important to remember that for child classes that process is automated. + Whenever a built-in control requests a theme item from the theme it can omit + the theme type, and its class name will be used instead. On top of that, + the class names of its parent classes will also be used in turn. This allows + changes to the parent class, such as ``Button``, to affect all derived + classes without the need to customize every one of them. -Changing themes with code -------------------------- - -In addition to the theme editor it is possible to change theme items with -code, here is an example: +You can also define your own theme types, and additionally customize both built-in +controls and your own controls. Because built-in controls have no knowledge of +your custom theme types, you must utilize scripts to access those items. All control +nodes have several methods that allow to fetch theme items from the theme that +is applied to them. Those methods accept the theme type as one of the arguments. .. tabs:: - .. code-tab:: gdscript GDScript - - var theme = Theme.new() - theme.set_color("font_color", "Label", Color.red) + .. code-tab:: gdscript - var label = Label.new() - label.theme = theme + var accent_color = get_theme_color("accent_color", "MyType") + label.add_color_override("font_color", accent_color) .. code-tab:: csharp - var theme = new Theme(); - theme.SetColor("fontColor", "Label", new Color(1.0f, 0.0f, 0.0f)); - - var label = new Label(); - label.Theme = theme; - -In the example above, a new theme is created. The "font_color" option -is changed and then applied to a label. Therefore, the label's text (and all -children and grandchildren labels) will be red. - -It is possible to override those options without using the theme -directly, and only for a specific control, by using the override API in -:ref:`Control.add_color_override() `: - -.. tabs:: - .. code-tab:: gdscript GDScript - - var label = Label.new() - label.add_color_override("font_color", Color.red) - - .. code-tab:: csharp + Color accentColor = GetThemeColor("accent_color", "MyType"); + label.AddColorOverride("font_color", accentColor); + +To give more customization opportunities types can also be linked together as +type variations. This is another use-case for custom theme types. For example, +a theme can contain a type ``Header`` which can be marked as a variation of +the base ``Label`` type. An individual ``Label`` control can then be set to +use the ``Header`` variation for its type, and every time a theme item is +requested from a theme this variation will be used before any other type. This +allows to store various presets of theme items for the same class of the +control node in the single ``Theme`` resource. + +.. warning:: + Only variations available from the default theme or defined in the custom + project theme are shown in the Inspector dock as options. You can still + input manually the name of a variation that is defined outside of those + two places, but it is recommended to keep all variations to the project theme. + +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 +reference can be overridden directly on the control itself, using either +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 + +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 +essential. Nodes such as :ref:`BoxContainer ` and +:ref:`GridContainer ` use theme constants for defining +separation between their children, and :ref:`MarginContainer ` +stores its customizable margins in its theme items. + +Whenever a control has a local theme item override, this is the value that +it uses. Values provided by the theme are ignored. + +.. _doc_gui_theme_in_project: + +Customizing a project +--------------------- + +Out of the box each project adopts the default project theme provided by Godot. The +default theme itself is constant and cannot be changed, but its items can be overridden +with a custom theme. Custom themes can be applied in two ways: as a project setting, +and as a node property throughout the tree of control nodes. + +There are two project settings that can be adjusted to affect your entire project: +:ref:`gui/theme/custom` allows you to +set a custom project-wide theme, and :ref:`gui/theme/custom_font` +does the same to the default fallback font. When a theme item is requested by a control +node the custom project theme, if present, is checked first. Only if it doesn't have +the item the default theme is checked. + +This allows you to configure the default look of every Godot control with a single +theme resource, but you can go more granular than that. Every control node also has +a :ref:`theme ` property, which allows you to set a +custom theme for the branch of nodes starting with that control. This means that the +control and all of its children, and their children in turn, would first check that +custom theme resource before falling back on the project and the default themes. + +.. note:: + Instead of changing the project setting you can set the custom theme resource to the + root-most control node of your entire UI branch to almost the same effect. While in the + running project it will behave as expected, individual scenes will still display + using the default theme when previewing or running them directly. To fix that you + can set the same theme resource to the root control of each individual scene. + +For example, you can have a certain style for buttons in your project theme, but want +a different look for buttons inside of a popup dialog. You can set a custom theme +resource to the root control of your popup and define a different style for buttons +within that resource. As long as the chain of control nodes between the root of +the popup and the buttons is uninterrupted, those buttons will use the styles defined +in the theme resource that is closest to them. All other controls will still be styled +using the project-wide theme and the default theme styles. + +To sum it up, for an arbitrary control its theme item lookup would look something +like this: + +#. Check for local overrides of the same data type and name. +#. Using control's type variation, class name and parent class names: + + a. Check every control starting from itself and see if it has a theme property set; + b. If it does, check that theme for the matching item of the same name, data and theme type; + c. If there is no custom theme or it doesn't have the item, move to the parent control; + d. Repeat steps a-c. until the root of the tree is reached, or a non-control node is reached. + +#. Using control's type variation, class name and parent class names check the project-wide theme, if it's present. +#. Using control's type variation, class name and parent class names check the default theme. + +Even if the item doesn't exist in any theme, a corresponding default value for that +data type will be returned. + +Beyond controls +--------------- - var label = new Label(); - label.AddColorOverride("fontColor", new Color(1.0f, 0.0f, 0.0f)); +Naturally, themes are an ideal type of resource for storing configuration for +something visual. While the support for theming is built into control nodes, +other nodes can use them as well, just like any other resource. -In the inline help of Godot (in the Script tab), you can check which theme items -are overridable, or check the :ref:`Control ` class reference. +An example of using themes for something beyond controls can be a modulation +of sprites for the same units on different teams in a strategy game. A theme +resource can define a collection of colors, and sprites (with a help from scripts) +can use those colors to draw the texture. The main benefit being that you +could make different themes using the same theme items for red, blue, and +green teams, and swap them with a single resource change. diff --git a/tutorials/ui/gui_using_theme_editor.rst b/tutorials/ui/gui_using_theme_editor.rst new file mode 100644 index 00000000000..f98945b53b0 --- /dev/null +++ b/tutorials/ui/gui_using_theme_editor.rst @@ -0,0 +1,158 @@ +.. _doc_gui_using_theme_editor: + +Using the theme editor +====================== + +This articles explains how to create and manage UI themes using the Godot +editor and its theme editor tool. We recommend getting familiar with the +basics behind GUI skinning/theming by reading :ref:`doc_gui_skinning` before starting. + +The theme editor is a bottom panel tool that activates automatically, when +a :ref:`Theme ` resource is selected for editing. It contains +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 +---------------- + +Like any other resources, themes can be created directly in the file system dock +by right-clicking and selecting **New Resource...**, then selecting **Theme** +and clicking **Create**. This is especially useful for creating project-wide +themes. + +Themes also can be created from any control node. Select a control node in the scene +hierarchy, then in the inspector go to the ``theme`` property. From there you can +select **New Theme**. + +.. figure:: img/new_theme.png + :align: center + +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 +menu to save the new theme to a file instead. + +While the theme editor provides the tools to manage theme types and items, themes also +include the default, fallback font that you can edit only using the Inspector dock. +Same applies to the contents of complex resource types, such as :ref:`StyleBoxes ` +and icons — they open for editing in the Inspector. + +.. figure:: img/default_font.png + :align: center + +Theme editor overview +--------------------- + +.. figure:: img/theme_editor.png + :align: center + +The theme editor has two main parts. The main theme editor, located at the bottom of +the Godot editor, aims to provide users with tools to quickly create, edit, and delete +theme items and types. It gives visual tools for picking and changing controls, abstracting +the underlying theme concepts. The **Manage Theme Items** dialog, on the other hand, +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 +~~~~~~~~~~~~~~ + +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 + +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 + +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. + +Previews can also be used to quickly select the theme type to edit. Select the +picker tool from the toolbar and hover over the preview area to highlight control +nodes. Highlighted control nodes display their class name, or type variation if available. +Clicking on the highlighted control opens it for editing on the right-hand side. + +.. figure:: img/theme_preview_picker.png + :align: center + +Theme types and items +~~~~~~~~~~~~~~~~~~~~~ + +The right-hand side of them theme editor provides a list of theme types available +in the edited theme resource, and the contents of the selected type. The list of +type's items is divided into several tabs, corresponding to each data type available +in the theme (colors, constants, styles, etc.). If the **Show Default** option is +enabled, then for each built-in type its default theme values are displayed, greyed +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 + +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 +the default items of the selected theme type by clicking on the **Override All** +button. Overridden properties can then be removed with the **Remove Item** button. +Properties can also be renamed using the **Rename Item** button, and completely +custom properties can be added to the list using the text field below it. + +Overridden theme items can be edited directly in the right-hand panel, unless they +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 + +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 +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 + +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. +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 + +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 + +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 +theme items either by their data type (using the brush icon in the list) or by +their quality. **Remove Class Items** will remove all built-in theme items you +have customized for a control node type. **Remove Custom Items** will remove all +the custom theme items for the selected type. Finally, **Remove All Items** will +remove everything from the type. + +From the **Import Items** tab you can import theme items from other themes. You can +import items from the default Godot theme, the Godot editor theme, or another custom +theme. You can import individual or multiple items, and you can decide whether to +copy or omit their data as well. There are several way you can select and deselect the +items, including by hand, by hierarchy, by data type, and everything. Opting to +include the data will copy all theme items as they are to your theme. Omitting the data +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 diff --git a/tutorials/ui/img/tank-kings-by-winterpixel-games.png b/tutorials/ui/img/tank-kings-by-winterpixel-games.png new file mode 100644 index 00000000000..dfd7b084ff3 Binary files /dev/null and b/tutorials/ui/img/tank-kings-by-winterpixel-games.png differ diff --git a/tutorials/ui/img/theme_pin_the_stylebox.png b/tutorials/ui/img/theme_pin_the_stylebox.png new file mode 100644 index 00000000000..686a425f4e4 Binary files /dev/null and b/tutorials/ui/img/theme_pin_the_stylebox.png differ diff --git a/tutorials/ui/img/theme_preview_picker.png b/tutorials/ui/img/theme_preview_picker.png new file mode 100644 index 00000000000..adb3d48f932 Binary files /dev/null and b/tutorials/ui/img/theme_preview_picker.png differ diff --git a/tutorials/ui/img/theme_type_editor.png b/tutorials/ui/img/theme_type_editor.png new file mode 100644 index 00000000000..9bba721bbbe Binary files /dev/null and b/tutorials/ui/img/theme_type_editor.png differ diff --git a/tutorials/ui/index.rst b/tutorials/ui/index.rst index 4d84677011c..22af8a735f5 100644 --- a/tutorials/ui/index.rst +++ b/tutorials/ui/index.rst @@ -1,13 +1,64 @@ +.. _doc_user_interface: + User Interface (UI) =================== +In this section of the tutorial we explain the basics of creating a graphical +user interface (GUI) in Godot. + +UI building blocks +------------------ + +Like everything else in Godot the user interface is built using nodes, specifically +:ref:`Control ` nodes. There are many different types of controls +which are useful for creating specific types of the GUI. For simplicity we can +separate them into two groups: content and layout. + +Typical content controls include: + +* :ref:`Buttons ` +* :ref:`Labels ` +* :ref:`LineEdits ` and :ref:`TextEdits ` + +Typical layout controls include: + +* :ref:`BoxContainers ` +* :ref:`MarginContainers ` +* :ref:`ScrollContainers ` +* :ref:`TabContainers ` +* :ref:`Popups ` + +The following pages explain the basics of using such controls. + .. toctree:: :maxdepth: 1 - :name: toc-learn-features-gui + :name: toc-gui-basics - gui_skinning - custom_gui_controls size_and_anchors gui_containers - bbcode_in_richtextlabel + custom_gui_controls control_node_gallery + +GUI skinning and themes +----------------------- + +Godot features an in-depth skinning/theming system for control nodes. The pages in this section +explain the benefits of that system and how to set it up in your projects. + +.. toctree:: + :maxdepth: 1 + :name: toc-gui-skinning + + gui_skinning + gui_using_theme_editor + +Control node tutorials +---------------------- + +The following articles cover specific details of using particular control nodes. + +.. toctree:: + :maxdepth: 1 + :name: toc-control-nodes-tutorials + + bbcode_in_richtextlabel