#nullable enable using System; using UnityEngine; using UnityEngine.UIElements; namespace UVC.UIToolkit { /// /// 실수 입력 필드에 위/아래 스테퍼 버튼이 붙은 컴포넌트. /// TextInput 오른쪽에 위, 아래 버튼이 세로로 배치됩니다. /// 키보드 화살표, 마우스 휠, 버튼 클릭으로 값을 조절할 수 있습니다. /// /// /// UTKFloatStepper란? /// 실수를 편리하게 증감할 수 있는 입력 컴포넌트입니다. /// /// 버튼 클릭: ▲/▼ 버튼으로 값 증감 /// 키보드: ↑/↓ 화살표 키로 값 증감 /// 마우스 휠: 호버 상태에서 휠로 값 조절 /// 직접 입력: 텍스트 필드에 숫자 직접 입력 /// /// 주요 기능: /// /// 최소/최대값 제한 (MinValue, MaxValue) /// 증감 단위 설정 (Step) /// 순환 모드 (WrapAround) - 최대에서 최소로, 최소에서 최대로 /// /// Validation (유효성 검사): /// /// 속성에 검증 함수를 설정하면, /// 포커스 아웃 시 자동으로 유효성 검사를 수행합니다. /// 검증 실패 시 에 설정된 메시지가 표시됩니다. /// /// /// /// C# 코드에서 사용: /// /// // 기본 스테퍼 생성 /// var stepper = new UTKFloatStepper(); /// stepper.MinValue = 0f; /// stepper.MaxValue = 10f; /// stepper.Value = 5.5f; /// stepper.Step = 0.5f; // 0.5씩 증감 /// /// // 값 변경 이벤트 /// stepper.OnValueChanged += (value) => { /// Debug.Log($"현재 값: {value}"); /// }; /// /// // 범위와 초기값을 지정하는 생성자 /// var volumeStepper = new UTKFloatStepper(0f, 1f, 0.8f, 0.1f); // min, max, initial, step /// /// // 순환 모드 활성화 (10.0 → 0.0, 0.0 → 10.0) /// stepper.WrapAround = true; /// /// // 프로그래밍 방식으로 값 변경 /// stepper.Increment(); // Step만큼 증가 /// stepper.Decrement(); // Step만큼 감소 /// stepper.SetValue(7.5f); // 직접 설정 /// /// // 읽기 전용 (사용자가 수정할 수 없음) /// var readOnlyStepper = new UTKFloatStepper(0f, 10f, 5f, 0.1f); /// readOnlyStepper.IsReadOnly = true; /// /// Validation 사용: /// /// var volumeStepper = new UTKFloatStepper(0f, 1f, 0.5f, 0.1f); /// volumeStepper.ErrorMessage = "볼륨은 0~1 사이여야 합니다."; /// volumeStepper.Validation = () => volumeStepper.Value >= 0f && volumeStepper.Value <= 1f; /// /// UXML에서 사용: /// /// /// /// /// /// /// /// /// /// /// /// /// /// /// ]]> /// 실제 활용 예시 (볼륨 조절): /// /// // 볼륨 스테퍼 (0.0~1.0) /// var volumeStepper = new UTKFloatStepper(0f, 1f, 0.8f, 0.1f); /// volumeStepper.OnValueChanged += (volume) => { /// AudioListener.volume = volume; /// }; /// /// [UxmlElement] public partial class UTKFloatStepper : VisualElement, IDisposable { #region Constants private const string USS_PATH = "UIToolkit/Input/UTKFloatStepper"; #endregion #region UXML Attributes [UxmlAttribute("value")] public float Value { get => _value; set => SetValue(value); } [UxmlAttribute("min-value")] public float MinValue { get => _minValue; set { _minValue = value; ClampValue(); } } [UxmlAttribute("max-value")] public float MaxValue { get => _maxValue; set { _maxValue = value; ClampValue(); } } [UxmlAttribute("step")] public float Step { get => _step; set => _step = value > 0 ? value : 0.1f; } [UxmlAttribute("wrap-around")] public bool WrapAround { get => _wrapAround; set => _wrapAround = value; } /// 읽기 전용 상태. true일 때 사용자가 값을 수정할 수 없음 [UxmlAttribute("is-readonly")] public bool IsReadOnly { get => _isReadOnly; set { _isReadOnly = value; UpdateReadOnlyState(); EnableInClassList("utk-number-stepper--readonly", value); } } /// 에러 메시지. 비어있지 않으면 에러 상태로 표시 [UxmlAttribute("error-message")] public string ErrorMessage { get => _errorMessage; set { _errorMessage = value; var hasError = !string.IsNullOrEmpty(value); EnableInClassList("utk-number-stepper--error", hasError); UpdateErrorLabel(hasError ? value : null); } } #endregion #region Fields private bool _disposed; private bool _isReadOnly; private float _value; private float _minValue = float.MinValue; private float _maxValue = float.MaxValue; private float _step = 1.0f; private bool _wrapAround; private bool _isUpdating; private bool _isHovered; private string _errorMessage = ""; private TextField? _textField; private Button? _upButton; private Button? _downButton; /// 유효성 검사 함수. true 반환 시 유효, false 반환 시 에러 표시 private Func? _validation; /// 에러 메시지 표시용 레이블 private Label? _errorLabel; #endregion #region Properties /// /// 유효성 검사 함수. /// 포커스 아웃 시 자동으로 호출되며, false 반환 시 에러 스타일과 메시지가 표시됩니다. /// public Func? Validation { get => _validation; set => _validation = value; } #endregion #region Events /// 값이 변경될 때 발생 public event Action? OnValueChanged; /// Tab 키가 눌렸을 때 발생 (다음 요소로 포커스 이동용) public event Action? OnTabPressed; /// Shift+Tab 키가 눌렸을 때 발생 (이전 요소로 포커스 이동용) public event Action? OnShiftTabPressed; #endregion #region Constructor public UTKFloatStepper() { UTKThemeManager.Instance.ApplyThemeToElement(this); LoadStyleSheet(); CreateUI(); SetupEvents(); SubscribeToThemeChanges(); } public UTKFloatStepper(bool isReadOnly = false): this() { _isReadOnly = isReadOnly; } public UTKFloatStepper(float minValue, float maxValue, float initialValue = 0f, float step = 0.1f, bool isReadOnly = false): this() { _isReadOnly = isReadOnly; _minValue = minValue; _maxValue = maxValue; _step = step > 0 ? step : 1.0f; _value = Mathf.Clamp(initialValue, minValue, maxValue); } private void LoadStyleSheet() { var uss = Resources.Load(USS_PATH); if (uss != null) { styleSheets.Add(uss); } } private void SubscribeToThemeChanges() { UTKThemeManager.Instance.OnThemeChanged += OnThemeChanged; RegisterCallback(OnAttachToPanelForTheme); RegisterCallback(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 Public Methods public void SetValue(float newValue, bool notify = true) { float clampedValue = ClampValueInternal(newValue); if (!Mathf.Approximately(_value, clampedValue)) { _value = clampedValue; UpdateDisplay(); if (notify) { OnValueChanged?.Invoke(_value); RunValidation(); } } } public void Increment() { if (_wrapAround && _value + _step > _maxValue) { SetValue(_minValue); } else { SetValue(_value + _step); } } public void Decrement() { if (_wrapAround && _value - _step < _minValue) { SetValue(_maxValue); } else { SetValue(_value - _step); } } public void SetRange(float min, float max) { _minValue = min; _maxValue = max; ClampValue(); } /// 컴포넌트의 활성화 상태를 설정합니다. public new void SetEnabled(bool enabled) { base.SetEnabled(enabled); EnableInClassList("utk-number-stepper--disabled", !enabled); } /// 텍스트 필드에 포커스를 설정합니다. public new void Focus() { _textField?.Focus(); } /// 강제로 Validation을 실행하여 에러 상태를 업데이트합니다. public bool Validate() { return RunValidation(); } /// 에러 상태를 수동으로 해제합니다. public void ClearError() { ErrorMessage = ""; } #endregion #region Private Methods - UI Creation private void CreateUI() { AddToClassList("utk-number-stepper"); // Text Field _textField = new TextField { name = "stepper-input" }; _textField.AddToClassList("utk-number-stepper__input"); _textField.isReadOnly = _isReadOnly; // TextField 내부 input 스타일링 _textField.RegisterCallback(_ => { var input = _textField.Q("unity-text-input"); if (input != null) { input.AddToClassList("utk-number-stepper__text-input"); } }); Add(_textField); // Button Container (위/아래 버튼을 세로로 배치) var buttonContainer = new VisualElement { name = "stepper-buttons" }; buttonContainer.AddToClassList("utk-number-stepper__buttons"); // Up Button _upButton = new Button { name = "stepper-up", text = UTKMaterialIcons.KeyboardArrowUp }; _upButton.AddToClassList("utk-number-stepper__btn"); _upButton.AddToClassList("utk-number-stepper__btn--up"); _upButton.SetEnabled(!_isReadOnly); UTKMaterialIcons.ApplyIconStyle(_upButton, 14); buttonContainer.Add(_upButton); // Down Button _downButton = new Button { name = "stepper-down", text = UTKMaterialIcons.KeyboardArrowDown }; _downButton.AddToClassList("utk-number-stepper__btn"); _downButton.AddToClassList("utk-number-stepper__btn--down"); _downButton.SetEnabled(!_isReadOnly); UTKMaterialIcons.ApplyIconStyle(_downButton, 14); buttonContainer.Add(_downButton); Add(buttonContainer); UpdateDisplay(); } private void SetupEvents() { _upButton?.RegisterCallback(OnUpButtonClick); _downButton?.RegisterCallback(OnDownButtonClick); _textField?.RegisterCallback>(OnTextFieldChanged); _textField?.RegisterCallback(OnTextFieldKeyDown, TrickleDown.TrickleDown); _textField?.RegisterCallback(OnTextFieldFocusOut); RegisterCallback(OnMouseEnter); RegisterCallback(OnMouseLeave); RegisterCallback(OnWheelEvent); } #endregion #region Event Handlers private void OnUpButtonClick(ClickEvent evt) => Increment(); private void OnDownButtonClick(ClickEvent evt) => Decrement(); private void OnTextFieldChanged(ChangeEvent evt) { if (_isUpdating) return; if (float.TryParse(evt.newValue, out float parsed)) { SetValue(parsed); } else { // 유효하지 않은 입력이면 이전 값으로 복원 UpdateDisplay(); } } private void OnTextFieldKeyDown(KeyDownEvent evt) { if (evt.keyCode == KeyCode.UpArrow) { Increment(); evt.StopPropagation(); } else if (evt.keyCode == KeyCode.DownArrow) { Decrement(); evt.StopPropagation(); } else if (evt.keyCode == KeyCode.Tab) { if (evt.shiftKey && OnShiftTabPressed != null) { OnShiftTabPressed.Invoke(); evt.StopImmediatePropagation(); } else if (!evt.shiftKey && OnTabPressed != null) { OnTabPressed.Invoke(); evt.StopImmediatePropagation(); } } } /// 텍스트 필드 포커스 아웃 시 유효성 검사 실행 private void OnTextFieldFocusOut(FocusOutEvent evt) { RunValidation(); } private void OnMouseEnter(MouseEnterEvent evt) => _isHovered = true; private void OnMouseLeave(MouseLeaveEvent evt) => _isHovered = false; private void OnWheelEvent(WheelEvent evt) { if (!_isHovered) return; if (evt.delta.y < 0) { Increment(); } else if (evt.delta.y > 0) { Decrement(); } evt.StopPropagation(); } #endregion #region Private Methods - Logic private void UpdateDisplay() { if (_textField == null) return; _isUpdating = true; _textField.value = _value.ToString();//.ToString("F2"); _isUpdating = false; } private void ClampValue() { SetValue(_value, notify: false); } private float ClampValueInternal(float value) { // Step 소수점 자릿수 기준으로 반올림하여 부동소수점 오차 제거 // 예: step=0.1 → digits=1, 0.7+0.1=0.8000001 → 0.8 int digits = GetDecimalDigits(_step); if (digits > 0) { value = (float)Math.Round(value, digits); } return Mathf.Clamp(value, _minValue, _maxValue); } /// 소수점 이하 유효 자릿수를 반환합니다. private static int GetDecimalDigits(float value) { // 최대 7자리까지 검사 (float 정밀도 한계) string s = value.ToString("G7"); int dotIndex = s.IndexOf('.'); return dotIndex < 0 ? 0 : s.Length - dotIndex - 1; } private void UpdateReadOnlyState() { if (_textField != null) { _textField.isReadOnly = _isReadOnly; } if (_upButton != null) { _upButton.SetEnabled(!_isReadOnly); } if (_downButton != null) { _downButton.SetEnabled(!_isReadOnly); } } private bool RunValidation() { if (_validation == null) return true; var isValid = _validation.Invoke(); if (isValid) { EnableInClassList("utk-number-stepper--error", false); UpdateErrorLabel(null); } else { EnableInClassList("utk-number-stepper--error", true); UpdateErrorLabel(_errorMessage); } return isValid; } private void UpdateErrorLabel(string? message) { if (string.IsNullOrEmpty(message)) { if (_errorLabel != null) { _errorLabel.style.display = DisplayStyle.None; } return; } if (_errorLabel == null) { _errorLabel = new Label(); _errorLabel.AddToClassList("utk-number-stepper__error-message"); _errorLabel.style.display = DisplayStyle.None; Add(_errorLabel); } _errorLabel.text = message; _errorLabel.style.display = DisplayStyle.Flex; } #endregion #region IDisposable public void Dispose() { if (_disposed) return; _disposed = true; UTKThemeManager.Instance.OnThemeChanged -= OnThemeChanged; UnregisterCallback(OnAttachToPanelForTheme); UnregisterCallback(OnDetachFromPanelForTheme); // 이벤트 콜백 해제 _upButton?.UnregisterCallback(OnUpButtonClick); _downButton?.UnregisterCallback(OnDownButtonClick); _textField?.UnregisterCallback>(OnTextFieldChanged); _textField?.UnregisterCallback(OnTextFieldKeyDown, TrickleDown.TrickleDown); _textField?.UnregisterCallback(OnTextFieldFocusOut); UnregisterCallback(OnMouseEnter); UnregisterCallback(OnMouseLeave); UnregisterCallback(OnWheelEvent); // 이벤트 null 처리 OnValueChanged = null; OnTabPressed = null; OnShiftTabPressed = null; // Validation 정리 _validation = null; _errorLabel = null; // UI 참조 정리 _textField = null; _upButton = null; _downButton = null; } #endregion } }