Styling System

[al6uiz]

Styling

This document describes MewUI's styling system — a code-first, AOT-friendly approach to reusable, state-aware visual customization.

---

1. Overview

MewUI's styling system is built around the following principles:

• Code-first: styles are C# lambdas, not XML or CSS
• AOT-friendly: no reflection, no dynamic dispatch — only generic interfaces and typed delegates
• Non-destructive: state-based colors are resolved at render time, not by mutating element properties
• Composable: styles can extend other styles; containers can propagate styles to descendants

Relationship to Theme

The Theme system provides app-wide defaults (palette, metrics, fonts). Styles sit on top of the theme and allow per-control or per-scope visual overrides without touching the theme itself.

Theme (global defaults)
  ↓  overridden by
StyleScope rules (container-level)
  ↓  overridden by
StyleName (per-element named style)
  ↓  (user can still set individual properties on top)

---

2. StyleSheet

StyleSheet is a named registry of styles. It lives on Application (global) or on a Window (local). When looking up a style, MewUI searches the nearest StyleSheet up the element tree.

2.1 Registering styles

// Application-level (global)
Application.Create()
    .UseStyles(styles => styles
        .Define("btn-primary", (Button b, Theme t) =>
        {
            b.Padding = new Thickness(12, 5);
        })
    )
    .Run(mainWindow);

// Or imperatively before Run(...)
app.Styles
    .Define("btn-primary", (Button b, Theme t) =>
    {
        b.Padding = new Thickness(12, 5);
    });

2.2 Applying a style to an element

var btn = new Button { Content = "Save", StyleName = "btn-primary" };

The style callback is invoked:

• When StyleName is first assigned
• Whenever the theme changes

2.3 Composing styles

A style can extend another by name. The base style runs first; the new style then applies its overrides on top.

app.Styles
    .Define("btn-base", (Button b, Theme t) =>
    {
        b.Padding = new Thickness(12, 5);
        b.BorderThickness = new Thickness(1);
    })
    .Define("btn-primary", "btn-base", (Button b, Theme t) =>
    {
        b.BorderBrush = t.Palette.Accent;
    })
    .Define("btn-danger", "btn-base", (Button b, Theme t) =>
    {
        b.BorderBrush = Colors.Red;
    });

---

3. StyleScope

StyleScope is attached to a container element. It applies matching style rules automatically to all descendants of that container.

var toolbar = new StackPanel
{
    Orientation = Orientation.Horizontal,
    Scope = new StyleScope()
        .Add<Button>("btn-compact")            // named style from StyleSheet
        .Add<Label>((l, t) => l.FontSize = 11) // inline rule
};

Rules are matched by element type (is T check). Multiple scopes can be nested; rules from outer scopes apply first, inner scopes override.

Scope resolution order

Window.Scope  →  outer Panel.Scope  →  inner Panel.Scope  →  element.StyleName
   (lowest priority)                                           (highest priority)

---

4. State-aware styling

State-based colors (hover, press, focus, disabled, selected) are resolved at render time rather than by mutating element properties. This avoids unnecessary layout invalidation and preserves explicitly set property values.

4.1 ElementState

[Flags]
public enum ElementState
{
    Normal   = 0,
    Hovered  = 1 << 0,
    Pressed  = 1 << 1,
    Focused  = 1 << 2,
    Disabled = 1 << 3,
    Selected = 1 << 4,
}

4.2 ColorRole

ColorRole identifies a color slot on a control. Built-in roles are predefined; custom controls can declare their own.

// Built-in roles
ColorRole.Background
ColorRole.Foreground
ColorRole.BorderBrush

// Custom control declares its own roles
public class CardControl : Control
{
    public static readonly ColorRole StripeColor = ColorRole.Create();
    public static readonly ColorRole HeaderBg    = ColorRole.Create();
}

4.3 ControlColors

ControlColors holds per-state color functions for a single ColorRole.

new ControlColors
{
    Normal   = t => t.Palette.Accent,
    Hovered  = t => t.Palette.AccentHovered,
    Pressed  = t => t.Palette.AccentPressed,
    Focused  = t => t.Palette.FocusRing,
    Disabled = t => t.Palette.Disabled,
}

Resolution priority within ControlColors: Disabled > Pressed > Hovered > Selected > Normal.
If a state has no entry, the system falls back to Normal.

4.4 StyleDefinition<T>

StyleDefinition<T> bundles color roles, a layout callback, and an optional state callback into a single style object.

app.Styles.Define("btn-primary", new StyleDefinition<Button>()
    .Set(ColorRole.Background, new ControlColors
    {
        Normal   = t => t.Palette.Accent,
        Hovered  = t => t.Palette.AccentHovered,
        Pressed  = t => t.Palette.AccentPressed,
        Disabled = t => t.Palette.Disabled,
    })
    .Set(ColorRole.Foreground, new ControlColors
    {
        Normal   = _ => Colors.White,
        Disabled = t => t.Palette.DisabledText,
    })
    .Set(ColorRole.BorderBrush, new ControlColors
    {
        Normal  = t => t.Palette.Accent,
        Focused = t => t.Palette.FocusRing,
    })
    // Layout properties: applied once per theme change
    .WithLayout((b, t) =>
    {
        b.Padding = new Thickness(12, 5);
        b.BorderThickness = new Thickness(1);
    })
);

4.5 How controls consume state colors

Controls query their resolved color at render time using ResolveColor. This method returns the style-overridden color, or the provided fallback if no style is set.

// Inside Button.OnRender (example):
var bg = ResolveColor(ColorRole.Background, theme,
    fallback: IsPressed   ? theme.Palette.ButtonPressed :
              IsMouseOver ? theme.Palette.ButtonHovered :
                            theme.Palette.ButtonFace);

Controls that do not use ResolveColor are unaffected by the styling system — their behavior is unchanged.

---

5. State-dependent layout properties

For layout properties (e.g., BorderThickness, Padding) that must change with state, use the OnState callback. Unlike color roles, layout mutations trigger InvalidateMeasure, which is the correct behavior for structural changes.

app.Styles.Define("textbox-outline", new StyleDefinition<TextBox>()
    .Set(ColorRole.BorderBrush, new ControlColors
    {
        Normal  = t => t.Palette.ControlBorder,
        Focused = t => t.Palette.Accent,
    })
    .WithLayout((tb, t) => tb.Padding = t.Metrics.InputPadding)
    .WithOnState((tb, t, state) =>
    {
        tb.BorderThickness = state.Has(ElementState.Focused)
            ? new Thickness(2)
            : new Thickness(1);
    })
);

Layout jump warning: changing BorderThickness on state transition shrinks the available content area. To avoid visible jumps, consider keeping BorderThickness constant and expressing the focus indicator through color only.

---

6. Custom control extension

Custom controls can define their own ColorRole keys and participate in the styling system with no changes to the framework.

public class StatusCard : Control
{
    // Declare roles as static fields
    public static readonly ColorRole IndicatorColor = ColorRole.Create();
    public static readonly ColorRole HeaderBg       = ColorRole.Create();

    protected override void OnRender(IGraphicsContext g, Rect bounds, Theme theme)
    {
        var bg        = ResolveColor(ColorRole.Background,  theme, theme.Palette.Surface);
        var header    = ResolveColor(HeaderBg,              theme, theme.Palette.SubtleFill);
        var indicator = ResolveColor(IndicatorColor,        theme, theme.Palette.Accent);

        g.FillRect(bg, bounds);
        g.FillRect(header, headerBounds);
        g.FillRect(indicator, indicatorBounds);
    }
}

// Style definition uses the same .Set() API for custom roles
app.Styles.Define("status-card-info", new StyleDefinition<StatusCard>()
    .Set(ColorRole.Background, new ControlColors { Normal = t => t.Palette.Surface })
    .Set(StatusCard.HeaderBg,  new ControlColors { Normal = t => t.Palette.SubtleFill })
    .Set(StatusCard.IndicatorColor, new ControlColors
    {
        Normal  = t => t.Palette.Accent,
        Hovered = t => t.Palette.AccentHovered,
    })
);

---

7. Execution timing summary

Property category	When applied	Triggers
ColorRole / ControlColors	At render time	InvalidateVisual (on state change)
WithLayout callback	On theme change	InvalidateMeasure
WithOnState callback	On state change	InvalidateMeasure
StyleScope inline rules	On theme change	Same as WithLayout

---

8. Complete example

app.Styles
    // Simple named style (layout only)
    .Define("btn-base", (Button b, Theme t) =>
    {
        b.Padding = new Thickness(12, 5);
        b.BorderThickness = new Thickness(1);
    })

    // State-aware style extending btn-base
    .Define("btn-primary", "btn-base", new StyleDefinition<Button>()
        .Set(ColorRole.Background, new ControlColors
        {
            Normal   = t => t.Palette.Accent,
            Hovered  = t => t.Palette.AccentHovered,
            Pressed  = t => t.Palette.AccentPressed,
            Disabled = t => t.Palette.Disabled,
        })
        .Set(ColorRole.Foreground, new ControlColors
        {
            Normal   = _ => Colors.White,
            Disabled = t => t.Palette.DisabledText,
        })
        .Set(ColorRole.BorderBrush, new ControlColors
        {
            Normal  = t => t.Palette.Accent,
            Focused = t => t.Palette.FocusRing,
        })
    );

// Container scope: all Buttons below get "btn-base"
var actionBar = new StackPanel
{
    Orientation = Orientation.Horizontal,
    Scope = new StyleScope().Add<Button>("btn-base")
};

// Individual override
var saveBtn   = new Button { Content = "Save",   StyleName = "btn-primary" };
var cancelBtn = new Button { Content = "Cancel", StyleName = "btn-base" };

actionBar.Children.Add(saveBtn);
actionBar.Children.Add(cancelBtn);

[al6uiz]

스타일링

이 문서는 MewUI의 스타일링 시스템을 설명합니다. 코드 퍼스트(code-first), AOT 친화적인 방식으로 재사용 가능한 상태 인식 비주얼 커스터마이징을 지원합니다.

---

1. 개요

MewUI 스타일링 시스템의 설계 원칙:

• 코드 퍼스트: 스타일은 C# 람다이며, XML이나 CSS가 아닙니다
• AOT 친화적: 리플렉션 없음, 제네릭 인터페이스와 타입 안전 델리게이트만 사용
• 비파괴적: 상태 기반 색상은 렌더 시점에 질의되며, 엘리먼트 프로퍼티를 덮어쓰지 않습니다
• 합성 가능: 스타일은 다른 스타일을 확장할 수 있고, 컨테이너가 하위 요소에 스타일을 전파할 수 있습니다

테마와의 관계

Theme 시스템은 앱 전역 기본값(팔레트, 메트릭, 폰트)을 제공합니다. 스타일은 테마 위에 놓이며, 테마 자체를 건드리지 않고 컨트롤별 또는 범위별 비주얼 오버라이드를 가능하게 합니다.

Theme (전역 기본값)
  ↓  재정의됨
StyleScope 규칙 (컨테이너 레벨)
  ↓  재정의됨
StyleName (엘리먼트별 이름 스타일)
  ↓  (그 위에 개별 프로퍼티를 직접 설정할 수 있음)

---

2. StyleSheet

StyleSheet는 이름이 붙은 스타일 레지스트리입니다. Application(전역) 또는 Window(로컬)에 위치합니다. 스타일을 조회할 때 MewUI는 엘리먼트 트리를 따라 올라가며 가장 가까운 StyleSheet를 탐색합니다.

2.1 스타일 등록

// 앱 전역
Application.Create()
    .UseStyles(styles => styles
        .Define("btn-primary", (Button b, Theme t) =>
        {
            b.Padding = new Thickness(12, 5);
        })
    )
    .Run(mainWindow);

// 또는 Run 전에 직접 등록
app.Styles
    .Define("btn-primary", (Button b, Theme t) =>
    {
        b.Padding = new Thickness(12, 5);
    });

2.2 엘리먼트에 스타일 적용

var btn = new Button { Content = "저장", StyleName = "btn-primary" };

스타일 콜백이 호출되는 시점:

• StyleName이 처음 할당될 때
• 테마가 변경될 때마다

2.3 스타일 합성

스타일은 이름으로 다른 스타일을 확장할 수 있습니다. 베이스 스타일이 먼저 실행되고, 이후 새 스타일이 그 위에 오버라이드를 적용합니다.

app.Styles
    .Define("btn-base", (Button b, Theme t) =>
    {
        b.Padding = new Thickness(12, 5);
        b.BorderThickness = new Thickness(1);
    })
    .Define("btn-primary", "btn-base", (Button b, Theme t) =>
    {
        b.BorderBrush = t.Palette.Accent;
    })
    .Define("btn-danger", "btn-base", (Button b, Theme t) =>
    {
        b.BorderBrush = Colors.Red;
    });

---

3. StyleScope

StyleScope는 컨테이너 엘리먼트에 연결됩니다. 해당 컨테이너의 모든 하위 요소 중 타입이 일치하는 요소에 자동으로 스타일 규칙을 적용합니다.

var toolbar = new StackPanel
{
    Orientation = Orientation.Horizontal,
    Scope = new StyleScope()
        .Add<Button>("btn-compact")             // StyleSheet에 등록된 이름 스타일
        .Add<Label>((l, t) => l.FontSize = 11)  // 인라인 규칙
};

규칙은 엘리먼트 타입으로 매칭됩니다(is T 검사). 여러 Scope를 중첩할 수 있으며, 바깥쪽 Scope 규칙이 먼저 적용되고 안쪽 Scope가 그 위를 덮습니다.

범위 우선순위

Window.Scope  →  바깥 Panel.Scope  →  안쪽 Panel.Scope  →  element.StyleName
   (낮은 우선순위)                                           (높은 우선순위)

---

4. 상태 인식 스타일링

Hover, Press, Focus, Disabled, Selected 등의 상태별 색상은 엘리먼트 프로퍼티를 직접 변경하지 않고 렌더 시점에 질의됩니다. 이를 통해 불필요한 레이아웃 재계산을 방지하고, 사용자가 명시적으로 설정한 프로퍼티 값을 보존합니다.

4.1 ElementState

[Flags]
public enum ElementState
{
    Normal   = 0,
    Hovered  = 1 << 0,
    Pressed  = 1 << 1,
    Focused  = 1 << 2,
    Disabled = 1 << 3,
    Selected = 1 << 4,
}

4.2 ColorRole

ColorRole은 컨트롤의 색상 슬롯을 식별하는 키입니다. 프레임워크가 기본 역할을 미리 정의하며, 커스텀 컨트롤은 자신만의 역할을 선언할 수 있습니다.

// 기본 제공 역할
ColorRole.Background
ColorRole.Foreground
ColorRole.BorderBrush

// 커스텀 컨트롤이 자신의 색상 역할 선언
public class CardControl : Control
{
    public static readonly ColorRole StripeColor = ColorRole.Create();
    public static readonly ColorRole HeaderBg    = ColorRole.Create();
}

4.3 ControlColors

ControlColors는 하나의 ColorRole에 대해 상태별 색상 함수를 담습니다.

new ControlColors
{
    Normal   = t => t.Palette.Accent,
    Hovered  = t => t.Palette.AccentHovered,
    Pressed  = t => t.Palette.AccentPressed,
    Focused  = t => t.Palette.FocusRing,
    Disabled = t => t.Palette.Disabled,
}

ControlColors 내부 우선순위: Disabled > Pressed > Hovered > Selected > Normal.
해당 상태에 항목이 없으면 Normal로 폴백합니다.

4.4 StyleDefinition<T>

StyleDefinition<T>는 색상 역할, 레이아웃 콜백, 상태 콜백을 하나의 스타일 객체로 묶습니다.

app.Styles.Define("btn-primary", new StyleDefinition<Button>()
    .Set(ColorRole.Background, new ControlColors
    {
        Normal   = t => t.Palette.Accent,
        Hovered  = t => t.Palette.AccentHovered,
        Pressed  = t => t.Palette.AccentPressed,
        Disabled = t => t.Palette.Disabled,
    })
    .Set(ColorRole.Foreground, new ControlColors
    {
        Normal   = _ => Colors.White,
        Disabled = t => t.Palette.DisabledText,
    })
    .Set(ColorRole.BorderBrush, new ControlColors
    {
        Normal  = t => t.Palette.Accent,
        Focused = t => t.Palette.FocusRing,
    })
    // 레이아웃 속성: 테마 변경 시 1회 실행
    .WithLayout((b, t) =>
    {
        b.Padding = new Thickness(12, 5);
        b.BorderThickness = new Thickness(1);
    })
);

4.5 컨트롤에서 상태 색상 사용

컨트롤은 ResolveColor를 통해 렌더 시점에 색상을 질의합니다. 이 메서드는 스타일이 지정된 경우 그 색상을 반환하고, 스타일이 없으면 제공된 fallback을 그대로 반환합니다.

// Button.OnRender 내부 (예시):
var bg = ResolveColor(ColorRole.Background, theme,
    fallback: IsPressed   ? theme.Palette.ButtonPressed :
              IsMouseOver ? theme.Palette.ButtonHovered :
                            theme.Palette.ButtonFace);

ResolveColor를 사용하지 않는 컨트롤은 스타일링 시스템의 영향을 받지 않으며, 기존 동작이 그대로 유지됩니다.

---

5. 상태 의존 레이아웃 속성

상태에 따라 변경되어야 하는 레이아웃 속성(예: BorderThickness, Padding)에는 OnState 콜백을 사용합니다. 색상 역할과 달리 레이아웃 뮤테이션은 InvalidateMeasure를 트리거하며, 이는 구조적 변경에서 올바른 동작입니다.

app.Styles.Define("textbox-outline", new StyleDefinition<TextBox>()
    .Set(ColorRole.BorderBrush, new ControlColors
    {
        Normal  = t => t.Palette.ControlBorder,
        Focused = t => t.Palette.Accent,
    })
    .WithLayout((tb, t) => tb.Padding = t.Metrics.InputPadding)
    .WithOnState((tb, t, state) =>
    {
        tb.BorderThickness = state.Has(ElementState.Focused)
            ? new Thickness(2)
            : new Thickness(1);
    })
);

레이아웃 점프 주의: BorderThickness가 상태 전환 시 바뀌면 사용 가능한 콘텐츠 영역이 줄어들어 시각적 점프가 발생할 수 있습니다. 이를 피하려면 BorderThickness를 고정하고 포커스 표시는 색상으로만 표현하는 것을 권장합니다.

---

6. 커스텀 컨트롤 확장

커스텀 컨트롤은 자신만의 ColorRole을 선언하고, 프레임워크 변경 없이 스타일링 시스템에 동일한 방식으로 참여할 수 있습니다.

public class StatusCard : Control
{
    // 정적 필드로 역할 선언
    public static readonly ColorRole IndicatorColor = ColorRole.Create();
    public static readonly ColorRole HeaderBg       = ColorRole.Create();

    protected override void OnRender(IGraphicsContext g, Rect bounds, Theme theme)
    {
        var bg        = ResolveColor(ColorRole.Background, theme, theme.Palette.Surface);
        var header    = ResolveColor(HeaderBg,             theme, theme.Palette.SubtleFill);
        var indicator = ResolveColor(IndicatorColor,       theme, theme.Palette.Accent);

        g.FillRect(bg, bounds);
        g.FillRect(header, headerBounds);
        g.FillRect(indicator, indicatorBounds);
    }
}

// 커스텀 역할도 동일한 .Set() API 사용
app.Styles.Define("status-card-info", new StyleDefinition<StatusCard>()
    .Set(ColorRole.Background, new ControlColors { Normal = t => t.Palette.Surface })
    .Set(StatusCard.HeaderBg,  new ControlColors { Normal = t => t.Palette.SubtleFill })
    .Set(StatusCard.IndicatorColor, new ControlColors
    {
        Normal  = t => t.Palette.Accent,
        Hovered = t => t.Palette.AccentHovered,
    })
);

---

7. 실행 타이밍 요약

속성 범주	적용 시점	트리거
ColorRole / ControlColors	렌더 시점	InvalidateVisual (상태 변경 시)
WithLayout 콜백	테마 변경 시	InvalidateMeasure
WithOnState 콜백	상태 변경 시	InvalidateMeasure
StyleScope 인라인 규칙	테마 변경 시	WithLayout과 동일

---

8. 전체 예시

app.Styles
    // 레이아웃만 있는 단순 이름 스타일
    .Define("btn-base", (Button b, Theme t) =>
    {
        b.Padding = new Thickness(12, 5);
        b.BorderThickness = new Thickness(1);
    })

    // btn-base를 확장하는 상태 인식 스타일
    .Define("btn-primary", "btn-base", new StyleDefinition<Button>()
        .Set(ColorRole.Background, new ControlColors
        {
            Normal   = t => t.Palette.Accent,
            Hovered  = t => t.Palette.AccentHovered,
            Pressed  = t => t.Palette.AccentPressed,
            Disabled = t => t.Palette.Disabled,
        })
        .Set(ColorRole.Foreground, new ControlColors
        {
            Normal   = _ => Colors.White,
            Disabled = t => t.Palette.DisabledText,
        })
        .Set(ColorRole.BorderBrush, new ControlColors
        {
            Normal  = t => t.Palette.Accent,
            Focused = t => t.Palette.FocusRing,
        })
    );

// 컨테이너 Scope: 하위 Button 전체에 "btn-base" 적용
var actionBar = new StackPanel
{
    Orientation = Orientation.Horizontal,
    Scope = new StyleScope().Add<Button>("btn-base")
};

// 개별 오버라이드
var saveBtn   = new Button { Content = "저장",   StyleName = "btn-primary" };
var cancelBtn = new Button { Content = "취소",   StyleName = "btn-base" };

actionBar.Children.Add(saveBtn);
actionBar.Children.Add(cancelBtn);