From 6def62dc8d5078e7ec78c14861fd13c6cba02e02 Mon Sep 17 00:00:00 2001 From: Relintai Date: Sat, 27 Apr 2024 14:12:15 +0200 Subject: [PATCH] Cleanups. --- 03_usage/04_ui/01_size_and_anchors.md | 9 +- 03_usage/04_ui/02_gui_containers.md | 39 +++----- 03_usage/04_ui/03_custom_gui_controls.md | 27 ++--- 03_usage/04_ui/04_gui_navigation.md | 10 +- 03_usage/04_ui/05_control_node_gallery.md | 6 +- .../01_bbcode_in_richtextlabel.md | 92 +++++------------- .../{ => control_node_tutorials}/img/fade.png | Bin .../img/rainbow.png | Bin .../img/shake.png | Bin .../img/tornado.png | Bin .../{ => control_node_tutorials}/img/wave.png | Bin 11 files changed, 58 insertions(+), 125 deletions(-) rename 03_usage/04_ui/{ => control_node_tutorials}/img/fade.png (100%) rename 03_usage/04_ui/{ => control_node_tutorials}/img/rainbow.png (100%) rename 03_usage/04_ui/{ => control_node_tutorials}/img/shake.png (100%) rename 03_usage/04_ui/{ => control_node_tutorials}/img/tornado.png (100%) rename 03_usage/04_ui/{ => control_node_tutorials}/img/wave.png (100%) diff --git a/03_usage/04_ui/01_size_and_anchors.md b/03_usage/04_ui/01_size_and_anchors.md index 4d86a50..6a9e617 100644 --- a/03_usage/04_ui/01_size_and_anchors.md +++ b/03_usage/04_ui/01_size_and_anchors.md @@ -1,7 +1,6 @@ -Size and anchors -================ +# Size and anchors If a game was always going to be run on the same device and at the same resolution, positioning controls would be a simple matter of setting the @@ -38,8 +37,7 @@ it, leaving a 20 pixel margin: ![](img/marginaround.png) -Centering a control -------------------- +## Centering a control To center a control in its parent, set its anchors to 0.5 and each margin to half of its relevant dimension. For example, the code below shows how @@ -64,8 +62,7 @@ Setting each anchor to 0.5 moves the reference point for the margins to the center of its parent. From there, we set negative margins so that the control gets its natural size. -Layout Presets --------------- +## Layout Presets Instead of manually adjusting the margin and anchor values, you can use the toolbar's Layout menu, above the viewport. Besides centering, it gives you many diff --git a/03_usage/04_ui/02_gui_containers.md b/03_usage/04_ui/02_gui_containers.md index f5c681e..13231db 100644 --- a/03_usage/04_ui/02_gui_containers.md +++ b/03_usage/04_ui/02_gui_containers.md @@ -1,7 +1,6 @@ -Using Containers -================ +# Using Containers `Anchors doc_size_and_anchors )` are an efficient way to handle different aspect ratios for basic multiple resolution handling in GUIs, @@ -14,8 +13,7 @@ common case where more advanced layout features may be required is in-game tools All these situations require a more capable OS-like user interface, with advanced layout and formatting. For that, `Containers` are more useful. -Container layout ----------------- +## Container layout Containers provide a huge amount of layout power (as an example, the Pandemonium editor user interface is entirely done using them): @@ -34,8 +32,7 @@ Example of *HBoxContainer* resizing children buttons. The real strength of containers is that they can be nested (as nodes), allowing the creation of very complex layouts that resize effortlessly. -Size flags ----------- +## Size flags When adding a node to a container, the way the container treats each child depends mainly on their *size flags*. These flags can be found by inspecting any control that is a child of a *Container*. @@ -56,13 +53,11 @@ Size flags are independent for vertical and horizontal sizing and not all contai Experimenting with these flags and different containers is recommended to get a better grasp on how they work. -Container types ---------------- +## Container types Pandemonium provides several container types out of the box as they serve different purposes: -Box Containers -^^^^^^^^^^^^^^ +### Box Containers Arranges child controls vertically or horizontally (via `HBoxContainer` and `VBoxContainer`). In the opposite of the designated direction @@ -72,16 +67,14 @@ Arranges child controls vertically or horizontally (via `HBoxContainer` and These containers make use of the *Ratio* property for children with the *Expand* flag set. -Grid Container -^^^^^^^^^^^^^^ +### Grid Container Arranges child controls in a grid layout (via `GridContainer`, amount of columns must be specified). Uses both the vertical and horizontal expand flags. ![](img/containers_grid.png) -Margin Container -^^^^^^^^^^^^^^^^ +### Margin Container Child controls are expanded towards the bounds of this control (via `MarginContainer`). Padding will be added on the margins @@ -94,8 +87,7 @@ constants overrides section of each control: ![](img/containers_margin_constants.png) -Tab Container -^^^^^^^^^^^^^ +### Tab Container Allows you to place several child controls stacked on top of each other (via `TabContainer`), with only the *current* one visible. @@ -110,8 +102,7 @@ The titles are generated from the node names by default (although they can be ov Settings such as tab placement and *StyleBox* can be modified in the *TabContainer* theme overrides. -Split Container -^^^^^^^^^^^^^^^ +### Split Container Accepts only one or two children controls, then places them side to side with a divisor (via `HSplitContainer`). @@ -124,8 +115,7 @@ The divisor can be dragged around to change the size relation between both child ![](img/containers_split_drag.gif) -PanelContainer -^^^^^^^^^^^^^^ +### PanelContainer Simple container that draws a *StyleBox*, then expands children to cover its whole area (via `PanelContainer`, respecting the *StyleBox* margins). @@ -135,8 +125,7 @@ It respects both the horizontal and vertical size flags. This container is useful as top-level, or just to add custom backgrounds to sections of a layout. -ScrollContainer -^^^^^^^^^^^^^^^ +### ScrollContainer Accepts a single child node. If this node is bigger than the container, scrollbars will be added to allow panning the node around (via `ScrollContainer`). Both @@ -152,14 +141,12 @@ Mouse wheel and touch drag (when touch is available) are also valid ways to pan As in the example above, one of the most common ways to use this container is together with a *VBoxContainer* as child. -ViewportContainer -^^^^^^^^^^^^^^^^^ +### ViewportContainer This is a special control that will only accept a single *Viewport* node as child, and it will display it as if it was an image (via `ViewportContainer`). -Creating custom Containers --------------------------- +## Creating custom Containers It is possible to easily create a custom container using script. Here is an example of a simple container that fits children to its rect size: diff --git a/03_usage/04_ui/03_custom_gui_controls.md b/03_usage/04_ui/03_custom_gui_controls.md index 57fa3b5..97fee64 100644 --- a/03_usage/04_ui/03_custom_gui_controls.md +++ b/03_usage/04_ui/03_custom_gui_controls.md @@ -1,10 +1,8 @@ -Custom GUI controls -=================== +# Custom GUI controls -So many controls... -------------------- +## So many controls... Yet there are never enough. Creating your own custom controls that act just the way you want them to is an obsession of almost every GUI @@ -13,15 +11,13 @@ the way you want. Before contacting the developers with a pull-request to support diagonal scrollbars, at least it will be good to know how to create these controls easily from script. -Drawing -------- +## Drawing For drawing, it is recommended to check the `doc_custom_drawing_in_2d` tutorial. The same applies. Some functions are worth mentioning due to their usefulness when drawing, so they will be detailed next: -Checking control size -~~~~~~~~~~~~~~~~~~~~~ +### Checking control size Unlike 2D nodes, "size" is important with controls, as it helps to organize them in proper layouts. For this, the @@ -29,8 +25,7 @@ organize them in proper layouts. For this, the property is provided. Checking it during `draw()` is vital to ensure everything is kept in-bounds. -Checking focus -~~~~~~~~~~~~~~ +### Checking focus Some controls (such as buttons or text editors) might provide input focus for keyboard or joypad input. Examples of this are entering text @@ -52,8 +47,7 @@ gdscript GDScript draw_normal() ``` -Sizing ------- +## Sizing As mentioned before, size is important to controls. This allows them to lay out properly, when set into grids, containers, or anchored. @@ -83,14 +77,12 @@ gdscript GDScript set_custom_minimum_size(Vector2(30, 30)) ``` -Input ------ +## Input Controls provide a few helpers to make managing input events much easier than regular nodes. -Input events -~~~~~~~~~~~~ +### Input events There are a few tutorials about input before this one, but it's worth mentioning that controls have a special input method that only works @@ -119,8 +111,7 @@ gdscript GDScript For more information about events themselves, check the `doc_inputevent` tutorial. -Notifications -~~~~~~~~~~~~~ +### Notifications Controls also have many useful notifications for which no dedicated callback exists, but which can be checked with the _notification callback: diff --git a/03_usage/04_ui/04_gui_navigation.md b/03_usage/04_ui/04_gui_navigation.md index 780ff79..f16a7d3 100644 --- a/03_usage/04_ui/04_gui_navigation.md +++ b/03_usage/04_ui/04_gui_navigation.md @@ -1,7 +1,5 @@ - -Keyboard/Controller Navigation and Focus -======================================== +# Keyboard/Controller Navigation and Focus It is a common requirement for a user interface to have full keyboard and controller support for navigation and interaction. There are two main @@ -23,8 +21,7 @@ Warning: Because these actions are used for focus they should not be used for any gameplay code. -Node settings -------------- +## Node settings In addition to the built-in logic, you can define what is known as focus neighbors for each individual control node. This allows to finely tune the path the UI focus @@ -57,8 +54,7 @@ no focus neighbor configured, the engine will try to guess the next control auto This may result in unintended behavior, especially in a complex user interface that doesn't have well-defined vertical or horizontal navigation flow. -Necessary code --------------- +## Necessary code For keyboard and controller navigation to work correctly, any node must be focused on using code when the scene starts. Without doing this, pressing buttons or keys won't diff --git a/03_usage/04_ui/05_control_node_gallery.md b/03_usage/04_ui/05_control_node_gallery.md index df4b247..bb5455b 100644 --- a/03_usage/04_ui/05_control_node_gallery.md +++ b/03_usage/04_ui/05_control_node_gallery.md @@ -1,9 +1,9 @@ -Control node gallery -==================== + +# Control node gallery Here is a list of common Control nodes with their name next to them: -![](/img/control_gallery.png) +![](img/control_gallery.png) The Control Gallery demo pictured above can be found `on GitHub ( https://github.com/Relintai/pandemonium_engine-demo-projects/tree/master/gui/control_gallery )`. diff --git a/03_usage/04_ui/control_node_tutorials/01_bbcode_in_richtextlabel.md b/03_usage/04_ui/control_node_tutorials/01_bbcode_in_richtextlabel.md index 5fc8adf..5cb1154 100644 --- a/03_usage/04_ui/control_node_tutorials/01_bbcode_in_richtextlabel.md +++ b/03_usage/04_ui/control_node_tutorials/01_bbcode_in_richtextlabel.md @@ -1,10 +1,8 @@ -BBCode in RichTextLabel -======================= +# BBCode in RichTextLabel -Introduction ------------- +## Introduction Label nodes are great for displaying basic text, but they have limits. If you want to change the color of the text, or its alignment, that change affects all of the @@ -18,8 +16,7 @@ It has a built-in API for generating the markup, but can also parse a BBCode. Note that the BBCode tags can also be used, to some extent, in the `XML source of the class reference ( doc_updating_the_class_reference )`. -Using BBCode ------------- +## Using BBCode For uniformly formatted text you can write in the "Text" property, but if you want to use BBCode markup you should use the "Text" property in the "Bb Code" section @@ -47,55 +44,36 @@ Note: There are no BBCode tags to control vertical centering of text yet. -Reference ---------- +## Reference -+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+ -| Command | Tag | Description | -+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+ + +| Command | Tag | Description | +|-----------------------|---------------------------------------------------------|--------------------------------------------------------------------------| | **bold** | `[b]{text}[/b]` | Makes {text} bold. | -+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+ | **italics** | `[i]{text}[/i]` | Makes {text} italics. | -+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+ | **underline** | `[u]{text}[/u]` | Makes {text} underline. | -+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+ | **strikethrough** | `[s]{text}[/s]` | Makes {text} strikethrough. | -+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+ | **code** | `[code]{text}[/code]` | Makes {text} use the code font (which is typically monospace). | -+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+ | **center** | `[center]{text}[/center]` | Makes {text} horizontally centered. | -+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+ | **right** | `[right]{text}[/right]` | Makes {text} horizontally right-aligned. | -+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+ | **fill** | `[fill]{text}[/fill]` | Makes {text} fill the RichTextLabel's width. | -+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+ | **indent** | `[indent]{text}[/indent]` | Increase the indentation level of {text}. | -+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+ | **url** | `[url]{url}[/url]` | Show {url} as such, underline it and make it clickable. | -| | | **Must be handled with the "meta_clicked" signal to have an effect.** | -| | | See `doc_bbcode_in_richtextlabel_handling_url_tag_clicks`. | -+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+ +| | | **Must be handled with the "meta_clicked" signal to have an effect.** | +| | | See `doc_bbcode_in_richtextlabel_handling_url_tag_clicks`. | | **url (ref)** | `[url=]{text}[/url]` | Makes {text} reference (underlined and clickable). | -| | | **Must be handled with the "meta_clicked" signal to have an effect.** | -| | | See `doc_bbcode_in_richtextlabel_handling_url_tag_clicks`. | -+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+ +| | | **Must be handled with the "meta_clicked" signal to have an effect.** | +| | | See `doc_bbcode_in_richtextlabel_handling_url_tag_clicks`. | | **image** | `[img]{path}[/img]` | Insert image at resource {path}. | -+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+ | **resized image** | `[img=]{path}[/img]` | Insert image at resource {path} using (keeps ratio). | -+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+ | **resized image** | `[img=x]{path}[/img]` | Insert image at resource {path} using ×. | -+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+ | **font** | `[font=]{text}[/font]` | Use custom font at for {text}. | -+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+ | **color** | `[color=]{text}[/color]` | Change {text} color; use name or # format, such as `#ff00ff`. | -+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+ | **table** | `[table=]{cells}[/table]` | Creates a table with of columns. | -+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+ | **cell** | `[cell]{text}[/cell]` | Adds cells with the {text} to the table. | -+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+ -Built-in color names -~~~~~~~~~~~~~~~~~~~~ + +### Built-in color names List of valid color names for the [color=] tag: @@ -115,8 +93,7 @@ List of valid color names for the [color=] tag: - white - yellow -Hexadecimal color codes -~~~~~~~~~~~~~~~~~~~~~~~ +### Hexadecimal color codes For opaque RGB colors, any valid 6-digit hexadecimal code is supported, e.g. `[color=#ffffff]white[/color]`. Short RGB color codes such as `#6f2` (equivalent to `#66ff22`) are also supported. @@ -125,10 +102,7 @@ For transparent RGB colors, any 8-digit hexadecimal code can be used, e.g. `[col In this case, note that the alpha channel is the **first** component of the color code, not the last one. Short RGBA color codes such as `#86f2` (equivalent to `#8866ff22`) are also supported. - - -Handling `[url]` tag clicks -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +### Handling `[url]` tag clicks By default, `[url]` tags do nothing when clicked. This is to allow flexible use of `[url]` tags rather than limiting them to opening URLs in a web browser. @@ -152,8 +126,7 @@ For more advanced use cases, it's also possible to store JSON in an `[url]` tag's option and parse it in the function that handles the `meta_clicked` signal. For example: `[url={"example": "value"}]JSON[/url]` -Image vertical offset -~~~~~~~~~~~~~~~~~~~~~ +### Image vertical offset You use a custom font for your image in order to align it vertically. @@ -161,14 +134,12 @@ You use a custom font for your image in order to align it vertically. 2. Set this bitmap font with a positive value for the `ascent` property, that's your height offset 3. Set the BBCode tag this way: `[font=][img]{image-path}[/img][/font]` -Animation effects ------------------ +## Animation effects BBCode can also be used to create different text animation effects. Five customizable effects are provided out of the box, and you can easily create your own. -Wave -~~~~ +### Wave ![](img/wave.png) @@ -176,8 +147,7 @@ Wave makes the text go up and down. Its tag format is `[wave amp=50 freq=2][/wav `amp` controls how high and low the effect goes, and `freq` controls how fast the text goes up and down. -Tornado -~~~~~~~ +### Tornado ![](img/tornado.png) @@ -186,8 +156,7 @@ Tornao makes the text move around in a circle. Its tag format is `radius` is the radius of the circle that controls the offset, `freq` is how fast the text moves in a circle. -Shake -~~~~~ +### Shake ![](img/shake.png) @@ -195,8 +164,7 @@ Shake makes the text shake. Its tag format is `[shake rate=5 level=10][/shake]`. `rate` controls how fast the text shakes, `level` controls how far the text is offset from the origin. -Fade -~~~~ +### Fade ![](img/fade.png) @@ -206,8 +174,7 @@ Fade creates a fade effect over the text that is not animated. Its tag format is command is inserted, `length` controls over how many characters should the fade out take place. -Rainbow -~~~~~~~ +### Rainbow ![](img/rainbow.png) @@ -216,8 +183,7 @@ Rainbow gives the text a rainbow color that changes over time. Its tag format is `freq` is the number of full rainbow cycles per second, `sat` is the saturation of the rainbow, `val` is the value of the rainbow. -Custom BBCode tags and text effects ------------------------------------ +## Custom BBCode tags and text effects You can extend the `RichTextEffect` resource type to create your own custom BBCode tags. You begin by extending the `RichTextEffect` resource type. Add @@ -238,8 +204,7 @@ Optionally, you can also provide a custom BBCode identifier simply by adding a m name `bbcode`. The code will check the `bbcode` property automatically or will use the name of the file to determine what the BBCode tag should be. -`process_custom_fx` -~~~~~~~~~~~~~~~~~~~~~~ +### `process_custom_fx` This is where the logic of each effect takes place and is called once per character during the draw phase of text rendering. This passes in a `CharFXTransform` @@ -269,8 +234,7 @@ the user fixes whatever error cropped up in their custom effect logic. Here are some examples of custom effects: -Ghost -~~~~~ +### Ghost ``` tool @@ -292,8 +256,7 @@ Ghost return true ``` -Pulse -~~~~~ +### Pulse ``` tool @@ -319,8 +282,7 @@ Pulse return true ``` -Matrix -~~~~~~ +### Matrix ``` tool diff --git a/03_usage/04_ui/img/fade.png b/03_usage/04_ui/control_node_tutorials/img/fade.png similarity index 100% rename from 03_usage/04_ui/img/fade.png rename to 03_usage/04_ui/control_node_tutorials/img/fade.png diff --git a/03_usage/04_ui/img/rainbow.png b/03_usage/04_ui/control_node_tutorials/img/rainbow.png similarity index 100% rename from 03_usage/04_ui/img/rainbow.png rename to 03_usage/04_ui/control_node_tutorials/img/rainbow.png diff --git a/03_usage/04_ui/img/shake.png b/03_usage/04_ui/control_node_tutorials/img/shake.png similarity index 100% rename from 03_usage/04_ui/img/shake.png rename to 03_usage/04_ui/control_node_tutorials/img/shake.png diff --git a/03_usage/04_ui/img/tornado.png b/03_usage/04_ui/control_node_tutorials/img/tornado.png similarity index 100% rename from 03_usage/04_ui/img/tornado.png rename to 03_usage/04_ui/control_node_tutorials/img/tornado.png diff --git a/03_usage/04_ui/img/wave.png b/03_usage/04_ui/control_node_tutorials/img/wave.png similarity index 100% rename from 03_usage/04_ui/img/wave.png rename to 03_usage/04_ui/control_node_tutorials/img/wave.png