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...

컨테이너 사용하기

:ref:`Anchors <doc_size_and_anchors>`는 GUI에서 기본 다중 해상도 처리를 위해 다양한 종횡비를 처리하는 효율적인 방법입니다.

더 복잡한 사용자 인터페이스의 경우 사용하기 어려울 수 있습니다.

이는 RPG, 온라인 채팅, 타이쿤 또는 시뮬레이션과 같은 게임의 경우인 경우가 많습니다. 더 고급 레이아웃 기능이 필요할 수 있는 또 다른 일반적인 경우는 게임 내 도구(또는 단순히 도구)입니다.

이러한 모든 상황에는 고급 레이아웃과 형식을 갖춘 더욱 유능한 OS와 유사한 사용자 인터페이스가 필요합니다. 이를 위해서는 Containers가 더 유용합니다.

컨테이너 레이아웃

컨테이너는 엄청난 양의 레이아웃 기능을 제공합니다(예를 들어 Godot 편집기 사용자 인터페이스는 완전히 컨테이너를 사용하여 수행됩니다):

Container 파생 노드를 사용하면 모든 자식 노드 Control 노드가 자체 위치 지정 능력을 포기합니다. 이는 컨테이너가 해당 위치를 제어하고 이러한 노드를 수동으로 변경하려는 모든 시도가 다음에 해당 상위 항목의 크기가 조정될 때 무시되거나 무효화됨을 의미합니다.

마찬가지로 컨테이너 파생 노드의 크기가 조정되면 모든 자식 노드가 이에 따라 재배치되며 사용된 컨테이너 유형에 따라 동작합니다.

자식 노드 버튼 크기를 조정하는 HBoxContainer의 예입니다.

컨테이너의 진정한 장점은 중첩될 수 있어(노드로) 쉽게 크기를 조정할 수 있는 매우 복잡한 레이아웃을 생성할 수 있다는 것입니다.

플러그인에 대해서

컨테이너에 노드를 추가할 때 컨테이너가 각 하위 항목을 처리하는 방식은 주로 *컨테이너 크기 조정 옵션*에 따라 달라집니다. 이러한 옵션은 *컨테이너*의 하위 항목인 *컨트롤*의 레이아웃을 검사하여 찾을 수 있습니다.

크기 조정 옵션은 수직 및 수평 크기 조정에 독립적이며 모든 컨테이너가 이를 사용하는 것은 아니지만 대부분은 사용합니다.

Fill: Ensures the control fills the designated area within the container. 컨트롤이 확장되는지 여부에 관계없이(아래 참조) 이 기능이 켜져 있으면 지정된 영역만 채워집니다(기본값).
확장: 상위 컨테이너(각 축)에서 최대한 많은 공간을 사용하려고 시도합니다. 확장되지 않는 컨트롤은 확장되는 컨트롤에 의해 밀려나게 됩니다. 확장 컨트롤 사이에서 서로 차지하는 공간의 양은 *늘이기 비율*(아래 참조)에 따라 결정됩니다. 이 옵션은 상위 컨테이너가 올바른 유형일 때만 사용할 수 있습니다. 예를 들어 *HBoxContainer*에는 가로 크기 조정을 위한 이 옵션이 있습니다.
시작점에서 수축 확장할 때는 확장된 영역의 왼쪽이나 위에서 머무르도록 합니다.
중앙에서 수축 확장할 때는 확장된 영역의 가운데에서 머무르도록 합니다.
끝점에서 수축 확장할 때는 확장된 영역의 오른쪽이나 아래에서 머무르도록 합니다.
늘이기 비율: 확장된 컨트롤이 서로 사용 가능한 공간을 차지하는 비율입니다. "2" 컨트롤은 "1" 컨트롤보다 두 배의 사용 가능한 공간을 차지합니다.

작동 방식을 더 잘 이해하려면 이러한 플래그와 다양한 컨테이너를 실험해 보는 것이 좋습니다.

컨테이너 내장 타입

Godot는 다양한 용도로 사용되는 여러 가지 컨테이너 유형을 즉시 제공합니다:

박스컨테이너

하위 컨트롤을 수직 또는 수평으로 정렬합니다(HBoxContainer 및 :ref:`VBoxContainer <class_VBoxContainer>`를 통해). 지정된 방향의 반대 방향(수평 컨테이너의 경우 수직)에서는 자식 노드만 확장됩니다.

이러한 컨테이너는 Expand 플래그가 설정된 자식 노드의 Stretch Ratio 속성을 활용합니다.

그리드 컨테이너

GridContainer를 통해 하위 컨트롤을 그리드 레이아웃으로 정렬합니다. 열의 양을 지정해야 합니다. 수직 및 수평 확장 플래그를 모두 사용합니다.

마진 컨테이너

하위 컨트롤은 이 컨트롤의 경계를 향해 확장됩니다(MarginContainer를 통해). 테마 구성에 따라 여백에 패딩이 추가됩니다.

여백은 테마 값이므로 각 컨트롤의 상수 재정의 섹션에서 편집해야 합니다.

탭 컨테이너

TabContainer를 통해 여러 개의 하위 컨트롤을 서로 겹쳐서 배치할 수 있으며 현재 컨트롤만 표시됩니다.

현재 항목 변경은 다음을 클릭하여 컨테이너 상단에 있는 탭을 통해 수행됩니다.

제목은 기본적으로 노드 이름에서 생성됩니다(단, TabContainer API를 통해 재정의할 수 있음).

탭 배치 및 StyleBox와 같은 설정은 TabContainer 테마 재정의에서 수정할 수 있습니다.

분할 컨테이너

Arranges child controls vertically or horizontally and creates grabbers between them (via HSplitContainer and VSplitContainer). Respects both horizontal and vertical expand flags, as well as Stretch Ratio.

The grabbers can be dragged around to change the size relation between the children:

패널컨테이너

StyleBox*를 그린 다음 자식 노드를 확장하여 전체 영역을 덮는 컨테이너입니다(*StyleBox 여백을 고려하여 :ref:`PanelContainer <class_PanelContainer>`를 통해). 가로 및 세로 크기 조정 옵션을 모두 준수합니다.

이 컨테이너는 최상위 컨트롤로 유용하거나 레이아웃 섹션에 사용자 정의 배경을 추가하는 데 유용합니다.

뷰포트

:ref:`FoldableContainer <class_FoldableContainer>`를 통해 확장/축소할 수 있는 컨테이너입니다. 하위 컨트롤은 축소되면 숨겨집니다.

스크롤컨테이너

단일 자식 노드를 허용합니다. 자식 노드가 컨테이너보다 큰 경우 :ref:`ScrollContainer <class_ScrollContainer>`를 통해 노드를 패닝할 수 있도록 스크롤 막대가 추가됩니다. Both vertical and horizontal size options are respected, and the behavior can be turned on or off per axis in the properties.

마우스 휠과 터치 드래그(터치가 가능한 경우)도 하위 컨트롤을 이동하는 유효한 방법입니다.

위의 예에서와 같이 이 컨테이너를 사용하는 가장 일반적인 방법 중 하나는 VBoxContainer를 하위 항목으로 함께 사용하는 것입니다.

뷰포트

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.

이는 동적이고 다양한 화면 크기에 반응해야 하는 컨테이너가 있고 의도한 모양을 잃지 않고 하위 요소의 크기를 비례적으로 조정하려는 경우에 유용합니다.

뷰포트

FlowContainer는 하위 컨트롤을 가로 또는 세로로 정렬하는 컨테이너입니다(HFlowContainer 및 :ref:`VFlowContainer <class_VFlowContainer>`를 통해). 사용 가능한 공간이 부족해지면 책에서 텍스트가 줄바꿈되는 방식과 비슷하게 자식 노드를 다음 줄이나 열로 줄 바꿈합니다.

하위 컨트롤이 겹치지 않고 사용 가능한 공간에 자동으로 조정되는 유연한 레이아웃을 만드는 데 유용합니다.

CenterContainer

CenterContainer는 모든 하위 컨트롤을 자동으로 최소 크기로 중앙에 유지하는 컨테이너입니다. 자식 컨트롤이 항상 중앙에 정렬되도록 보장하므로 수동 위치 지정 없이 중앙 레이아웃을 더 쉽게 만들 수 있습니다(:ref:`CenterContainer <class_CenterContainer>`를 통해).

SubViewportContainer

이는 단일 뷰포트 노드만 하위 항목으로 허용하고 이를 이미지인 것처럼 표시하는 특수 컨트롤입니다(:ref:`SubViewportContainer <class_SubViewportContainer>`를 통해).

커스텀 컨테이너 만들기

스크립트를 사용하여 사용자 정의 컨테이너를 생성할 수 있습니다. 다음은 자식 노드를 해당 크기에 맞는 컨테이너의 예입니다.

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();
    }
}