khi/XRLib
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

기본 Styleguide 완료

Browse Source
This commit is contained in:
logonkhi
2026-01-21 20:43:54 +09:00
parent fd8f8c6de0
commit e00953de52
122 changed files with 3310 additions and 709 deletions
Download Patch File Download Diff File Expand all files Collapse all files

90
Assets/Scripts/UVC/UIToolkit/Dropdown/UTKDropdown.cs
View File

@@ -9,32 +9,82 @@ namespace UVC.UIToolkit
/// <summary>
/// 드롭다운 메뉴 컴포넌트.
/// Unity DropdownField를 래핑하여 커스텀 스타일을 적용합니다.
/// 여러 옵션 중 하나를 선택할 수 있는 UI 컨트롤입니다.
/// </summary>
/// <remarks>
/// <para><b>드롭다운(Dropdown)이란?</b></para>
/// <para>
/// 드롭다운은 클릭하면 펼쳐지는 옵션 목록에서 하나를 선택하는 UI 컴포넌트입니다.
/// 많은 옵션을 작은 공간에 담을 수 있어 화면 공간을 효율적으로 사용합니다.
/// 라디오 버튼과 비슷하지만, 옵션이 많을 때 더 적합합니다.
/// </para>
///
/// <para><b>주요 속성:</b></para>
/// <list type="bullet">
/// <item><description><c>choices</c> - 선택 가능한 옵션 목록 (List<string>)</description></item>
/// <item><description><c>index</c> - 현재 선택된 인덱스 (0부터 시작)</description></item>
/// <item><description><c>value</c> - 현재 선택된 텍스트 값</description></item>
/// <item><description><c>SelectedIndex</c> - index의 별칭</description></item>
/// <item><description><c>SelectedValue</c> - value의 별칭 (읽기 전용)</description></item>
/// </list>
///
/// <para><b>주요 메서드:</b></para>
/// <list type="bullet">
/// <item><description><c>SetOptions(List<string>)</c> - 전체 옵션 목록 교체</description></item>
/// <item><description><c>AddOption(string)</c> - 옵션 하나 추가</description></item>
/// <item><description><c>SetSelectedValue(string, bool)</c> - 값으로 선택 (notify: 이벤트 발생 여부)</description></item>
/// </list>
///
/// <para><b>실제 활용 예시:</b></para>
/// <list type="bullet">
/// <item><description>정렬 옵션 - 이름순, 날짜순, 크기순</description></item>
/// <item><description>언어 선택 - 한국어, English, 日本語</description></item>
/// <item><description>국가/지역 선택</description></item>
/// <item><description>해상도, 품질 설정</description></item>
/// <item><description>파일 형식 선택</description></item>
/// </list>
/// </remarks>
/// <example>
/// <para><b>C# 코드에서 사용:</b></para>
/// <code>
/// // 기본 드롭다운
/// var dropdown = new UTKDropdown();
/// dropdown.Label = "국가 선택";
/// dropdown.SetChoices(new List<string> { "한국", "미국", "일본" });
/// dropdown.OnSelectionChanged += (index, value) => Debug.Log($"선택: {value}");
///
/// // 기본값 설정
/// dropdown.value = "한국";
/// dropdown.index = 0;
/// // 국가 선택 드롭다운
/// var countryDropdown = new UTKDropdown();
/// countryDropdown.label = "국가 선택";
/// countryDropdown.SetOptions(new List<string> { "한국", "미국", "일본", "중국" });
///
/// // 선택 변경 이벤트 (인덱스와 값 모두 전달)
/// countryDropdown.OnSelectionChanged += (index, value) => {
/// Debug.Log($"선택: [{index}] {value}");
/// };
///
/// // 생성자로 한 번에 설정
/// var sortDropdown = new UTKDropdown("정렬", new List<string> { "이름", "날짜", "크기" });
///
/// // 기본값 설정 (인덱스로)
/// sortDropdown.index = 0; // 첫 번째 항목 선택
///
/// // 기본값 설정 (값으로)
/// sortDropdown.SetSelectedValue("날짜");
///
/// // 동적으로 옵션 추가
/// countryDropdown.AddOption("독일");
///
/// // 이벤트 없이 값 변경 (초기화 시 유용)
/// sortDropdown.SetSelectedValue("크기", notify: false);
/// </code>
/// <para><b>UXML에서 사용:</b></para>
/// <code>
/// <ui:UXML xmlns:utk="UVC.UIToolkit">
/// <!-- 기본 드롭다운 -->
/// <utk:UTKDropdown label="정렬" choices="이름,날짜,크기" />
///
/// <!-- 기본값 지정 -->
/// <utk:UTKDropdown label="언어" choices="한국어,English,日本語" index="0" />
///
/// <!-- 비활성화 -->
/// <utk:UTKDropdown label="선택" IsEnabled="false" />
/// </ui:UXML>
/// <!-- 기본 드롭다운 (쉼표로 구분) -->
/// <utk:UTKDropdown label="정렬" choices="이름,날짜,크기" />
///
/// <!-- 기본값 지정 (index로) -->
/// <utk:UTKDropdown label="언어"
/// choices="한국어,English,日本語"
/// index="0" />
///
/// <!-- 비활성화 상태 -->
/// <utk:UTKDropdown label="선택" IsEnabled="false"
/// choices="옵션1,옵션2,옵션3" />
/// </code>
/// </example>
[UxmlElement]
@@ -66,7 +116,7 @@ namespace UVC.UIToolkit
public string? SelectedValue => value;
/// <summary>활성화 상태</summary>
[UxmlAttribute]
[UxmlAttribute("is-enabled")]
public bool IsEnabled
{
get => _isEnabled;

103
Assets/Scripts/UVC/UIToolkit/Dropdown/UTKEnumDropDown.cs
View File

@@ -8,37 +8,98 @@ namespace UVC.UIToolkit
/// <summary>
/// Enum 선택 드롭다운 컴포넌트.
/// Unity EnumField를 래핑하여 커스텀 스타일을 적용합니다.
/// C# Enum 타입을 자동으로 드롭다운 옵션으로 변환합니다.
/// </summary>
/// <remarks>
/// <para><b>Enum 드롭다운이란?</b></para>
/// <para>
/// Enum 드롭다운은 C#의 열거형(Enum) 타입을 자동으로 드롭다운 목록으로 만들어주는 컴포넌트입니다.
/// 문자열 목록을 수동으로 관리할 필요 없이, Enum 정의만으로 타입 안전한 선택 UI를 구현합니다.
/// </para>
///
/// <para><b>Enum이란?</b></para>
/// <para>
/// Enum(열거형)은 관련된 상수들을 묶어 명명된 값의 집합을 정의합니다.
/// 예를 들어, 게임 난이도를 <c>Easy</c>, <c>Normal</c>, <c>Hard</c>로 정의할 수 있습니다.
/// </para>
///
/// <para><b>문자열 드롭다운 vs Enum 드롭다운:</b></para>
/// <list type="bullet">
/// <item><description>문자열: 유연하지만 오타 위험, 컴파일 타임 검증 불가</description></item>
/// <item><description>Enum: 타입 안전, 자동 완성 지원, 리팩토링 용이</description></item>
/// </list>
///
/// <para><b>주요 속성:</b></para>
/// <list type="bullet">
/// <item><description><c>Value</c> - 현재 선택된 Enum 값</description></item>
/// <item><description><c>IsEnabled</c> - 활성화/비활성화 상태</description></item>
/// </list>
///
/// <para><b>중요한 메서드:</b></para>
/// <list type="bullet">
/// <item><description><c>Init(Enum)</c> - Enum 타입과 기본값으로 초기화 (필수!)</description></item>
/// </list>
///
/// <para><b>UXML 사용 시 주의:</b></para>
/// <para>
/// UXML에서는 Enum 타입을 지정할 수 없으므로, 반드시 C# 코드에서 <c>Init()</c>을 호출해야 합니다.
/// </para>
///
/// <para><b>실제 활용 예시:</b></para>
/// <list type="bullet">
/// <item><description>게임 난이도 - Easy, Normal, Hard, Expert</description></item>
/// <item><description>정렬 방식 - Ascending, Descending</description></item>
/// <item><description>파일 형식 - PNG, JPG, GIF, BMP</description></item>
/// <item><description>품질 설정 - Low, Medium, High, Ultra</description></item>
/// <item><description>애니메이션 상태 - Idle, Walk, Run, Jump</description></item>
/// </list>
/// </remarks>
/// <example>
/// <para><b>Enum 정의:</b></para>
/// <code>
/// // 게임 난이도 Enum
/// public enum Difficulty { Easy, Normal, Hard, Expert }
///
/// // 품질 설정 Enum
/// public enum QualityLevel { Low, Medium, High, Ultra }
/// </code>
/// <para><b>C# 코드에서 사용:</b></para>
/// <code>
/// // Enum 정의
/// public enum MyOption { Option1, Option2, Option3 }
///
/// // 기본 Enum 드롭다운
/// var enumDropdown = new UTKEnumDropDown();
/// enumDropdown.label = "옵션 선택";
/// enumDropdown.Init(MyOption.Option1);
///
/// // 난이도 선택 드롭다운
/// var difficultyDropdown = new UTKEnumDropDown();
/// difficultyDropdown.label = "난이도";
/// difficultyDropdown.Init(Difficulty.Normal); // 기본값: Normal
///
/// // 값 변경 이벤트
/// enumDropdown.OnValueChanged += (value) => {
/// Debug.Log($"선택됨: {value}");
/// difficultyDropdown.OnValueChanged += (value) => {
/// var difficulty = (Difficulty)value;
/// Debug.Log($"난이도 변경: {difficulty}");
/// ApplyDifficulty(difficulty);
/// };
///
/// // 현재 값 가져오기
/// var current = (MyOption)enumDropdown.Value;
///
/// // 생성자로 한 번에 설정
/// var qualityDropdown = new UTKEnumDropDown("품질", QualityLevel.High);
///
/// // 현재 값 읽기 (캐스팅 필요)
/// var currentQuality = (QualityLevel)qualityDropdown.Value;
///
/// // 프로그래밍으로 값 변경
/// difficultyDropdown.Value = Difficulty.Hard;
/// </code>
/// <para><b>UXML에서 사용:</b></para>
/// <code>
/// <ui:UXML xmlns:utk="UVC.UIToolkit">
/// <!-- UXML에서는 C#에서 Init() 호출 필요 -->
/// <utk:UTKEnumDropDown name="my-enum" label="옵션" />
/// </ui:UXML>
/// <!-- UXML에서는 name만 지정 -->
/// <utk:UTKEnumDropDown name="difficulty-dropdown" label="난이도" />
/// <utk:UTKEnumDropDown name="quality-dropdown" label="품질" />
/// </code>
/// <para><b>UXML 로드 후 초기화:</b></para>
/// <para><b>UXML 로드 후 C#에서 초기화:</b></para>
/// <code>
/// var enumField = root.Q<UTKEnumDropDown>("my-enum");
/// enumField.Init(MyOption.Option1);
/// // UXML 로드 후 반드시 Init() 호출
/// var diffDropdown = root.Q<UTKEnumDropDown>("difficulty-dropdown");
/// diffDropdown.Init(Difficulty.Normal);
///
/// var qualityDropdown = root.Q<UTKEnumDropDown>("quality-dropdown");
/// qualityDropdown.Init(QualityLevel.High);
/// </code>
/// </example>
[UxmlElement]
@@ -67,7 +128,7 @@ namespace UVC.UIToolkit
}
/// <summary>활성화 상태</summary>
[UxmlAttribute]
[UxmlAttribute("is-enabled")]
public bool IsEnabled
{
get => _isEnabled;