diff --git a/tutorials/ui/files/skin_assets.zip b/tutorials/ui/files/skin_assets.zip deleted file mode 100644 index f84d9dbe4..000000000 Binary files a/tutorials/ui/files/skin_assets.zip and /dev/null differ diff --git a/tutorials/ui/gui_skinning.rst b/tutorials/ui/gui_skinning.rst index 08ab13117..e2f2dcf57 100644 --- a/tutorials/ui/gui_skinning.rst +++ b/tutorials/ui/gui_skinning.rst @@ -3,40 +3,15 @@ GUI skinning ============ -Oh, beautiful GUI! ------------------- +Themes +------ -This tutorial is about advanced skinning of a user interface. Most -games generally don't need this, as they end up just relying on -:ref:`Label `, :ref:`TextureRect `, -:ref:`TextureButton ` and -:ref:`TextureProgress `. - -However, many types of games often need complex user interfaces, like -MMOs, traditional RPGs, Simulators, Strategy, etc. These kinds of -interface are also common in some games that include editors to create -content, or interfaces for network connectivity. - -Godot's user interface uses these kinds of control with the default theme, -but they can be skinned to resemble pretty much any kind of user -interface. - -Theme ------ - -The GUI is skinned through the :ref:`Theme ` +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. Theme options are named, so it's -not obvious which name changes what (especially from code), but several -tools are provided. The ultimate place to look at what each theme option -is for each control, which will always be more up to date than any -documentation, is the file `scene/resources/default_theme/default_theme.cpp -`__. -The rest of this document will explain the different tools used to -customize the theme. +entire visual styling of all controls. -A Theme can be applied to any control in the scene. As a result, all -children and grand-children controls will use that same theme, too +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 @@ -51,29 +26,122 @@ user interfaces. 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. -Theme options -------------- +Creating a theme +---------------- -Each kind of option in a theme can be: +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**. -- **An integer constant**: A single numerical constant. Generally used - to define spacing between components or alignment. -- **A Color**: A single color, with or without transparency. Colors are +.. 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 + +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: + +- **Color**: A single color, with or without transparency. Colors are usually applied to fonts and icons. -- **A Texture**: A single image. Textures are not often used, but when +- **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). -- **A Font**: Every control that uses text can be assigned the fonts - used to draw strings. -- **A StyleBox**: Stylebox is a resource that defines how to draw a +- **StyleBox**: Stylebox is a resource that defines how to draw a panel in varying sizes (more information on them later). -Every option is associated with: +Every item is associated with: -- A name (the name of the option) +- A name (the name of the item) - A Control (the name of the control) -An example usage: +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. + +.. image:: img/theme_item_inspector.png + +You can also add custom theme items to a control node under the built in theme items. + +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. + +Manage theme Items +------------------ + +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. + +.. image:: img/manage_items.png + +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. + +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. + +.. image:: img/import_items.png + +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 +--------------- + +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: + +.. image:: img/themecheck.png + +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. + +Changing themes with code +------------------------- + +In addition to the theme editor it is possible to change theme items with +code, here is an example: .. tabs:: .. code-tab:: gdscript GDScript @@ -111,76 +179,5 @@ directly, and only for a specific control, by using the override API in var label = new Label(); label.AddColorOverride("fontColor", new Color(1.0f, 0.0f, 0.0f)); -In the inline help of Godot (in the Script tab), you can check which theme options +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. - -Customizing a control ---------------------- - -If only a few controls need to be skinned, it is often not necessary to -create a new theme. Controls offer their theme options as special kinds -of properties. If checked, overriding will take place: - -.. image:: img/themecheck.png - -As can be seen in the image above, theme options have little check boxes. -If checked, they can be used to override the value of the theme just for -that control. - -Creating a theme ----------------- - -The simplest way to create a theme is to edit a theme resource. Create a -Theme from the resource menu; the editor will appear immediately. -After that, save it (for example, with the name mytheme.theme): - -.. image:: img/sb2.png - -This will create an empty theme that can later be loaded and assigned to -controls. - -Example: theming a button --------------------------- - -Download these assets (:download:`skin_assets.zip `) -and add them to your project. Open the theme editor, click on "Edit Theme" -and select "Add Class Items": - -.. image:: img/themeci.png - -A menu will appear prompting the type of control to create. Select -"Button": - -.. image:: img/themeci2.png - -Immediately, all button theme options will appear in the property -editor, where they can be edited: - -.. image:: img/themeci3.png - -From ``Styles``, open the "Normal" drop-down menu next to where it probably -says "null" and create a "New StyleBoxTexture", then -edit it. A texture stylebox contains a texture and the size of the margins -that will not stretch when the texture is stretched. -This is called nine-patch or "3x3" stretching: - -.. image:: img/sb1.png - -Repeat the steps and add the other assets. There is no hover or disabled -image in the example files, so use the same stylebox as in normal. Set -the supplied font as the button font and change the font color to black. -Soon, your button will look different and retro: - -.. image:: img/sb2.png - -Save this theme to the .theme file. Go to the 2D editor and create a few -buttons: - -.. image:: img/skinbuttons1.png - -Now, go to the root node of the scene and locate the "theme" property, -replace it with the theme that was just created. It should look like this: - -.. image:: img/skinbuttons2.png - -Congratulations! You have created a reusable GUI Theme! diff --git a/tutorials/ui/img/add_item_type.png b/tutorials/ui/img/add_item_type.png new file mode 100644 index 000000000..a58e45185 Binary files /dev/null and b/tutorials/ui/img/add_item_type.png differ diff --git a/tutorials/ui/img/default_font.png b/tutorials/ui/img/default_font.png new file mode 100644 index 000000000..8f1894236 Binary files /dev/null and b/tutorials/ui/img/default_font.png differ diff --git a/tutorials/ui/img/default_preview.png b/tutorials/ui/img/default_preview.png new file mode 100644 index 000000000..83b927b0c Binary files /dev/null and b/tutorials/ui/img/default_preview.png differ diff --git a/tutorials/ui/img/import_items.png b/tutorials/ui/img/import_items.png new file mode 100644 index 000000000..a7c1a57b2 Binary files /dev/null and b/tutorials/ui/img/import_items.png differ diff --git a/tutorials/ui/img/manage_items.png b/tutorials/ui/img/manage_items.png new file mode 100644 index 000000000..2fdcae1de Binary files /dev/null and b/tutorials/ui/img/manage_items.png differ diff --git a/tutorials/ui/img/new_theme.png b/tutorials/ui/img/new_theme.png new file mode 100644 index 000000000..ff16dbbcc Binary files /dev/null and b/tutorials/ui/img/new_theme.png differ diff --git a/tutorials/ui/img/sb1.png b/tutorials/ui/img/sb1.png deleted file mode 100644 index 4581e024d..000000000 Binary files a/tutorials/ui/img/sb1.png and /dev/null differ diff --git a/tutorials/ui/img/sb2.png b/tutorials/ui/img/sb2.png deleted file mode 100644 index 7fe1746b2..000000000 Binary files a/tutorials/ui/img/sb2.png and /dev/null differ diff --git a/tutorials/ui/img/scene_preview.png b/tutorials/ui/img/scene_preview.png new file mode 100644 index 000000000..31ae06c40 Binary files /dev/null and b/tutorials/ui/img/scene_preview.png differ diff --git a/tutorials/ui/img/skinbuttons1.png b/tutorials/ui/img/skinbuttons1.png deleted file mode 100644 index 226bd90dc..000000000 Binary files a/tutorials/ui/img/skinbuttons1.png and /dev/null differ diff --git a/tutorials/ui/img/skinbuttons2.png b/tutorials/ui/img/skinbuttons2.png deleted file mode 100644 index b6a79ef6d..000000000 Binary files a/tutorials/ui/img/skinbuttons2.png and /dev/null differ diff --git a/tutorials/ui/img/theme_editor.png b/tutorials/ui/img/theme_editor.png new file mode 100644 index 000000000..d54e13113 Binary files /dev/null and b/tutorials/ui/img/theme_editor.png differ diff --git a/tutorials/ui/img/theme_item_inspector.png b/tutorials/ui/img/theme_item_inspector.png new file mode 100644 index 000000000..8599fb817 Binary files /dev/null and b/tutorials/ui/img/theme_item_inspector.png differ diff --git a/tutorials/ui/img/themecheck.png b/tutorials/ui/img/themecheck.png index 9fbd8e68c..55ffc5ba0 100644 Binary files a/tutorials/ui/img/themecheck.png and b/tutorials/ui/img/themecheck.png differ diff --git a/tutorials/ui/img/themeci.png b/tutorials/ui/img/themeci.png deleted file mode 100644 index 5075df1fc..000000000 Binary files a/tutorials/ui/img/themeci.png and /dev/null differ diff --git a/tutorials/ui/img/themeci2.png b/tutorials/ui/img/themeci2.png deleted file mode 100644 index 060f645be..000000000 Binary files a/tutorials/ui/img/themeci2.png and /dev/null differ diff --git a/tutorials/ui/img/themeci3.png b/tutorials/ui/img/themeci3.png deleted file mode 100644 index d0e80f367..000000000 Binary files a/tutorials/ui/img/themeci3.png and /dev/null differ