Version: 2023.1
언어: 한국어
Unity UI(uGUI)에서 UI 툴킷으로 마이그레이션
Unity UI

즉시 모드 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 인스턴스를 추가할 수는 없습니다.

IMGUIContainer 예시
IMGUIContainer 예시

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.positionPosition.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.positionAbsolute로 설정합니다. style.topstyle.left를 설정하여 포지션을 정의합니다. style.widthstyle.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 directionHorizontal로 설정된 Scroller.
HorizontalSlider() GUI, GUILayout directionHorizontal로 설정된 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 isSelectablefocusable이 true로 설정된 Label.
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.whiteSpaceNormal로 설정되고, ScrollView.verticalScrollerVisibilityAuto로 설정된 TextField.
TextField() EditorGUI, EditorGUILayout, GUI, GUILayout multiline이 true로 설정되고 style.whiteSpaceNoWrap로 설정된 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 directionVertical로 설정된 Scroller.
VerticalSlider() GUI, GUILayout directionVertical로 설정된 Slider.
Width() GUILayout VisualElement.style.width
Window() GUI, GUILayout 해당 없음

추가 리소스

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