Files
XRLib/Assets/Scripts/UVC/UIToolkit/Window/UTKPropertyListWindow.cs
2026-02-19 18:40:37 +09:00

544 lines
22 KiB
C#

#nullable enable
using System;
using System.Collections.Generic;
using System.Linq;
using UnityEngine;
using UnityEngine.UIElements;
namespace UVC.UIToolkit
{
/// <summary>
/// UTKPropertyList를 감싸는 윈도우 래퍼입니다.
/// 헤더(타이틀 + 닫기 버튼), 드래그 이동, 그리고 내부 UTKPropertyList를 통한
/// 속성 목록 관리 기능을 제공합니다.
///
/// <para><b>주요 기능:</b></para>
/// <list type="bullet">
/// <item>윈도우 프레임 (헤더, 타이틀, 닫기 버튼)</item>
/// <item>헤더 드래그로 위치 이동</item>
/// <item>UTKPropertyList 위임 메서드 (데이터 로드, 속성 관리, 값 변경 등)</item>
/// <item>속성 값 변경 / 클릭 / 버튼 클릭 이벤트</item>
/// </list>
///
/// <para><b>관련 리소스:</b></para>
/// <list type="bullet">
/// <item>Resources/UIToolkit/Window/UTKPropertyListWindow.uxml</item>
/// <item>Resources/UIToolkit/Window/UTKPropertyListWindowUss.uss</item>
/// </list>
///
/// <para><b>사용 예 (C#):</b></para>
/// <code>
/// // 1. 윈도우 생성 및 설정
/// var window = new UTKPropertyListWindow("속성 편집기");
/// window.ShowCloseButton = true;
/// window.SetSize(300, 600);
///
/// // 2. 이벤트 구독
/// window.OnCloseClicked += () => window.Hide();
/// window.OnPropertyValueChanged += args =>
/// {
/// Debug.Log($"{args.PropertyId} = {args.NewValue}");
///
/// // 조건부 가시성 제어 예시
/// if (args.PropertyId == "type" &amp;&amp; args.NewValue is string type)
/// {
/// window.SetPropertyVisibilityBatch(new (string, bool)[]
/// {
/// ("option_a", type == "A"),
/// ("option_b", type == "B"),
/// });
/// }
/// };
///
/// // 3. 데이터 로드 (그룹 + 개별 아이템 혼합)
/// var entries = new List<IUTKPropertyEntry>();
/// entries.Add(new UTKStringPropertyItem("name", "이름", "기본값"));
///
/// var group = new UTKPropertyGroup("transform", "Transform");
/// group.AddItem(new UTKVector3PropertyItem("pos", "Position", Vector3.zero));
/// entries.Add(group);
///
/// window.LoadMixedProperties(entries);
///
/// // 4. 런타임 속성 제어
/// window.SetPropertyReadOnly("name", true); // 읽기 전용 전환
/// window.SetPropertyVisibility("pos", false); // 숨김
/// window.UpdatePropertyValue("name", "새 이름"); // 값 변경
///
/// root.Add(window);
/// </code>
///
/// <para><b>사용 예 (UXML):</b></para>
/// <code>
/// <?xml version="1.0" encoding="utf-8"?>
/// <UXML xmlns="UnityEngine.UIElements" xmlns:utk="UVC.UIToolkit">
/// <utk:UTKPropertyListWindow name="property-window" />
/// </UXML>
/// </code>
/// </summary>
[UxmlElement]
public partial class UTKPropertyListWindow : VisualElement, IDisposable
{
#region Constants
private const string UXML_PATH = "UIToolkit/Window/UTKPropertyListWindow";
private const string USS_PATH = "UIToolkit/Window/UTKPropertyListWindowUss";
#endregion
#region Fields
private bool _disposed;
private UTKPropertyList? _propertyList;
private VisualElement? _header;
private UTKLabel? _titleLabel;
private UTKButton? _closeButton;
private string _title = "Properties";
private bool _showCloseButton = false;
private bool _isDragging;
private Vector2 _dragStartPosition;
private Vector2 _dragStartMousePosition;
#endregion
#region Properties
/// <summary>윈도우 타이틀</summary>
public string Title
{
get => _title;
set
{
_title = value;
if (_titleLabel != null)
{
_titleLabel.Text = value;
}
}
}
/// <summary>닫기 버튼 표시 여부</summary>
public bool ShowCloseButton
{
get => _showCloseButton;
set
{
_showCloseButton = value;
if (_closeButton != null)
{
_closeButton.style.display = value ? DisplayStyle.Flex : DisplayStyle.None;
}
}
}
/// <summary>내부 PropertyList 접근</summary>
public UTKPropertyList PropertyList => _propertyList ??= new UTKPropertyList();
#endregion
#region Events
/// <summary>닫기 버튼 클릭 이벤트</summary>
public event Action? OnCloseClicked;
/// <summary>속성 값 변경 이벤트 (PropertyList 위임)</summary>
public event Action<UTKPropertyValueChangedEventArgs>? OnPropertyValueChanged
{
add => PropertyList.OnPropertyValueChanged += value;
remove => PropertyList.OnPropertyValueChanged -= value;
}
/// <summary>그룹 펼침/접힘 이벤트 (PropertyList 위임)</summary>
public event Action<IUTKPropertyGroup, bool>? OnGroupExpandedChanged
{
add => PropertyList.OnGroupExpandedChanged += value;
remove => PropertyList.OnGroupExpandedChanged -= value;
}
/// <summary>속성 클릭 이벤트 (PropertyList 위임)</summary>
public event Action<IUTKPropertyItem>? OnPropertyClicked
{
add => PropertyList.OnPropertyClicked += value;
remove => PropertyList.OnPropertyClicked -= value;
}
/// <summary>버튼 클릭 이벤트 (PropertyList 위임)</summary>
public event Action<string, string>? OnPropertyButtonClicked
{
add => PropertyList.OnPropertyButtonClicked += value;
remove => PropertyList.OnPropertyButtonClicked -= value;
}
#endregion
#region Constructor
public UTKPropertyListWindow()
{
UTKThemeManager.Instance.ApplyThemeToElement(this);
SubscribeToThemeChanges();
var styleSheet = Resources.Load<StyleSheet>(USS_PATH);
if (styleSheet != null)
{
styleSheets.Add(styleSheet);
}
CreateUI();
}
public UTKPropertyListWindow(string title) : this()
{
Title = title;
}
#endregion
#region UI Creation
private void CreateUI()
{
AddToClassList("utk-property-window");
var asset = Resources.Load<VisualTreeAsset>(UXML_PATH);
if (asset != null)
{
CreateUIFromUxml(asset);
}
else
{
CreateUIFallback();
}
// 드래그 이벤트
if (_header != null)
{
_header.RegisterCallback<PointerDownEvent>(OnHeaderPointerDown);
_header.RegisterCallback<PointerMoveEvent>(OnHeaderPointerMove);
_header.RegisterCallback<PointerUpEvent>(OnHeaderPointerUp);
}
}
private void CreateUIFromUxml(VisualTreeAsset asset)
{
var root = asset.Instantiate();
var windowRoot = root.Q<VisualElement>("window-root");
if (windowRoot != null)
{
// windowRoot의 자식들을 현재 요소로 이동
foreach (var child in windowRoot.Children().ToArray())
{
Add(child);
}
}
else
{
// window-root가 없으면 전체 추가
Add(root);
}
// 요소 참조 가져오기
_header = this.Q<VisualElement>("header");
_titleLabel = this.Q<UTKLabel>("title");
_closeButton = this.Q<UTKButton>("close-btn");
_propertyList = this.Q<UTKPropertyList>("content");
// 타이틀 설정
if (_titleLabel != null)
{
_titleLabel.Text = _title;
_titleLabel.Size = UTKLabel.LabelSize.Label3;
}
// 닫기 버튼 설정
if (_closeButton != null)
{
_closeButton.SetMaterialIcon(UTKMaterialIcons.Close, 14);
_closeButton.IconOnly = true;
_closeButton.OnClicked += () => OnCloseClicked?.Invoke();
_closeButton.style.display = _showCloseButton ? DisplayStyle.Flex : DisplayStyle.None;
}
// PropertyList가 없으면 생성
if (_propertyList == null)
{
_propertyList = new UTKPropertyList();
_propertyList.name = "content";
_propertyList.AddToClassList("utk-property-window__content");
Add(_propertyList);
}
}
private void CreateUIFallback()
{
// 헤더
_header = new VisualElement();
_header.name = "header";
_header.AddToClassList("utk-property-window__header");
_titleLabel = new UTKLabel(_title, UTKLabel.LabelSize.Label3);
_titleLabel.name = "title";
_titleLabel.AddToClassList("utk-property-window__title");
_header.Add(_titleLabel);
_closeButton = new UTKButton("", UTKMaterialIcons.Close, UTKButton.ButtonVariant.Text, 14);
_closeButton.name = "close-btn";
_closeButton.IconOnly = true;
_closeButton.AddToClassList("utk-property-window__close-btn");
_closeButton.OnClicked += () => OnCloseClicked?.Invoke();
_header.Add(_closeButton);
Add(_header);
// PropertyList
_propertyList = new UTKPropertyList();
_propertyList.AddToClassList("utk-property-window__content");
Add(_propertyList);
}
#endregion
#region Public Methods - Data Loading (PropertyList )
/// <summary>평면 속성 목록을 로드합니다 (그룹 없이).</summary>
/// <param name="items">로드할 속성 아이템 목록.</param>
public void LoadProperties(List<IUTKPropertyItem> items) => PropertyList.LoadProperties(items);
/// <summary>그룹화된 속성 목록을 로드합니다.</summary>
/// <param name="groups">로드할 속성 그룹 목록.</param>
public void LoadGroupedProperties(List<IUTKPropertyGroup> groups) => PropertyList.LoadGroupedProperties(groups);
/// <summary>그룹과 개별 아이템이 혼합된 엔트리 목록을 로드합니다.</summary>
/// <param name="entries">로드할 엔트리 목록 (IUTKPropertyGroup 또는 IUTKPropertyItem).</param>
public void LoadMixedProperties(List<IUTKPropertyEntry> entries) => PropertyList.LoadMixedProperties(entries);
#endregion
#region Public Methods - Group Management (PropertyList )
/// <summary>그룹을 추가합니다.</summary>
/// <param name="group">추가할 속성 그룹.</param>
public void AddGroup(IUTKPropertyGroup group) => PropertyList.AddGroup(group);
/// <summary>지정한 ID의 그룹과 내부 아이템을 모두 제거합니다.</summary>
/// <param name="groupId">제거할 그룹 ID.</param>
public void RemoveGroup(string groupId) => PropertyList.RemoveGroup(groupId);
/// <summary>지정한 ID의 그룹을 반환합니다.</summary>
/// <param name="groupId">조회할 그룹 ID.</param>
/// <returns>그룹 인스턴스 또는 null.</returns>
public IUTKPropertyGroup? GetGroup(string groupId) => PropertyList.GetGroup(groupId);
/// <summary>그룹의 펼침/접힘 상태를 설정합니다.</summary>
/// <param name="groupId">대상 그룹 ID.</param>
/// <param name="expanded">true면 펼침, false면 접힘.</param>
public void SetGroupExpanded(string groupId, bool expanded) => PropertyList.SetGroupExpanded(groupId, expanded);
/// <summary>그룹의 펼침/접힘 상태를 토글합니다.</summary>
/// <param name="groupId">대상 그룹 ID.</param>
public void ToggleGroupExpanded(string groupId) => PropertyList.ToggleGroupExpanded(groupId);
#endregion
#region Public Methods - Property Management (PropertyList )
/// <summary>최상위 속성 아이템을 추가합니다.</summary>
/// <param name="item">추가할 속성 아이템.</param>
public void AddProperty(IUTKPropertyItem item) => PropertyList.AddProperty(item);
/// <summary>지정한 그룹에 속성 아이템을 추가합니다.</summary>
/// <param name="groupId">대상 그룹 ID.</param>
/// <param name="item">추가할 속성 아이템.</param>
public void AddPropertyToGroup(string groupId, IUTKPropertyItem item) => PropertyList.AddPropertyToGroup(groupId, item);
/// <summary>지정한 ID의 속성 아이템을 제거합니다.</summary>
/// <param name="itemId">제거할 아이템 ID.</param>
public void RemoveProperty(string itemId) => PropertyList.RemoveProperty(itemId);
/// <summary>지정한 ID의 속성 아이템을 반환합니다.</summary>
/// <param name="itemId">조회할 아이템 ID.</param>
/// <returns>아이템 인스턴스 또는 null.</returns>
public IUTKPropertyItem? GetProperty(string itemId) => PropertyList.GetProperty(itemId);
#endregion
#region Public Methods - Value Management (PropertyList )
/// <summary>속성 값을 변경합니다. 바인딩된 View에 자동 반영됩니다.</summary>
/// <param name="propertyId">대상 속성 ID.</param>
/// <param name="newValue">새 값 (타입 변환 자동 시도).</param>
/// <param name="notify">true면 값 변경 알림 이벤트 발생.</param>
public void UpdatePropertyValue(string propertyId, object newValue, bool notify = false) => PropertyList.UpdatePropertyValue(propertyId, newValue, notify);
/// <summary>속성 값을 변경합니다. <see cref="UpdatePropertyValue"/>의 별칭입니다.</summary>
/// <param name="propertyId">대상 속성 ID.</param>
/// <param name="value">새 값.</param>
/// <param name="notify">true면 값 변경 알림 이벤트 발생.</param>
public void SetPropertyValue(string propertyId, object value, bool notify = false) => PropertyList.SetPropertyValue(propertyId, value, notify);
#endregion
#region Public Methods - Visibility & ReadOnly (PropertyList )
/// <summary>속성 아이템의 가시성을 변경합니다. TreeView Rebuild가 발생합니다.</summary>
/// <param name="propertyId">대상 속성 ID.</param>
/// <param name="visible">true면 표시, false면 숨김.</param>
public void SetPropertyVisibility(string propertyId, bool visible) => PropertyList.SetPropertyVisibility(propertyId, visible);
/// <summary>여러 속성의 가시성을 일괄 변경합니다. TreeView는 마지막에 한 번만 갱신됩니다.</summary>
/// <param name="changes">변경할 (속성 ID, 가시성) 튜플 목록.</param>
public void SetPropertyVisibilityBatch(IEnumerable<(string propertyId, bool visible)> changes) => PropertyList.SetPropertyVisibilityBatch(changes);
/// <summary>그룹의 가시성을 변경합니다. TreeView Rebuild가 발생합니다.</summary>
/// <param name="groupId">대상 그룹 ID.</param>
/// <param name="visible">true면 표시, false면 숨김.</param>
public void SetGroupVisibility(string groupId, bool visible) => PropertyList.SetGroupVisibility(groupId, visible);
/// <summary>속성 아이템의 읽기 전용 상태를 변경합니다. OnStateChanged로 View에 자동 반영됩니다.</summary>
/// <param name="propertyId">대상 속성 ID.</param>
/// <param name="isReadOnly">true면 읽기 전용.</param>
public void SetPropertyReadOnly(string propertyId, bool isReadOnly) => PropertyList.SetPropertyReadOnly(propertyId, isReadOnly);
/// <summary>그룹 내 모든 아이템의 읽기 전용 상태를 일괄 변경합니다.</summary>
/// <param name="groupId">대상 그룹 ID.</param>
/// <param name="isReadOnly">true면 읽기 전용.</param>
public void SetGroupReadOnly(string groupId, bool isReadOnly) => PropertyList.SetGroupReadOnly(groupId, isReadOnly);
#endregion
#region Public Methods - Utilities (PropertyList )
/// <summary>모든 엔트리(그룹 + 아이템)를 제거하고 초기화합니다.</summary>
public void Clear() => PropertyList.Clear();
/// <summary>현재 데이터를 기반으로 TreeView를 다시 빌드합니다.</summary>
public void Refresh() => PropertyList.Refresh();
#endregion
#region Public Methods - Window
/// <summary>윈도우를 표시합니다.</summary>
public void Show()
{
style.display = DisplayStyle.Flex;
}
/// <summary>윈도우를 숨깁니다.</summary>
public void Hide()
{
style.display = DisplayStyle.None;
}
/// <summary>
/// 윈도우의 위치를 설정합니다 (absolute 포지셔닝).
/// </summary>
/// <param name="x">왼쪽 오프셋 (px).</param>
/// <param name="y">상단 오프셋 (px).</param>
public void SetPosition(float x, float y)
{
style.left = x;
style.top = y;
}
/// <summary>
/// 윈도우의 크기를 설정합니다.
/// </summary>
/// <param name="width">너비 (px).</param>
/// <param name="height">높이 (px).</param>
public void SetSize(float width, float height)
{
style.width = width;
style.height = height;
}
/// <summary>
/// 부모 요소 기준으로 윈도우를 중앙에 배치합니다.
/// schedule.Execute로 다음 프레임에 실행됩니다.
/// </summary>
public void CenterOnScreen()
{
schedule.Execute(() =>
{
var parent = this.parent;
if (parent == null) return;
float parentWidth = parent.resolvedStyle.width;
float parentHeight = parent.resolvedStyle.height;
float selfWidth = resolvedStyle.width;
float selfHeight = resolvedStyle.height;
style.left = (parentWidth - selfWidth) / 2;
style.top = (parentHeight - selfHeight) / 2;
});
}
#endregion
#region Dragging
private void OnHeaderPointerDown(PointerDownEvent evt)
{
if (evt.button != 0) return;
_isDragging = true;
_dragStartPosition = new Vector2(resolvedStyle.left, resolvedStyle.top);
_dragStartMousePosition = evt.position;
_header?.CapturePointer(evt.pointerId);
}
private void OnHeaderPointerMove(PointerMoveEvent evt)
{
if (!_isDragging) return;
Vector2 delta = (Vector2)evt.position - _dragStartMousePosition;
style.left = _dragStartPosition.x + delta.x;
style.top = _dragStartPosition.y + delta.y;
}
private void OnHeaderPointerUp(PointerUpEvent evt)
{
if (!_isDragging) return;
_isDragging = false;
_header?.ReleasePointer(evt.pointerId);
}
#endregion
#region (Theme)
private void SubscribeToThemeChanges()
{
UTKThemeManager.Instance.OnThemeChanged += OnThemeChanged;
RegisterCallback<AttachToPanelEvent>(OnAttachToPanelForTheme);
RegisterCallback<DetachFromPanelEvent>(OnDetachFromPanelForTheme);
}
private void OnAttachToPanelForTheme(AttachToPanelEvent evt)
{
UTKThemeManager.Instance.OnThemeChanged -= OnThemeChanged;
UTKThemeManager.Instance.OnThemeChanged += OnThemeChanged;
UTKThemeManager.Instance.ApplyThemeToElement(this);
}
private void OnDetachFromPanelForTheme(DetachFromPanelEvent evt)
{
UTKThemeManager.Instance.OnThemeChanged -= OnThemeChanged;
}
private void OnThemeChanged(UTKTheme theme)
{
UTKThemeManager.Instance.ApplyThemeToElement(this);
}
#endregion
#region IDisposable
public void Dispose()
{
if (_disposed) return;
_disposed = true;
// 테마 변경 이벤트 해제
UTKThemeManager.Instance.OnThemeChanged -= OnThemeChanged;
UnregisterCallback<AttachToPanelEvent>(OnAttachToPanelForTheme);
UnregisterCallback<DetachFromPanelEvent>(OnDetachFromPanelForTheme);
// 드래그 이벤트 해제
if (_header != null)
{
_header.UnregisterCallback<PointerDownEvent>(OnHeaderPointerDown);
_header.UnregisterCallback<PointerMoveEvent>(OnHeaderPointerMove);
_header.UnregisterCallback<PointerUpEvent>(OnHeaderPointerUp);
}
// PropertyList 정리
_propertyList?.Dispose();
_propertyList = null;
// 이벤트 정리
OnCloseClicked = null;
// UI 참조 정리
_header = null;
_titleLabel = null;
_closeButton = null;
}
#endregion
}
}