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 コントロールのタイプ階層を反映しています。各コントロールタイプの直接のフォールバックタイプについては、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 はフォールバックスタイルでプロセス全体を繰り返し実行します。 デフォルトのフォールバックスタイルは「基本スタイル」と類似しているため、スタイルが空であっても、完全にスタイルが適用されたコントロールが生成されます。

フォールバックスタイル自体にもフォールバックスタイルを設定することができ、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"
        }
    }
}

解決された各プロパティは 1 行ずつ出力されます。例：

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

出力中の「StyleReader 」は、Button が内部でスタイルプロパティの値を読み取る際に使用するStyleReader を指しています。

filter プロパティを使用すると、対象となるプロパティのみを出力に限定できます。