StyleKit 속성 해결

background.color 와 같은 스타일 속성은 컨트롤의 state, 활성 Theme, 유효 style variations 에 따라 다양한 값을 가질 수 있습니다. 예를 들어, pressed 와 hovered 상태 간에 차이가 있을 수 있으며, light 와 dark 테마 간에도 차이가 있을 수 있습니다. 이 문서는 StyleKit 가 특정 Control 의 스타일을 지정할 때 속성이 갖게 될 값을 어떻게 결정하는지 자세히 설명합니다.

컨트롤 상태

컨트롤은 상호작용에 따라 모양이 달라집니다 — hovered, pressed, checked, focused, disabled 등. 속성을 결정할 때, StyleKit 는 일반 상태를 확인하기 전에 먼저 모든 상태별 값을 모두 검토합니다.

예를 들어, Button 이 hovered 인 경우, button.background.color 보다 먼저 hovered.button.background.color 이 확인됩니다. 또한 pressed 인 경우, 이 둘보다 먼저 pressed.button.background.color 이 확인됩니다. 상태 간의 우선순위는 ControlStateStyle documentation 에 설명되어 있습니다.

상태는 중첩될 수도 있습니다. 예를 들어, pressed.hovered.button.background.color 와 같은 조합은 pressed.button.background.color 이나 hovered.button.background.color 중 어느 하나만 사용하는 것보다 더 구체적이며, 이 둘 모두보다 우선순위가 높습니다.

대체 속성

일부 스타일 속성은 여러 가지 방법으로 설정할 수 있습니다. 예를 들어, 배경의 왼쪽 상단 반경은 ` background.topLeftRadius`을 사용하여 직접 설정하거나, ` background.radius `(모든 모서리의 반경을 동일하게 설정함)을 사용하여 간접적으로 설정할 수 있습니다. 이러한 속성의 경우, StyleKit 는 먼저 특정 속성을 확인한 다음 대체 속성을 확인하며, 현재 상태에서 두 가지 모두를 모두 적용한 후에야 더 포괄적인 상태로 넘어갑니다. 예를 들어, 컨트롤에 마우스를 올린 상태에서는 button.hovered.background.radius 가 button.background.topLeftRadius 보다 우선합니다. 물론, button.hovered.background.topLeftRadius 는 두 속성 모두보다 우선합니다.

컨트롤 유형 계층 구조

The controls 는 계층 구조를 이룹니다. ` button `은 ` abstractButton`으로 대체되며, 이는 다시 ` control`으로 대체됩니다. ` groupBox `은 ` frame`으로 대체되며, 이는 다시 ` pane`으로 대체되고, 이는 다시 ` control`으로 대체되는 식으로 이어집니다. ` control `은 이 계층 구조의 루트 유형으로, Qt Quick Controls. 각 컨트롤 유형의 직접적인 대체 유형을 확인하려면 documentation 를 참조하십시오.

특정 컨트롤 유형에 대해 모든 상태 및 대체 속성이 소진되면, StyleKit 은 계층 구조를 거슬러 올라가 기본 유형에 해당 속성이 설정되어 있는지 확인합니다. 예를 들어, button.background.color 가 설정되어 있지 않으면, StyleKit 는 대신 abstractButton.background.color 를 확인하며, 이와 같은 방식으로 진행됩니다. 이로 인해 설계자는 재사용을 극대화하고 중복을 최소화하기 위해 여러 컨트롤에 공통적으로 적용되는 속성 값을 공통 기본 유형으로 분리하도록 유도됩니다. 예를 들어, 버튼, 체크박스, 라디오 버튼에 공통적으로 적용되는 모든 속성 값을 abstractButton 에 포함시키고, 특정 하위 유형에서는 서로 다른 속성만 설정할 수 있습니다.

더 구체적인 유형의 상태(일반 상태 포함)는 기본 유형의 어떤 상태보다 우선한다는 점에 유의하십시오. 예를 들어, button.background.color 는 hovered.abstractButton.background.color 보다 우선하며, 이는 컨트롤에 마우스를 올린 상태라도 마찬가지입니다. 물론, hovered.button.background.color 는 이 둘 모두보다 우선합니다.

스타일과 테마

컨트롤 유형 계층 구조는 ` Style `과 ` Theme` 내부에서 모두 반복됩니다. 속성을 해결할 때, ` StyleKit `은 먼저 활성 ` Theme`의 컨트롤 유형 계층 구조를 살펴본 다음, 활성 ` Style`의 계층 구조를 살펴봅니다. 즉, 활성 테마에서 설정된 속성이 스타일에서 설정된 속성보다 우선합니다. 결과적으로, 테마 내의 기본 유형도 스타일 내의 더 구체적인 유형을 재정의합니다. 예를 들어, ` theme.control.background.color `는 ` style.button.background.color`보다 우선합니다.

스타일 변형

컨트롤 유형 계층 구조는 ` StyleVariation` 내부에서도 반복됩니다. 스타일 변형은 스타일과 테마 모두에서 정의할 수 있으며, 테마 내의 스타일 변형은 테마 자체보다 우선합니다. 테마가 스타일보다 우선하므로, 현재 테마의 스타일 속성도 스타일 내의 스타일 변형보다 우선합니다. 예를 들어, theme.button.background.color 는 style.variation.button.background.color 보다 우선합니다.

대체 스타일

모든 Style 에는 fallback style 가 있습니다. 이는 활성 스타일 내에서 속성을 해결할 수 없을 때 최후의 수단으로 작용하는 완전한 스타일입니다. 전체 해결 과정(컨트롤 유형, 상태, 활성 테마 및 모든 스타일 변형을 아우르는)에서 값을 찾지 못하면, StyleKit 는 대체 스타일에서 전체 과정을 반복합니다. 기본 대체 스타일은 기본 스타일( Basic Style)과 유사하므로, 빈 스타일이라도 완전히 스타일이 적용된 컨트롤을 생성합니다.

폴백 스타일 자체에도 폴백 스타일이 있을 수 있으며, ` StyleKit `은 값을 찾거나 체인이 소진될 때까지 이 체인을 재귀적으로 따라갑니다. 값을 찾을 수 없는 경우 기본값이 사용됩니다.

모든 것을 종합해 보면

예를 들어, StyleKit 가 hovered Button 에 대해 background.color 를 해결해야 한다고 가정해 봅시다. 이 스타일에는 테마가 있으며, 스타일과 테마 모두 활성 변형이 있습니다. 그러면 StyleKit 는 다음 위치를 순서대로 확인하며, 가장 먼저 발견된 값을 사용합니다:

• theme.variation.hovered.button.background.color
• theme.variation.button.background.color
• theme.variation.hovered.abstractButton.background.color
• theme.variation.abstractButton.background.color
• theme.variation.hovered.control.background.color
• theme.variation.control.background.color
• theme.hovered.button.background.color
• theme.button.background.color
• theme.hovered.abstractButton.background.color
• theme.abstractButton.background.color
• theme.hovered.control.background.color
• theme.control.background.color
• style.variation.hovered.button.background.color
• style.variation.button.background.color
• style.variation.hovered.abstractButton.background.color
• style.variation.abstractButton.background.color
• style.variation.hovered.control.background.color
• style.variation.control.background.color
• style.hovered.button.background.color
• style.button.background.color
• style.hovered.abstractButton.background.color
• style.abstractButton.background.color
• style.hovered.control.background.color
• style.control.background.color

이 모든 위치를 모두 확인해도 값을 찾지 못하면, 대체 스타일에서 동일한 과정이 반복됩니다(대체 스타일에도 대체 스타일이 있는 경우 재귀적으로 수행됨). 그래도 찾지 못하면 기본값이 사용됩니다.

속성 해결 디버깅

여러 컨트롤 유형, 테마, 변형 및 대체 스타일이 모두 속성의 최종 값을 결정하는 데 기여하기 때문에, 특정 컨트롤이 왜 특정 모양으로 표시되는지 파악하기 어려울 때가 있습니다. ` StyleKitDebug `는 읽은 각 스타일 속성을 디버그 출력에 기록하여, 속성이 정확히 어떤 계층과 컨트롤 유형에서 해결되었는지 보여주는 앱 내 진단 도구입니다.

추적을 시작하려면, 분석하려는 컨트롤을 StyleKit.debug.control 속성에 할당하십시오:

ApplicationWindow {
    id: app
    width: 1024
    height: 800
    visible: true

    StyleKit.debug.control: someButton
    StyleKit.debug.filter: "background.color"

    StyleKit.style: Style {
        button {
            background.color: "gray"
            hovered.background.color: "dimgray"
        }
        dark: Theme {
            button {
                background.color: "skyblue"
                hovered.background.color: "lightblue"
            }
        }
    }

    Column {
        anchors.fill: parent
        anchors.margins: 10
        spacing: 10

        Button {
            id: someButton
            text: "A Button"
        }
    }
}

해결된 각 속성은 한 줄로 출력됩니다. 예를 들면 다음과 같습니다:

[read] StyleReader[Hovered].button.background.color -> Style.Theme(Dark).button[Hovered] = #add8e6

출력에 표시된 ` StyleReader `는 ` Button `가 내부적으로 스타일 속성 값을 읽기 위해 사용하는 ` StyleReader `을 가리킵니다.

filter 속성을 사용하여 관심 있는 속성으로만 출력을 제한할 수 있습니다.