Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update size and anchors tutorial #7106

Closed
wants to merge 4 commits into from
Closed

Update size and anchors tutorial #7106

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7883c58
update size_and_anchors
jnettl Apr 1, 2023
bb771b4
update png to webp
jnettl Apr 1, 2023
8392596
Fix typo
jnettl Apr 2, 2023
d727506
Fix image reference in size_and_anchors.rst
jnettl Apr 2, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file removed tutorials/ui/img/anchors.png
View file
Open in desktop
Binary file not shown.
Binary file added tutorials/ui/img/anchors_dropdown_menu.webp
View file
Open in desktop
Binary file not shown.
Binary file added tutorials/ui/img/custom_anchors_preset.webp
View file
Open in desktop
Binary file not shown.
Binary file removed tutorials/ui/img/layout_dropdown_menu.png
View file
Open in desktop
Binary file not shown.
Binary file removed tutorials/ui/img/margin.png
View file
Open in desktop
Binary file not shown.
Binary file removed tutorials/ui/img/marginaround.png
View file
Open in desktop
Binary file not shown.
Binary file added tutorials/ui/img/marginaround.webp
View file
Open in desktop
Binary file not shown.
Binary file removed tutorials/ui/img/marginend.png
View file
Open in desktop
Binary file not shown.
Binary file added tutorials/ui/img/ui_anchor_and_margins.webp
View file
Open in desktop
Binary file not shown.
75 changes: 40 additions & 35 deletions tutorials/ui/size_and_anchors.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
:article_outdated: True

.. _doc_size_and_anchors:

Size and anchors
Expand All @@ -17,37 +15,53 @@ and mobile phones have different resolutions and aspect ratios.
There are several ways to handle this, but for now, let's just imagine
that the screen resolution has changed and the controls need to be
re-positioned. Some will need to follow the bottom of the screen, others
the top of the screen, or maybe the right or left margins.
the top of the screen, or maybe the right or left borders.

.. image:: img/ui_anchor_and_margins.webp
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This image has a bunch of incorrect terminology. First of all, it refers to a parent container. While it's a generic word, a container is a term in Godot that carries special meaning. One of the characteristic of containers is that you don't use anchors with them. It should be "parent control", as it was in the original image.

Terms "anchor pin" and "anchor ratio" aren't great either as they don't exist in this form in Godot. Point and value would be more appropriate.

Furthermore, here and below you use the term "margin", but in Godot 4 this property was renamed to avoid confusion with MarginContainers. It's offsets now, which it is correctly called way below in the article, but not directly below this image, and not in the image itself.


This is done using the *margin* and *anchor* properties. Margins represent a
distance in pixels relative to the top-left corner of the parent control or
(in case there is no parent control) the viewport. Anchors adjust where the
margin distances are relative *to*. We can think of them as a percentage of the
parent's size, represented by a value between 0 and 1.0.
Comment on lines +22 to +26
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Anchors should probably be explained before offsets. Also offsets are not relative to the top-left corner, that's only true by default. They are relative to anchor points, and anchor points in turn default to the top-left corner. I think this explanation here needs more work.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also you should be consistent when formatting numbers. It should be 0.0 throughout the article.


.. image:: img/anchors.png
:ref:`Containers <doc_gui_containers>` are used to compose the layout of control
scenes, offering powerful layout and sizing functionality. The MarginContainer
is where we typically set margins for its child controls. When using containers,
controls will inherit the layout properties of their parent, removing the need
to modify the anchors of a control.
Comment on lines +28 to +32
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is just wrong and misleading.


Layout Presets
--------------

This is done by editing the *margin* properties of controls. Each
control has four margins: left, right, bottom, and top, which correspond
to the respective edges of the control. By default, all of
them represent a distance in pixels relative to the top-left corner of
the parent control or (in case there is no parent control) the viewport.
Each control has an individual anchor that can be adjusted from the beginning
to the end of the parent. So the vertical (top, bottom) anchors adjust from 0
(top of parent) to 1.0 (bottom of parent) with 0.5 being the center. The
horizontal (left, right) anchors similarly adjust from left to right of the
parent.
Comment on lines +37 to +41
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is this mentioned in the section about presets? It should be explained above, in the section about the basics.


.. image:: img/margin.png
Instead of manually setting the *anchor* properties of a control, you can use
the toolbar's Layout menu, above the viewport. Besides centering, it gives you
many options to align and resize control nodes. These will automatically set
the *anchor* properties.
Comment on lines +45 to +46
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They set anchors, offsets, and grow direction (this last one is new to 4.0).


So to make the control wider you can make the right margin larger and/or
make the left margin smaller. This lets you set the exact placement
and shape of the control.
Note that changing the layout preset will overwrite the position and size of
the control. Set to Current Ratio will automatically adjust the control's anchor
points and offsets to match the current size and position of the control.

The *anchor* properties adjust where the margin distances are relative *to*.
Each margin has an individual anchor that can be adjusted from the
beginning to the end of the parent. So the vertical (top, bottom) anchors
adjust from 0 (top of parent) to 1.0 (bottom of parent) with 0.5 being
the center, and the control margins will be placed relative to that
point. The horizontal (left, right) anchors similarly adjust from left to
right of the parent.
.. image:: img/anchors_dropdown_menu.webp

Note that when you wish the edge of a control to be above or left of the
anchor point, you must change the margin value to be negative.
Custom Anchors
--------------

For example: when horizontal anchors are changed to 1, the margin values
become relative to the top-right corner of the parent control or viewport.
The *anchor* properties can be set manually using the custom anchors preset
option. Here we can change the exact placement and shape of the control
Comment on lines +57 to +58
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's strange that only at this point in the article we explain that you can set anchors manually, when we already explained that, hey, you don't have to. I don't think this flows well.

We also skip the entire Layout section of the Inspector, which is likely the main tool everyone would use, and not the custom anchors or the toolbar. If we go from the Inspector side of things, we can gradually explain that you can position the node directly, then by using layout presets and anchor presets, and then manually. And then mention the toolbar.

with the anchor points and offsets. Each control has four anchor points and
offsets: left, right, bottom, and top, which correspond to the respective edges
of the control. Anchor offsets represent the relative distance from the anchor
point to the corresponding edge of the control.

.. image:: img/marginend.png
.. image:: img/custom_anchors_preset.webp

Adjusting the two horizontal or the two vertical anchors to different
values will make the control change size when the parent control does.
Expand All @@ -56,7 +70,7 @@ parent's bottom-right, while the top-left control margins are still
anchored to the top-left of the parent, so when re-sizing the parent,
the control will always cover it, leaving a 20 pixel margin:

.. image:: img/marginaround.png
.. image:: img/marginaround.webp

Centering a control
-------------------
Expand Down Expand Up @@ -102,12 +116,3 @@ a TextureRect can be centered in its parent:
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
--------------

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
options to align and resize control nodes.

.. image:: img/layout_dropdown_menu.png