UI Toolkit : UI Document 활용하기

지난번에는 UI Toolkit을 소개했으면 오늘은 프로그래머가 어떤 식으로 사용하는지에 대해 정리하는 시간입니다.

이번 글은 다음과 같은 순서로 진행됩니다.

1. UI Builder를 활용해서 테스트 UI Document(.uxml) 작성하기
2. 작성한 UI Document를 기반으로 C# 코드 작성하기
3. 씬에서 컴포넌트를 연결 한 후 직접 테스트해보기

---

1. UI Builder를 활용해서 UI Document(. uxml) 작성하기

Project 우클릭 → Create → UI Toolkit → UI Document를 선택해서 새로운 UI Document를 생성합니다.

이름은 TestUIDocument로 설정하겠습니다. (자유입니다.)

생성된 TestUIDocument를 클릭하면 UI Builder 가 열리면서 확인할 수 있습니다.

이번 프로젝트에서는 Style Sheet는 따로 설정하지 않겠습니다.

Hierarchy에서 TestUIDocument.uxml를 클릭 → Inspector에서 Canvas Size를 설정합니다.

저는 1920, 1080으로 설정했습니다.

이제 Library에서 테스트로 사용해 볼 UI 요소들을 하이라키로 가지고 옵니다.

Containers → Visual Element 선택해서 하이라키에 추가합니다.

이름은 #test-main-window로 설정하겠습니다.

이제 그 안쪽으로 다양한 UI 요소들을 추가하겠습니다.

 

Controls → Dropdown을 추가 후 이름은 #test-dropdown으로 설정하겠습니다.

Controls → Label을 추가 후 이름은 #test-label으로 설정하겠습니다.

Controls → Button을 추가 후 이름은 #test-button으로 설정하겠습니다.

Containers → Visual Element를 추가 후 이름은 #test-window로 설정하겠습니다.

#test-window는 Inspector에서 Inlined Styles → Background → Image에 이미지를 연결합니다.

Controls → Toggle을 추가 후 이름은 #test-toggle으로 설정하겠습니다.

Controls → Progress Bar을 추가 후 이름은 #test-progressbar으로 설정하겠습니다.

Controls → Text Field을 추가 후 이름은 #test-textfield로 설정하겠습니다.

 

모든 항목 Inspector에서 Inlined Styles → Text → Size만 50으로 변경했습니다. (보기 좋은 용도)

 

이름 변경은 F2(이름 변경 단축키)를 통해서 하거나 UI 요소를 선택한 후 Inspector 최상단에서 수정 가능합니다.

완성된 TestUIDocument의 모습입니다. → 저와 다르게 원하시는 항목을 추가로 테스트해보세요!

---

2. 작성한 UI Document를 기반으로 C# 코드 작성하기

이제 C#으로 UI 요소를 제어하기 위해 스크립트를 작성하는 시간입니다.

우선 C# 스크립트를 하나 생성합니다. 이름은 TestUI로 하겠습니다.

스크립트의 상단부에는 앞서 UI Document에서 선언한 UIElement 들을 선언합니다.

그리고 기존 유니티 생명주기와 다르게 UI Element 초기화 및 값을 설정하는 부분은 OnEnable()에서 진행합니다.

OnEnable() 안에서 Root Visual Element를 찾아서 가져온 후 해당 Root 안에 있는 요소들을 찾아서 선언한 UI Element와 연결합니다.

그 후 연결 된 UI Element의 값을 수정하는 방식입니다.

(*해당 글에서는 예외처리 부분 포함하지 않았습니다.)

using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using UnityEngine.UIElements;

public class TestUI : MonoBehaviour
{
    // root 요소 선언
    VisualElement root;

    // UI 요소 선언
    Label testLabel;
    Button testButton;
    VisualElement testWindow;
    Toggle testToggle;
    ProgressBar testProgressBar;
    DropdownField testChoice;
    TextField input_test;

    private void OnEnable()
    {   
        // root 요소 찾아서 연결
        root = GetComponent<UIDocument>().rootVisualElement;

        // ui 요소 바인딩
        testLabel = root.Q<Label>("test-label");
        
        testButton = root.Q<Button>("test-button");
        
        testWindow = root.Q<VisualElement>("test-window");
        
        testToggle = root.Q<Toggle>("test-toggle");

        testProgressBar = root.Q<ProgressBar>("test-progressbar");
        testProgressBar.value = 0;

        testChoice = root.Q<DropdownField>("test-dropdown");
        
        input_test = root.Q<TextField>("test-textfield");

        // ui 요소 설정
        testLabel.text = "Test Label !!!";

        testButton.text = "Test Button !!!";
        testButton.RegisterCallback<ClickEvent>(ev =>
        {
            Debug.LogWarning("Test Button Clicked !!!");

            Debug.LogWarning("Input Test Value : " + input_test.value);
        });

        testToggle.value = true;
        testToggle.RegisterValueChangedCallback(evt =>
        {
            Debug.LogWarning("Test Toggle Value : " + evt.newValue);
            testWindow.style.display = evt.newValue ? DisplayStyle.Flex : DisplayStyle.None;
        });

        for (int i = 0; i < 100; i++)
        {
            testProgressBar.value = i % 100;
        }

        List<string> testChoiceList = new List<string>();
        testChoiceList.Add("Test_01");
        testChoiceList.Add("Test_02");
        testChoiceList.Add("Test_03");
        testChoice.choices = testChoiceList;

        testChoice.index = 0;

        testChoice.RegisterValueChangedCallback(ev =>
        {
            Debug.LogWarning("Current Test Choice Index is " + ev.newValue);
        });

        input_test.value = "Input Test Field !!";
    }
}

해당 코드를 확인하면 초반 부분에 Root에서 연결할 때 다음과 같은 코드를 사용합니다.

`testLabel = root.Q<Label>("test-label");`

이 코드를 풀어서 설명하겠습니다.

testLabel에 root에서 Q → Query 쿼리를 통해서 <Label> 타입의 “test-label” 이름을 가진 UI 요소를 가져와서 할당한다입니다.

중반부에 보면 testButton, testToggle, testChoice 에는 Register~~ 하는 코드가 있는데 람다식으로 이벤트를 연결하는 코드로 생각하시면 쉽게 이해할 수 있습니다.

기존 UGUI에서 OnValueChanged 같은 개념입니다.

---

3. 씬에서 컴포넌트를 연결한 후 직접 테스트해보기

이제 다 왔습니다.

생성한 UI Document와 TestUI 스크립트를 통해서 씬에서 직접 확인해 보도록 하겠습니다.

Project에서 Create → UI Toolkit → Panel Settings Asset을 통해서 Panel Settings를 하나 생성합니다.

씬에서 빈 GameObject를 생성한 후 UI Document와 Test UI 컴포넌트를 Add Component 합니다.

아래 사진처럼 UI Document에 Panel Settings와 TestUIDocument.uxml를 연결합니다.

이제 실행하면 로그를 통해서 정상작동 하는지 확인 가능합니다.

더 다양한 기능은 직접 테스트해보시면 좋을 것 같습니다.

감사합니다.