Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Usando Contêineres

As Âncoras são uma maneira eficiente de lidar com diferentes proporções de tela para o gerenciamento básico de múltiplas resoluções em GUIs.

Para interfaces de usuário mais complexas, elas podem se tornar difíceis de usar.

Esse costuma ser o caso de jogos como RPGs, chats online, tycoons ou simulações. Outro caso comum onde recursos de layout mais avançados podem ser necessários são as ferramentas de jogo (ou simplesmente ferramentas).

Todas essas situações exigem uma interface de usuário mais robusta, semelhante à de um sistema operacional, com layout e formatação avançados. Para isso, os Containers são mais úteis.

Layout do contêiner

Os containers oferecem uma enorme quantidade de poder de layout (como exemplo, a interface do usuário do editor do Godot é inteiramente feita usando eles):

Quando um nó derivado de Container é usado, todos os nós filhos Control abrem mão de sua própria capacidade de posicionamento. Isso significa que o Container controlará o posicionamento deles, e qualquer tentativa de alterar manualmente esses nós será ignorada ou invalidada na próxima vez que o pai for redimensionar.

Da mesma forma, quando um nó derivado de Container é redimensionado, todos os seus filhos serão reposicionados de acordo com ele, com um comportamento baseado no tipo de container utilizado:

Exemplo de um HBoxContainer redimensionando botões filhos.

A verdadeira força dos containers é que eles podem ser aninhados (como nós), permitindo a criação de layouts muito complexos que se redimensionam sem esforço.

Opções de dimensionamento

Ao adicionar um nó a um container, a maneira como o container trata cada filho depende principalmente de suas opções de dimensionamento de container. Essas opções podem ser encontradas inspecionando o layout de qualquer Control que seja filho de um Container.

As opções de dimensionamento são independentes para o tamanho vertical e horizontal, e nem todos os containers fazem uso delas (mas a maioria faz):

Fill: Garante que o controle preencha a área designada dentro do container. Não importa se um controle se expande ou não (veja abaixo), ele só preencherá a área designada quando isso estiver ativado (vem ativado por padrão).
Expand: Tenta usar o máximo de espaço possível no container pai (em cada eixo). Controles que não se expandem serão empurrados por aqueles que se expandem. Entre os controles que se expandem, a quantidade de espaço que eles tiram uns dos outros é determinada pela Stretch Ratio (veja abaixo). Esta opção só está disponível quando o Container pai é do tipo correto; por exemplo, o HBoxContainer possui esta opção para o dimensionamento horizontal.
Shrink Begin: Ao expandir, tenta permanecer à esquerda ou no topo da área expandida.
Shrink Center: Ao expandir, tenta permanecer no centro da área expandida.
Shrink End: Ao expandir, tenta permanecer à direita ou na parte inferior da área expandida.
Stretch Ratio: A proporção de quanto os controles expandidos ocupam do espaço disponível em relação uns aos outros. Um controle com "2" ocupará o dobro do espaço disponível em relação a um com "1".

Experimentar com essas flags e diferentes containers é recomendado para obter uma melhor compreensão de como eles funcionam.

Tipos de contêiner

O Godot fornece vários tipos de containers prontos para o uso, já que eles servem a propósitos diferentes:

Containers de Caixa

Organiza os controles filhos vertical ou horizontalmente (via HBoxContainer e VBoxContainer). Na direção oposta à estipulada (por exemplo, vertical para um container horizontal), ele apenas expande os filhos.

Esses containers fazem uso da propriedade Stretch Ratio para filhos que estão com a flag Expand ativada.

Grid Container

Organiza os controles filhos em um layout de grade (via GridContainer, a quantidade de colunas deve ser especificada). Usa as flags de expansão vertical e horizontal.

MarginContainer (Contêiner de margem)

Os controles filhos são expandidos em direção aos limites deste controle (via MarginContainer). O espaçamento (padding) será adicionado nas margens dependendo da configuração do tema.

Novamente, tenha em mente que as margens são um valor do Tema (Theme), portanto, precisam ser editadas na seção de sobreposição de constantes de cada controle:

Tab Container

Permite que você coloque vários controles filhos empilhados uns sobre os outros (via TabContainer), com apenas o controle atual visível.

A alteração do controle atual é feita por meio de abas localizadas no topo do container, através de cliques:

Os títulos são gerados a partir dos nomes dos nós por padrão (embora possam ser substituídos via API do TabContainer).

Configurações como o posicionamento das abas e o StyleBox podem ser modificadas nas sobreposições de tema do TabContainer.

Split Container

Organiza os controles filhos vertical ou horizontalmente e cria barras de arrasto (grabbers) entre eles (via HSplitContainer e VSplitContainer). Respeita as flags de expansão horizontal e vertical, bem como a Stretch Ratio.

As barras de arrasto podem ser movidas para alterar a relação de tamanho entre os filhos:

PanelContainer

Um container que desenha um StyleBox e, em seguida, expande os filhos para cobrir toda a sua área (via PanelContainer, respeitando as margens do StyleBox). Ele respeita as opções de dimensionamento tanto horizontais quanto verticais.

Este container é útil como um controle de nível superior ou apenas para adicionar fundos personalizados a seções de um layout.

FoldableContainer

Um container que pode ser expandido/recolhido (via FoldableContainer). Os controles filhos ficam ocultos quando ele está recolhido.

ScrollContainer

Aceita um único nó filho. Se o nó filho for maior que o container, barras de rolagem serão adicionadas para permitir o arrasto (pan) do nó (via ScrollContainer). Ambas as opções de tamanho vertical e horizontal são respeitadas, e o comportamento pode ser ligado ou desligado por eixo nas propriedades.

A roda do mouse e o arrasto por toque (quando o toque está disponível) também são formas válidas de arrastar o controle filho.

Como no exemplo acima, uma das maneiras mais comuns de usar este container é junto com um VBoxContainer como filho.

AspectRatioContainer

A container type that arranges its child controls in a way that preserves their proportions automatically when the container is resized. (via AspectRatioContainer). It has multiple stretch modes, providing options for adjusting the child controls' sizes relative to the container: Width Controls Height, Height Controls Width, Fit, and Cover.

É útil quando você tem um container que precisa ser dinâmico e responsivo a diferentes tamanhos de tela, e deseja que os elementos filhos se redimensionem proporcionalmente sem perder suas formas pretendidas.

FlowContainer

FlowContainer é um container que organiza seus controles filhos horizontal ou verticalmente (via HFlowContainer e via VFlowContainer). Quando o espaço disponível se esgota, ele quebra os filhos para a próxima linha ou coluna, de forma semelhante a como o texto quebra em um livro.

É útil para criar layouts flexíveis onde os controles filhos se ajustam automaticamente ao espaço disponível sem se sobreporem.

CenterContainer

CenterContainer é um container que mantém automaticamente todos os seus controles filhos centralizados dentro dele em seu tamanho mínimo. Ele garante que os controles filhos estejam sempre alinhados ao centro, facilitando a criação de layouts centralizados sem posicionamento manual (via CenterContainer).

SubViewportContainer

Este é um controle especial que aceitará apenas um único nó Viewport como filho, e o exibirá como se fosse uma imagem (via SubViewportContainer).

Criando Contêineres personalizados

É possível criar um container personalizado usando um script. Aqui está um exemplo de um container que ajusta os filhos ao seu tamanho:

extends Container

func _notification(what):
    if what == NOTIFICATION_SORT_CHILDREN:
        # Must re-sort the children
        for c in get_children():
            # Fit to own size
            fit_child_in_rect(c, Rect2(Vector2(), size))

func set_some_setting():
    # Some setting changed, ask for children re-sort.
    queue_sort()

using Godot;

public partial class CustomContainer : Container
{
    public override void _Notification(int what)
    {
        if (what == NotificationSortChildren)
        {
            // Must re-sort the children
            foreach (Control c in GetChildren())
            {
                // Fit to own size
                FitChildInRect(c, new Rect2(new Vector2(), Size));
            }
        }
    }

    public void SetSomeSetting()
    {
        // Some setting changed, ask for children re-sort.
        QueueSort();
    }
}