mirror of
https://github.com/Relintai/pandemonium_engine_docs.git
synced 2025-01-04 14:49:52 +01:00
Cleanups.
This commit is contained in:
parent
a1cc43d629
commit
6def62dc8d
@ -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:
|
||||
|
||||
|
||||
|
||||
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
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
|
||||
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:
|
||||
|
||||
|
||||
|
||||
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
|
||||
|
||||
|
||||
|
||||
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:
|
||||
|
||||
@ -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:
|
||||
|
||||
@ -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
|
||||
|
||||
@ -1,9 +1,9 @@
|
||||
Control node gallery
|
||||
====================
|
||||
|
||||
# Control node gallery
|
||||
|
||||
Here is a list of common Control nodes with their name next to them:
|
||||
|
||||
|
||||
|
||||
|
||||
The Control Gallery demo pictured above can be found
|
||||
`on GitHub ( https://github.com/Relintai/pandemonium_engine-demo-projects/tree/master/gui/control_gallery )`.
|
||||
|
||||
@ -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=<url>]{text}[/url]` | Makes {text} reference <url> (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=<width>]{path}[/img]` | Insert image at resource {path} using <width> (keeps ratio). |
|
||||
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
|
||||
| **resized image** | `[img=<width>x<height>]{path}[/img]` | Insert image at resource {path} using <width>×<height>. |
|
||||
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
|
||||
| **font** | `[font=<path>]{text}[/font]` | Use custom font at <path> for {text}. |
|
||||
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
|
||||
| **color** | `[color=<code/name>]{text}[/color]` | Change {text} color; use name or # format, such as `#ff00ff`. |
|
||||
+-----------------------+-----------------------------------------------------------+--------------------------------------------------------------------------+
|
||||
| **table** | `[table=<number>]{cells}[/table]` | Creates a table with <number> 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=<name>] tag:
|
||||
|
||||
@ -115,8 +93,7 @@ List of valid color names for the [color=<name>] 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=<font-path>][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
|
||||
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
Before Width: | Height: | Size: 2.4 KiB After Width: | Height: | Size: 2.4 KiB |
|
Before Width: | Height: | Size: 1.6 KiB After Width: | Height: | Size: 1.6 KiB |
|
Before Width: | Height: | Size: 1.3 KiB After Width: | Height: | Size: 1.3 KiB |
|
Before Width: | Height: | Size: 1.5 KiB After Width: | Height: | Size: 1.5 KiB |
|
Before Width: | Height: | Size: 1.9 KiB After Width: | Height: | Size: 1.9 KiB |
Loading…
Reference in New Issue
Block a user