Update size and anchors tutorial #7106
Conversation
update size_and_anchors
|
Hey! Thanks for contributing. Please convert the PNG file(s) to WebP while you're at it (we're in the process of moving the docs repository over to WebP, see image creation guidelines). |
mhilbrunner
added
bug
area:manual
|
No worries, glad to be here! |
|
This is probably a good fix-up, but just for the record, there is a plan to rewrite these articles (this one, and the one about containers, that you've also edited). Here's the current short plan:
The task is to replace https://docs.godotengine.org/en/latest/tutorials/ui/size_and_anchors.html and parts of https://docs.godotengine.org/en/latest/tutorials/ui/gui_containers.html with a new article about creating layouts.
Creating UI layouts
Layout modes in GodotThis comment is a great reference IMO:
It may be worth it to port the entire containers article here, except for the custom containers part (custom containers deserve a dedicated article that fully explores the subject, not a small paragraph at the end with an obscure code sample). Editor tools for layouts
|
YuriSizov
added
the
content:images
|
Ah cheers, it's good to have a reference for a proper rewrite. I was planning on raising it once these were merged anyway. I'll put something together soon but it'll be good to not have outdated info for now at least! |
|
Even though it will be rewritten, can this be merged? |
mhilbrunner
requested review from
NathanLovato and
YuriSizov
and removed request for
NathanLovato
|
cc @YuriSizov - would be cool if you could review this so we can merge it as an improvement until this is rewritten. |
There was a problem hiding this comment.
Sorry for the delay. I looked further into this PR, and I don't think it's good to merge. It doesn't improve the content much, misses the important information from Godot 4, and also has misleading statements. It needs to be improved a lot, so I left some pointers to get started.
| 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 |
There was a problem hiding this comment.
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.
| :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. |
There was a problem hiding this comment.
This is just wrong and misleading.
| 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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Also you should be consistent when formatting numbers. It should be 0.0 throughout the article.
| 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. |
There was a problem hiding this comment.
Why is this mentioned in the section about presets? It should be explained above, in the section about the basics.
| many options to align and resize control nodes. These will automatically set | ||
| the *anchor* properties. |
There was a problem hiding this comment.
They set anchors, offsets, and grow direction (this last one is new to 4.0).
| 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 |
There was a problem hiding this comment.
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.
mhilbrunner
added
the
needs work
|
Closing this PR due to lack of activity for over two months after Yuri's review. |
Piralein
removed
the
needs work
Updated the size and anchors tutorial to reflect the changes made in Godot 4.