Files
XRLib/Assets/Scripts/UVC/UIToolkit/Button/UTKButton.cs
2026-01-13 20:39:45 +09:00

670 lines
22 KiB
C#

#nullable enable
using System;
using System.Threading;
using Cysharp.Threading.Tasks;
using UnityEngine;
using UnityEngine.UIElements;
namespace UVC.UIToolkit
{
/// <summary>
/// 커스텀 버튼 컴포넌트.
/// 텍스트와 아이콘을 동시에 표시하거나, 아이콘만 표시할 수 있습니다.
/// 배경 색상, 외곽선 굵기 등을 설정할 수 있습니다.
/// </summary>
/// <example>
/// <para><b>C# 코드에서 사용:</b></para>
/// <code>
/// // 기본 버튼 생성
/// var btn = new UTKButton("확인");
/// btn.OnClicked += () => Debug.Log("클릭됨!");
///
/// // 텍스트와 Material Icon이 있는 버튼
/// var saveBtn = new UTKButton("저장", UTKMaterialIcons.Save, UTKButton.ButtonVariant.Primary);
///
/// // 텍스트와 아이콘 (크기 지정)
/// var largeIconBtn = new UTKButton("설정", UTKMaterialIcons.Settings, UTKButton.ButtonVariant.Primary, 28);
/// var smallImageBtn = new UTKButton("닫기", UTKImageIcons.BtnClose22, UTKButton.ButtonVariant.Danger, 20);
///
/// // Material Icon 설정
/// // 텍스트와 아이콘 (크기 지정)
/// var largeIconBtn = new UTKButton("설정", UTKMaterialIcons.Settings, UTKButton.ButtonVariant.Primary, 28);
/// var smallImageBtn = new UTKButton("닫기", UTKImageIcons.BtnClose22, UTKButton.ButtonVariant.Danger, 20);
///
/// // Text 버튼 스타일에서 아이콘 크기 지정
/// var textSmallIcon = new UTKButton("Small", UTKMaterialIcons.Settings, UTKButton.ButtonVariant.Text, 16);
/// var textMediumIcon = new UTKButton("Medium", UTKMaterialIcons.Settings, UTKButton.ButtonVariant.Text, 24);
/// var textLargeIcon = new UTKButton("Large", UTKMaterialIcons.Settings, UTKButton.ButtonVariant.Text, 32);
///
/// // Material Icon 설정
/// var imgBtn = new UTKButton("닫기");
/// imgBtn.SetImageIcon(UTKImageIcons.BtnClose22);
/// imgBtn.SetImageIconByName("icon_setting_22");
///
/// // 비동기 아이콘 설정
/// await btn.SetMaterialIconAsync(UTKMaterialIcons.Search);
/// await btn.SetImageIconAsync(UTKImageIcons.IconSetting22);
///
/// // 아이콘만 표시하는 버튼
/// var iconOnlyBtn = new UTKButton { IconOnly = true };
/// iconOnlyBtn.SetMaterialIcon(UTKMaterialIcons.Close);
///
/// // 버튼 스타일 변형
/// btn.Variant = UTKButton.ButtonVariant.Primary;
/// btn.Variant = UTKButton.ButtonVariant.Danger;
/// btn.Variant = UTKButton.ButtonVariant.Ghost;
///
/// // 버튼 크기
/// btn.Size = UTKButton.ButtonSize.Small;
/// btn.Size = UTKButton.ButtonSize.Large;
///
/// // 주의: 생성자에서 icon 파라미터로 아이콘을 전달하면 다음 순서로 타입이 감지됩니다.
/// // 1. UTKMaterialIcons에서 먼저 검사 (Material Symbols Outlined 아이콘)
/// // 2. UTKImageIcons에서 검사 (이미지 기반 아이콘)
/// // 3. 둘 다 아니면 텍스트로 처리됨
///
/// // 아이콘 제거
/// btn.ClearIcon();
/// </code>
/// <para><b>UXML에서 사용:</b></para>
/// <code>
/// <!-- 네임스페이스 선언 -->
/// <ui:UXML xmlns:utk="UVC.UIToolkit">
///
/// <!-- 기본 버튼 -->
/// <utk:UTKButton Text="확인" />
///
/// <!-- Material Icon 버튼 (유니코드 직접 입력) -->
/// <utk:UTKButton Text="설정" Icon="&#xe8b8;" />
///
/// <!-- 버튼 변형 -->
/// <utk:UTKButton Text="저장" Variant="Primary" />
/// <utk:UTKButton Text="삭제" Variant="Danger" />
/// <utk:UTKButton Text="취소" Variant="Ghost" />
/// <utk:UTKButton Text="링크" Variant="Text" />
///
/// <!-- 외곽선 변형 -->
/// <utk:UTKButton Text="확인" Variant="OutlinePrimary" />
/// <utk:UTKButton Text="삭제" Variant="OutlineDanger" />
///
/// <!-- 크기 변형 -->
/// <utk:UTKButton Text="작은 버튼" Size="Small" />
/// <utk:UTKButton Text="큰 버튼" Size="Large" />
///
/// <!-- 아이콘만 표시 -->
/// <utk:UTKButton Icon="&#xe5cd;" IconOnly="true" />
/// <utk:UTKButton Text="" Icon="Close" Variant="Text" IconSize="12" />
///
/// <!-- 비활성화 -->
/// <utk:UTKButton Text="비활성화" IsEnabled="false" />
///
/// <!-- 외곽선 굵기 -->
/// <utk:UTKButton Text="두꺼운 외곽선" BorderWidth="2" />
///
/// </ui:UXML>
/// </code>
/// <para><b>UXML에서 로드 후 C#에서 아이콘 설정:</b></para>
/// <code>
/// var root = GetComponent<UIDocument>().rootVisualElement;
/// var btn = root.Q<UTKButton>("my-button");
/// btn.SetMaterialIcon(UTKMaterialIcons.Settings);
/// </code>
/// </example>
[UxmlElement]
public partial class UTKButton : VisualElement, IDisposable
{
#region Constants
private const string USS_PATH = "UIToolkit/Button/UTKButton";
#endregion
#region Fields
private bool _disposed;
private Label? _iconLabel;
private Label? _textLabel;
private VisualElement? _imageIcon;
private string _text = "";
private string _icon = "";
private ButtonVariant _variant = ButtonVariant.Normal;
private ButtonSize _size = ButtonSize.Medium;
private Color? _backgroundColor;
private int _borderWidth = -1;
private bool _iconOnly;
private bool _isEnabled = true;
#endregion
#region Events
/// <summary>버튼 클릭 이벤트</summary>
public event Action? OnClicked;
#endregion
#region Properties
/// <summary>버튼 텍스트</summary>
[UxmlAttribute]
public string Text
{
get => _text;
set
{
_text = value;
UpdateContent();
}
}
/// <summary>아이콘 (유니코드 문자 또는 텍스트)</summary>
[UxmlAttribute]
public string Icon
{
get => _icon;
set
{
_icon = value;
UpdateContent();
}
}
/// <summary>버튼 스타일 변형</summary>
[UxmlAttribute]
public ButtonVariant Variant
{
get => _variant;
set
{
_variant = value;
UpdateVariant();
}
}
/// <summary>버튼 크기</summary>
[UxmlAttribute]
public ButtonSize Size
{
get => _size;
set
{
_size = value;
UpdateSize();
}
}
/// <summary>커스텀 배경 색상 (null이면 기본 스타일 사용)</summary>
public Color? BackgroundColor
{
get => _backgroundColor;
set
{
_backgroundColor = value;
UpdateCustomStyles();
}
}
/// <summary>외곽선 굵기 (-1이면 기본값 사용)</summary>
[UxmlAttribute]
public int BorderWidth
{
get => _borderWidth;
set
{
_borderWidth = value;
UpdateCustomStyles();
}
}
/// <summary>아이콘만 표시 모드</summary>
[UxmlAttribute]
public bool IconOnly
{
get => _iconOnly;
set
{
_iconOnly = value;
UpdateContent();
}
}
/// <summary>버튼 활성화 상태</summary>
[UxmlAttribute]
public bool IsEnabled
{
get => _isEnabled;
set
{
_isEnabled = value;
SetEnabled(value);
EnableInClassList("utk-button--disabled", !value);
}
}
#endregion
#region Enums
public enum ButtonVariant
{
Normal,
Primary,
Secondary,
Ghost,
Danger,
OutlineNormal,
OutlinePrimary,
OutlineDanger,
/// <summary>배경과 외곽선이 투명하고 텍스트/아이콘만 표시</summary>
Text
}
public enum ButtonSize
{
Small,
Medium,
Large
}
#endregion
#region Constructor
public UTKButton()
{
UTKThemeManager.Instance.ApplyThemeToElement(this);
var uss = Resources.Load<StyleSheet>(USS_PATH);
if (uss != null)
{
styleSheets.Add(uss);
}
CreateUI();
SetupEvents();
SubscribeToThemeChanges();
// UXML에서 로드될 때 속성이 설정된 후 UI 갱신
RegisterCallback<AttachToPanelEvent>(_ =>
{
UpdateContent();
UpdateVariant();
UpdateSize();
});
}
/// <summary>
/// 텍스트, 아이콘, 변형, 크기를 설정하여 버튼을 생성합니다.
/// </summary>
/// <param name="text">버튼에 표시할 텍스트</param>
/// <param name="icon">아이콘 이름 또는 경로 (Material Icon 또는 Image Icon)</param>
/// <param name="variant">버튼 스타일 변형</param>
/// <param name="iconSize">아이콘 크기 (생략 시 기본값 사용)</param>
/// <remarks>
/// 아이콘 타입 감지 순서:
/// 1. UTKMaterialIcons 검사 (Material Symbols Outlined 아이콘)
/// 2. UTKImageIcons 검사 (이미지 기반 아이콘)
/// 3. 둘 다 아니면 텍스트로 처리됨
/// </remarks>
public UTKButton(string text, string icon = "", ButtonVariant variant = ButtonVariant.Normal, int? iconSize = null) : this()
{
_text = text;
_icon = icon;
_variant = variant;
UpdateContent();
UpdateVariant();
// 아이콘 타입 자동 감지 및 적용
if (!string.IsNullOrEmpty(icon))
{
// 1순위: UTKMaterialIcons에 해당하는지 확인
if (UTKMaterialIcons.GetIcon(icon) != null)
{
SetMaterialIcon(icon, iconSize);
}
// 2순위: UTKImageIcons에 해당하는지 확인
else if (!string.IsNullOrEmpty(UTKImageIcons.GetPath(icon)))
{
SetImageIcon(icon, iconSize);
}
// 3순위: 둘 다 아니면 현재 로직 유지 (UpdateContent에서 이미 처리됨)
}
}
#endregion
#region UI Creation
private void CreateUI()
{
AddToClassList("utk-button");
focusable = true;
pickingMode = PickingMode.Position;
_iconLabel = new Label
{
name = "icon",
pickingMode = PickingMode.Ignore
};
_iconLabel.AddToClassList("utk-button__icon");
Add(_iconLabel);
_textLabel = new Label
{
name = "text",
pickingMode = PickingMode.Ignore
};
_textLabel.AddToClassList("utk-button__text");
Add(_textLabel);
UpdateContent();
UpdateVariant();
UpdateSize();
}
private void SetupEvents()
{
RegisterCallback<ClickEvent>(OnClick);
RegisterCallback<KeyDownEvent>(OnKeyDown);
}
private void SubscribeToThemeChanges()
{
UTKThemeManager.Instance.OnThemeChanged += OnThemeChanged;
RegisterCallback<DetachFromPanelEvent>(_ =>
{
UTKThemeManager.Instance.OnThemeChanged -= OnThemeChanged;
});
}
private void OnThemeChanged(UTKTheme theme)
{
UTKThemeManager.Instance.ApplyThemeToElement(this);
}
#endregion
#region Event Handlers
private void OnClick(ClickEvent evt)
{
if (!_isEnabled) return;
OnClicked?.Invoke();
evt.StopPropagation();
}
private void OnKeyDown(KeyDownEvent evt)
{
if (!_isEnabled) return;
if (evt.keyCode == KeyCode.Return || evt.keyCode == KeyCode.Space)
{
OnClicked?.Invoke();
evt.StopPropagation();
}
}
#endregion
#region Update Methods
private void UpdateContent()
{
bool hasIcon = !string.IsNullOrEmpty(_icon);
bool hasText = !string.IsNullOrEmpty(_text);
if (_iconLabel != null)
{
_iconLabel.text = _icon;
_iconLabel.style.display = hasIcon ? DisplayStyle.Flex : DisplayStyle.None;
}
if (_textLabel != null)
{
_textLabel.text = _text;
_textLabel.style.display = (_iconOnly || !hasText) ? DisplayStyle.None : DisplayStyle.Flex;
}
EnableInClassList("utk-button--icon-only", _iconOnly || (hasIcon && !hasText));
EnableInClassList("utk-button--has-icon", hasIcon && hasText && !_iconOnly);
}
private void UpdateVariant()
{
RemoveFromClassList("utk-button--normal");
RemoveFromClassList("utk-button--primary");
RemoveFromClassList("utk-button--secondary");
RemoveFromClassList("utk-button--ghost");
RemoveFromClassList("utk-button--danger");
RemoveFromClassList("utk-button--outline-normal");
RemoveFromClassList("utk-button--outline-primary");
RemoveFromClassList("utk-button--outline-danger");
RemoveFromClassList("utk-button--text");
var variantClass = _variant switch
{
ButtonVariant.Primary => "utk-button--primary",
ButtonVariant.Secondary => "utk-button--secondary",
ButtonVariant.Ghost => "utk-button--ghost",
ButtonVariant.Danger => "utk-button--danger",
ButtonVariant.OutlineNormal => "utk-button--outline-normal",
ButtonVariant.OutlinePrimary => "utk-button--outline-primary",
ButtonVariant.OutlineDanger => "utk-button--outline-danger",
ButtonVariant.Text => "utk-button--text",
_ => "utk-button--normal"
};
AddToClassList(variantClass);
}
private void UpdateSize()
{
RemoveFromClassList("utk-button--small");
RemoveFromClassList("utk-button--medium");
RemoveFromClassList("utk-button--large");
var sizeClass = _size switch
{
ButtonSize.Small => "utk-button--small",
ButtonSize.Large => "utk-button--large",
_ => "utk-button--medium"
};
AddToClassList(sizeClass);
}
private void UpdateCustomStyles()
{
if (_backgroundColor.HasValue)
{
style.backgroundColor = _backgroundColor.Value;
}
else
{
style.backgroundColor = StyleKeyword.Null;
}
if (_borderWidth >= 0)
{
style.borderTopWidth = _borderWidth;
style.borderBottomWidth = _borderWidth;
style.borderLeftWidth = _borderWidth;
style.borderRightWidth = _borderWidth;
}
else
{
style.borderTopWidth = StyleKeyword.Null;
style.borderBottomWidth = StyleKeyword.Null;
style.borderLeftWidth = StyleKeyword.Null;
style.borderRightWidth = StyleKeyword.Null;
}
}
#endregion
#region Icon Methods
/// <summary>
/// Material Icon을 설정합니다.
/// </summary>
/// <param name="icon">Material Icon 유니코드 문자 (예: UTKMaterialIcons.Settings)</param>
/// <param name="fontSize">아이콘 폰트 크기 (null이면 버튼 크기에 맞춤)</param>
public void SetMaterialIcon(string icon, int? fontSize = null)
{
ClearImageIcon();
Icon = icon;
if (_iconLabel != null)
{
UTKMaterialIcons.ApplyIconStyle(_iconLabel, fontSize ?? GetDefaultIconSize());
}
}
/// <summary>
/// Material Icon을 비동기로 설정합니다.
/// </summary>
/// <param name="icon">Material Icon 유니코드 문자 (예: UTKMaterialIcons.Settings)</param>
/// <param name="ct">취소 토큰</param>
/// <param name="fontSize">아이콘 폰트 크기 (null이면 버튼 크기에 맞춤)</param>
public async UniTask SetMaterialIconAsync(string icon, CancellationToken ct = default, int? fontSize = null)
{
ClearImageIcon();
Icon = icon;
if (_iconLabel != null)
{
await UTKMaterialIcons.ApplyIconStyleAsync(_iconLabel, ct, fontSize ?? GetDefaultIconSize());
}
}
/// <summary>
/// 아이콘 이름으로 Material Icon을 설정합니다.
/// </summary>
/// <param name="iconName">아이콘 이름 (예: "settings", "home")</param>
/// <param name="fontSize">아이콘 폰트 크기 (null이면 버튼 크기에 맞춤)</param>
public void SetMaterialIconByName(string iconName, int? fontSize = null)
{
var iconChar = UTKMaterialIcons.GetIcon(iconName);
if (!string.IsNullOrEmpty(iconChar))
{
SetMaterialIcon(iconChar, fontSize);
}
else
{
Debug.LogWarning($"[UTKButton] Material icon '{iconName}'을(를) 찾을 수 없습니다.");
}
}
/// <summary>
/// Image Icon을 설정합니다.
/// </summary>
/// <param name="resourcePath">이미지 리소스 경로 (예: UTKImageIcons.IconSetting22)</param>
/// <param name="iconSize">아이콘 크기 (null이면 버튼 크기에 맞춤)</param>
public void SetImageIcon(string resourcePath, int? iconSize = null)
{
var texture = UTKImageIcons.LoadTexture(resourcePath);
if (texture != null)
{
ApplyImageIcon(texture, iconSize);
}
else
{
Debug.LogWarning($"[UTKButton] Image icon '{resourcePath}'을(를) 로드할 수 없습니다.");
}
}
/// <summary>
/// Image Icon을 비동기로 설정합니다.
/// </summary>
/// <param name="resourcePath">이미지 리소스 경로 (예: UTKImageIcons.IconSetting22)</param>
/// <param name="ct">취소 토큰</param>
/// <param name="iconSize">아이콘 크기 (null이면 버튼 크기에 맞춤)</param>
public async UniTask SetImageIconAsync(string resourcePath, CancellationToken ct = default, int? iconSize = null)
{
var texture = await UTKImageIcons.LoadTextureAsync(resourcePath, ct);
if (texture != null)
{
ApplyImageIcon(texture, iconSize);
}
else
{
Debug.LogWarning($"[UTKButton] Image icon '{resourcePath}'을(를) 로드할 수 없습니다.");
}
}
/// <summary>
/// 아이콘 이름으로 Image Icon을 설정합니다.
/// </summary>
/// <param name="iconName">아이콘 이름 (예: "icon_setting_22", "btn_close_16")</param>
/// <param name="iconSize">아이콘 크기 (null이면 버튼 크기에 맞춤)</param>
public void SetImageIconByName(string iconName, int? iconSize = null)
{
var texture = UTKImageIcons.LoadTextureByName(iconName);
if (texture != null)
{
ApplyImageIcon(texture, iconSize);
}
else
{
Debug.LogWarning($"[UTKButton] Image icon '{iconName}'을(를) 찾을 수 없습니다.");
}
}
/// <summary>
/// 모든 아이콘을 제거합니다.
/// </summary>
public void ClearIcon()
{
Icon = "";
ClearImageIcon();
if (_iconLabel != null)
{
_iconLabel.style.display = DisplayStyle.None;
}
}
private void ApplyImageIcon(Texture2D texture, int? iconSize)
{
// 기존 아이콘 Label 숨기기
Icon = "";
if (_iconLabel != null)
{
_iconLabel.style.display = DisplayStyle.None;
}
// 이미지 아이콘용 VisualElement 생성 또는 재사용
if (_imageIcon == null)
{
_imageIcon = new VisualElement
{
name = "image-icon",
pickingMode = PickingMode.Ignore
};
_imageIcon.AddToClassList("utk-button__image-icon");
Insert(0, _imageIcon);
}
var size = iconSize ?? GetDefaultIconSize();
_imageIcon.style.width = size;
_imageIcon.style.height = size;
_imageIcon.style.backgroundImage = new StyleBackground(texture);
_imageIcon.style.display = DisplayStyle.Flex;
EnableInClassList("utk-button--has-image-icon", true);
}
private void ClearImageIcon()
{
if (_imageIcon != null)
{
_imageIcon.style.display = DisplayStyle.None;
}
EnableInClassList("utk-button--has-image-icon", false);
}
private int GetDefaultIconSize()
{
return _size switch
{
ButtonSize.Small => 16,
ButtonSize.Large => 24,
_ => 20 // Medium
};
}
#endregion
#region IDisposable
public void Dispose()
{
if (_disposed) return;
_disposed = true;
UTKThemeManager.Instance.OnThemeChanged -= OnThemeChanged;
OnClicked = null;
}
#endregion
}
}