즉시 모드 GUI(IMGUI)에서 UI 툴킷으로 마이그레이션

이 가이드는 즉시 모드 GUI(IMGUI)를 사용하여 UI 툴킷으로 마이그레이션한 경험이 있는 개발자용입니다. 이 가이드는 에디터 UI에 중점을 두고 있지만 정보는 런타임 UI에도 적용될 수 있습니다.

주요 차이점

코드 기반과 UI 기반 비교

IMGUI는 C# 스크립트에서 OnGUI 함수에 대해 호출별 코드 기반으로 구현됩니다. UI 툴킷은 에디터 UI 생성을 위한 더 풍부한 옵션을 제공합니다. UI ㄹ툴킷을 사용하면 C# 스크립트에서 동작을 정의할 수 있습니다. 그러나 UI 요소와 스타일을 정의할 때 C# 외에도 UI 빌더에서 UI 컨트롤을 시각적으로 정의하거나 XML 같은 텍스트 파일(일명 UXML)에 직접 작성할 수 있습니다. 자세한 내용은 간단한 UI 툴킷 워크플로를 참조하십시오.

즉시 모드와 보류 모드 비교

IMGUI를 사용하면 OnGUI() 함수 내에서 UI를 리페인팅할 때 UI 트리를 형성합니다. 서로 다른 이벤트 간에 UI 트리와 관련된 영구적인 정보는 없습니다. 반면 시각적 트리라는 트리 구조에서 UI 툴킷을 사용하여 시각적 요소를 만듭니다. 시각적 트리의 정보는 영구적으로 유지됩니다.

불변과 상태 변화 비교

IMGUI는 매 프레임마다 적어도 한 번은 실행되는 OnGUI() 함수를 기반으로 합니다. 가능한 모든 프레임에 대해 UI의 모양과 동작을 정의합니다. OnGUI()의 바디에는 많은 조건과 다양한 상태가 포함될 수 있습니다.

UI 툴킷은 이벤트 기반 시스템에서 작동합니다. 기본 상태에서 UI의 모양을 정의하고 이벤트에 대한 UI의 동작을 정의합니다. UI 툴킷에서 변경하면 UI 상태가 지속적으로 변경됩니다.

예를 들어 IMGUI의 버튼 선언은 다음과 같습니다.

if (GUILayout.Button("Click me!"))
{
    //Code runs here in frames where the user clicks the button.

    //Code makes changes to the UI for frames where the user has just clicked the button.
}
else
{
    //Code specifies what happens in all other frames.
}

위의 예시는 UI 툴킷에서 다음과 같이 작성되어야 합니다

UIDocument document = GetComponent<UIDocument>();

//Create button.
Button button = new Button();
button.text = "Click me!";

//Set up event handler.
button.RegisterCallback<ClickEvent>((ClickEvent evt) =>
{
    //Code runs here after button receives ClickEvent.
});

//Add button to UI.
document.rootVisualElement.Add(button);

UI 툴킷을 사용하여 커스텀 에디터 창을 만드는 방법에 대한 완성된 예시는 간단한 UI 툴킷 워크플로를 참조하십시오.

IMGUI 지원

IMGUIContainer를 사용하여 IMGUI 코드를 VisualElement 내에 배치하십시오. OnGUI() 내에서 수행하는 대부분의 작업이 지원됩니다.

GUILayout 및 UI 툴킷 레이아웃을 혼합하여 여러 개의 IMGUIContainer를 배열하고 배치할 수 있습니다. 단, IMGUIContainer 내부에 VisualElement 인스턴스를 추가할 수는 없습니다.

IMGUI에서 UI 툴킷으로 전환

다음 표에는 IMGUI와 UI 툴킷 간에 대응하는 함수가 나열되어 있습니다.

액션	IMGUI	UI 툴킷
에디터 창 생성	`EditorWindow.OnGUI()`	`EditorWindow.CreateGUI()`
프로퍼티 드로어 또는 프로퍼티 속성 생성	`PropertyDrawer.OnGUI()`	`PropertyDrawer.CreatePropertyGUI()`
인스펙터용 커스텀 에디터 생성	`Editor.OnInspectorGUI()`	`Editor.CreateInspectorGUI()`

다음 표에는 IMGUI와 UI 툴킷 간에 대응하는 메서드, 클래스, 속성이 나열되어 있습니다.

IMGUI	IMGUI 네임스페이스	UI 툴킷
`AddCursorRect()`	EditorGUIUtility	`VisualElement.style.cursor`를 설정하거나 UI 빌더 또는 USS에서 시각적 요소의 커서 텍스처를 설정합니다. 더 자세한 상호 작용은 C# 이벤트를 사용하십시오.
`AreaScope`	GUILayout	일반적으로 UI 툴킷에서는 범위가 필요하지 않습니다. `BeginArea()`를 참조하십시오.
`BeginArea()`	GUILayout	영역 자체를 정의하려면 시각적 요소를 만들고 `style.position`을 `Position.Absolute`로 설정합니다. 자식 영역을 만들려면 그 아래에 자식 시각적 요소를 만듭니다.
`BeginBuildTargetSelectionGrouping()`	EditorGUILayout	해당 없음
`BeginChangeCheck()`	EditorGUI	변경 사항 확인 범위의 각 요소에 콜백을 등록합니다. `PropertyField`를 커스텀 인스펙터의 직렬화된 필드에 대한 대안으로 사용하는 경우 `PropertyField.RegisterCallback<SerializedPropertyChangeEvent>()` 또는 `PropertyField.RegisterValueChangeCallback()`을 사용합니다. 다른 모든 경우에는 `VisualElement.RegisterCallback<ChangeEvent<T>>()` 또는 `VisualElement.RegisterValueChangedCallback<T>()`을 사용합니다.
`BeginDisabledGroup()`	EditorGUI	`VisualElement.SetEnabled(false)`
`BeginFoldoutHeaderGroup()`	EditorGUI, EditorGUILayout	`Foldout()`을 참조하십시오.
`BeginGroup()`	GUI	`BeginArea()`를 참조하십시오.
`BeginHorizontal()`	EditorGUILayout, GUILayout	`BeginArea()`를 참조하십시오.
`BeginProperty()`	EditorGUI	`BeginProperty()`/`EndProperty()`를 사용하여 직렬화된 프로퍼티에 간단한 컨트롤을 바인딩하는 경우 UI 툴킷에서 `BindProperty()`를 호출하거나 `bindingPath`를 설정하거나 `binding-path` UXML 속성을 설정하여 수행할 수 있습니다. `BeginProperty()`/`EndProperty()`를 사용하여 복잡한 커스텀 UI에서 단일 프로퍼티를 만드는 경우 UI 툴킷에서 완벽히 지원되지 않습니다.
`BeginScrollView()`	EditorGUILayout, GUI, GUILayout	`UnityEngine.UIElements.ScrollView`
`BeginToggleGroup()`	EditorGUILayout	해당 없음
`BeginVertical()`	EditorGUILayout, GUILayout	`BeginArea()`를 참조하십시오.
`BoundsField()`	EditorGUI, EditorGUILayout	`BoundsField`
`BoundsIntField()`	EditorGUI, EditorGUILayout	`BoundsIntField`
`Box()`	GUI, GUILayout	`Box`
`BringWindowToBack()`	GUI	`Window()` 참조.
`BringWindowToFront()`	GUI	`Window()` 참조.
`Button()`	GUI, GUILayout	`Button`
`CanCacheInspectorGUI()`	EditorGUI	보류 모드에서는 필요하지 않습니다.
`ChangeCheckScope`	EditorGUI	일반적으로 UI 툴킷에서는 범위가 필요하지 않습니다. `BeginChangeCheck()`를 참조하십시오.
`ColorField()`	EditorGUI, EditorGUILayout	`ColorField`
`CommandEvent()`	EditorGUIUtility	일반적으로 보류 모드에서는 필요하지 않습니다. 이벤트를 처리하려면 C# 콜백을 사용하십시오.
`CurveField()`	EditorGUI, EditorGUILayout	`CurveField`
`DelayedDoubleField()`	EditorGUI, EditorGUILayout	`isDelayed`가 true로 설정된 `DoubleField`.
`DelayedFloatField()`	EditorGUI, EditorGUILayout	`isDelayed`가 true로 설정된 `FloatField`.
`DelayedIntField()`	EditorGUI, EditorGUILayout	`isDelayed`가 true로 설정된 `IntegerField`.
`DelayedTextField()`	EditorGUI, EditorGUILayout	`isDelayed`가 true로 설정된 `TextField`.
`DisabledScope`	EditorGUI	일반적으로 UI 툴킷에서는 범위가 필요하지 않습니다. `BeginDisabledGroup()`을 참조하십시오.
`DoubleField()`	EditorGUI, EditorGUILayout	`DoubleField`
`DragWindow()`	GUI	`Window()` 참조.
`DrawPreviewTexture()`	EditorGUI	해당 없음
`DrawRect()`	EditorGUI	`VisualElement`를 사용합니다. `style.position`을 `Absolute`로 설정합니다. `style.top` 및 `style.left`를 설정하여 포지션을 정의합니다. `style.width` 및 `style.height`를 설정하여 크기를 정의합니다. `style.backgroundColor`를 설정하여 컬러를 설정합니다.
`DrawTexture()`	GUI	`Image`. `color` 대신 `tintColor`를 설정합니다. `alphaBlend`가 false인 경우 해당 사항 없음. `borderWidth`, `borderWidths`, `borderRadius`, `borderRadiuses`의 경우 해당 사항 없음.
`DrawTextureAlpha()`	EditorGUI	해당 없음
`DrawTextureWithTexCoords()`	GUI	`Image`. `texCoords` 대신 `uv`를 설정합니다. `alphaBlend`가 false인 경우 해당 사항 없음.
`DropdownButton()`	EditorGUI, EditorGUILayout	정확히 대응하지 않습니다. 단순한 `DropdownButton()` 대신 완전한 기능을 갖춘 `DropdownField`를 사용합니다.
`DropShadowLabel()`	EditorGUI	그림자 값이 `style.textShadow`에 설정된 `Label`.
`EditorToolbar()`	EditorGUILayout	각 툴마다 `ToolbarButton`이 하나씩 있는 `Toolbar`를 만듭니다. 각 `ToolbarButton`마다 클릭될 때 콜백을 등록하여 `ToolManager.SetActiveTool()` 또는 `ToolManager.RestorePreviousTool()`을 호출함으로써 해당 버튼이 각각의 툴을 활성화하거나 비활성화하도록 합니다.
`EndArea()`	GUILayout	`BeginArea()`를 참조하십시오.
`EndBuildTargetSelectionGrouping()`	EditorGUILayout	`BeginBuildTargetSelectionGrouping()` 을 참조하십시오.
`EndChangeCheck()`	EditorGUI	`BeginChangeCheck()`를 참조하십시오.
`EndDisabledGroup()`	EditorGUI	`BeginDisabledGroup()`을 참조하십시오.
`EndFoldoutHeaderGroup()`	EditorGUI, EditorGUILayout	`Foldout()`을 참조하십시오.
`EndGroup()`	GUI	`BeginArea()`를 참조하십시오.
`EndHorizontal()`	EditorGUILayout, GUILayout	`BeginArea()`를 참조하십시오.
`EndProperty()`	EditorGUI	`BeginProperty()`를 참조하십시오.
`EndScrollView()`	EditorGUILayout, GUI, GUILayout	`BeginScrollView()`를 참조하십시오.
`EndToggleGroup()`	EditorGUILayout	`BeginToggleGroup()`을 참조하십시오.
`EndVertical()`	EditorGUILayout, GUILayout	`BeginArea()`를 참조하십시오.
`EnumFlagsField()`	EditorGUI, EditorGUILayout	`EnumFlagsField`
`EnumPopup()`	EditorGUI, EditorGUILayout	`EnumField`
`ExpandHeight()`	GUILayout	해당 없음
`ExpandWidth()`	GUILayout	해당 없음
`FlexibleSpace()`	GUILayout	`Space()`를 참조하십시오.
`FloatField()`	EditorGUI, EditorGUILayout	`FloatField`
`FocusControl()`	GUI	`VisualElement.Focus()`
`FocusTextInControl()`	EditorGUI	`TextField.Focus()`
`FocusWindow()`	GUI	`Window()` 참조.
`Foldout()`	EditorGUI, EditorGUILayout	`Foldout`
`GetControlRect()`	EditorGUILayout	EditorGUILayout에서 EditorGUI로 변환하는 데만 필요합니다. UI 툴킷에서는 필요하지 않습니다.
`GetNameOfFocusedControl()`	GUI	`VisualElement.focusController.focusedElement`
`GetPropertyHeight()`	EditorGUI	`PropertyField.layout.height`
`GradientField()`	EditorGUI, EditorGUILayout	`GradientField`
`GroupScope`	GUI	일반적으로 UI 툴킷에서는 범위가 필요하지 않습니다. `BeginArea()`를 참조하십시오.
`Height()`	GUILayout	`VisualElement.style.height`
`HelpBox()`	EditorGUI, EditorGUILayout	`HelpBox`
`HorizontalScope`	EditorGUILayout, GUILayout	일반적으로 UI 툴킷에서는 범위가 필요하지 않습니다. `BeginArea()`를 참조하십시오.
`HorizontalScrollbar()`	GUI, GUILayout	`direction`이 `Horizontal`로 설정된 `Scroller`.
`HorizontalSlider()`	GUI, GUILayout	`direction`이 `Horizontal`로 설정된 `Slider`.
`InspectorTitlebar()`	EditorGUI, EditorGUILayout	해당 없음
`IntField()`	EditorGUI, EditorGUILayout	`IntegerField`
`IntPopup()`	EditorGUI, EditorGUILayout	해당 없음
`IntSlider()`	EditorGUI, EditorGUILayout	`SliderInt`
`Label()`	GUI, GUILayout	`Label`
`LabelField()`	EditorGUI, EditorGUILayout	`isReadOnly`가 true로 설정된 `TextField`.
`LayerField()`	EditorGUI, EditorGUILayout	`LayerField`
`LinkButton()`	EditorGUI, EditorGUILayout	해당 없음
`Load()`	EditorGUIUtility	C#을 사용하는 경우 이 함수를 그대로 사용하고 원하는 `VisualElement.style` 프로퍼티에 반환 값을 할당할 수 있습니다. USS를 사용하는 경우 `Load()`에 지정된 인자와 동일한 인자로 `resource()` 함수를 사용합니다.
`LongField()`	EditorGUI, EditorGUILayout	`LongField`
`MaskField()`	EditorGUI, EditorGUILayout	`MaskField`
`MaxHeight()`	GUILayout	`VisualElement.style.maxHeight`
`MaxWidth()`	GUILayout	`VisualElement.style.maxWidth`
`MinHeight()`	GUILayout	`VisualElement.style.minHeight`
`MinMaxSlider()`	EditorGUI, EditorGUILayout	`MinMaxSlider`
`MinWidth()`	GUILayout	`VisualElement.style.minWidth`
`ModalWindow()`	GUI	`Window()` 참조.
`[NonReorderable]` attribute		`ListView.reorderable`이 false여야 함.
`ObjectField()`	EditorGUI, EditorGUILayout	`ObjectField`
`PasswordField()`	EditorGUI, EditorGUILayout, GUI, GUILayout	`isPasswordField`가 true로 설정된 `TextField`.
`PixelsToPoints()`	EditorGUIUtility	UI 툴킷과 사용 가능.
`PointsToPixels()`	EditorGUIUtility	UI 툴킷과 사용 가능.
`Popup()`	EditorGUI, EditorGUILayout	`PopupField<T0>`
`ProgressBar()`	EditorGUI	`ProgressBar`
`PropertyField()`	EditorGUI, EditorGUILayout	`PropertyField`
`PropertyScope`	EditorGUI	일반적으로 UI 툴킷에서는 범위가 필요하지 않습니다. `BeginProperty()`를 참조하십시오.
`RectField()`	EditorGUI, EditorGUILayout	`RectField`
`RectIntField()`	EditorGUI, EditorGUILayout	`RectIntField`
`RepeatButton()`	GUI, GUILayout	`RepeatButton`
`ScrollTo()`	GUI	`ScrollView.ScrollTo()` 또는 `ScrollView.scrollOffset`
`ScrollViewScope`	EditorGUILayout, GUI, GUILayout	일반적으로 UI 툴킷에서는 범위가 필요하지 않습니다. `BeginScrollView()`를 참조하십시오.
`SelectableLabel()`	EditorGUI, EditorGUILayout	해당 없음
`SelectionGrid()`	GUI, GUILayout	`RadioButton`
`SetNextControlName()`	GUI	`VisualElement.name`
`singleLineHeight`	EditorGUIUtility	USS 변수 `--unity-metrics-single_line-height`를 사용합니다.
`Slider()`	EditorGUI, EditorGUILayout	`Slider`
`Space()`	EditorGUILayout, GUILayout	`flex` 프로퍼티를 사용하여 시각적 요소 사이의 간격을 설정합니다.
`TagField()`	EditorGUI, EditorGUILayout	`TagField`
`TextArea()`	EditorGUI, EditorGUILayout, GUI, GUILayout	`multiline`이 true로 설정되고 `style.whiteSpace`가 `Normal`로 설정된 `TextField`.
`TextField()`	EditorGUI, EditorGUILayout, GUI, GUILayout	`multiline`이 true로 설정되고 `style.whiteSpace`가 `NoWrap`로 설정된 `TextField`.
`Toggle()`	EditorGUI, EditorGUILayout, GUI, GUILayout	`Toggle`
`ToggleGroupScope`	EditorGUILayout	일반적으로 UI 툴킷에서는 범위가 필요하지 않습니다. `BeginToggleGroup()`을 참조하십시오.
`ToggleLeft()`	EditorGUI, EditorGUILayout	`Toggle`, 하지만 `label`을 설정하는 대신 `text`를 설정합니다.
`Toolbar()`	GUI, GUILayout	해당 없음
`UnfocusWindow()`	GUI	`Window()` 참조.
`Vector2Field()`	EditorGUI, EditorGUILayout	`Vector2Field`
`Vector2IntField()`	EditorGUI, EditorGUILayout	`Vector2IntField`
`Vector3Field()`	EditorGUI, EditorGUILayout	`Vector3Field`
`Vector3IntField()`	EditorGUI, EditorGUILayout	`Vector3IntField`
`Vector4Field()`	EditorGUI, EditorGUILayout	`Vector4Field`
`VerticalScope`	EditorGUILayout, GUILayout	일반적으로 UI 툴킷에서는 범위가 필요하지 않습니다. `BeginArea()`를 참조하십시오.
`VerticalScrollbar()`	GUI, GUILayout	`direction`이 `Vertical`로 설정된 `Scroller`.
`VerticalSlider()`	GUI, GUILayout	`direction`이 `Vertical`로 설정된 `Slider`.
`Width()`	GUILayout	`VisualElement.style.width`
`Window()`	GUI, GUILayout	해당 없음

추가 리소스

Unity UI(UGUI)에서 UI 툴킷으로의 마이그레이션

Unity UI

매뉴얼

즉시 모드 GUI(IMGUI)에서 UI 툴킷으로 마이그레이션

주요 차이점

코드 기반과 UI 기반 비교

즉시 모드와 보류 모드 비교

불변과 상태 변화 비교

IMGUI 지원

IMGUI에서 UI 툴킷으로 전환

추가 리소스