Résolution des propriétés StyleKit

Une propriété de style — telle que background.color — peut prendre de nombreuses valeurs différentes en fonction de l’ state du contrôle, de l’ Theme active et de l’ style variations effective. Par exemple, elle peut varier entre les états pressed et hovered, ou entre les thèmes light et dark. Ce document explique en détail comment StyleKit détermine la valeur qu’une propriété prendra lorsqu’elle est utilisée pour styliser un Control particulier.

États des contrôles

Les contrôles changent d’apparence en fonction de l’interaction — hovered, pressed, checked, focused, disabled, etc. Lors de la résolution d’une propriété, StyleKit explore d’abord toutes les valeurs spécifiques à chaque état avant de vérifier l’état normal.

Par exemple, si une propriété « Button » prend la valeur « hovered », « hovered.button.background.color » est vérifiée avant « button.background.color ». Et si elle prend également la valeur « pressed », « pressed.button.background.color » est vérifiée avant ces deux-là. L’ordre de priorité entre les états est documenté dans le document « ControlStateStyle documentation ».

Les états peuvent également être imbriqués. Une combinaison telle que pressed.hovered.button.background.color est plus spécifique que pressed.button.background.color ou hovered.button.background.color pris isolément, et a priorité sur les deux.

Propriétés de repli

Certaines propriétés de style peuvent être définies de plusieurs façons. Par exemple, le rayon du coin supérieur gauche de l’arrière-plan peut être défini soit directement à l’aide de ` background.topLeftRadius`, soit indirectement à l’aide de ` background.radius ` (qui définit le même rayon pour tous les coins). Pour ces propriétés, StyleKit vérifie d’abord la propriété spécifique, puis la propriété de secours, et épuise les deux dans l’état actuel avant de passer à un état moins spécifique. Par exemple, button.hovered.background.radius a priorité sur button.background.topLeftRadius si le curseur survole le contrôle. Et bien sûr, button.hovered.background.topLeftRadius a priorité sur les deux.

Hiérarchie des types de contrôles

The controls forment une hiérarchie. Un button a pour solution de repli abstractButton, qui a pour solution de repli control. Un groupBox a pour solution de repli frame, qui a pour solution de repli pane, qui a pour solution de repli control, et ainsi de suite. control est le type racine de la hiérarchie, reflétant la hiérarchie des types de Qt Quick Controls. Reportez-vous à la documentation documentation pour chaque type de contrôle afin de connaître son type de repli direct.

Lorsque tous les états et toutes les propriétés de repli ont été épuisés pour un type de contrôle spécifique, StyleKit remonte la hiérarchie pour vérifier si la propriété est définie dans un type de base. Par exemple, si button.background.color n’est pas défini, StyleKit vérifiera abstractButton.background.color à la place, et ainsi de suite. Cela incite le concepteur à regrouper les valeurs de propriétés communes à plusieurs contrôles dans un type de base commun, afin de maximiser la réutilisation et de minimiser les doublons. Par exemple, vous pouvez placer toutes les valeurs de propriétés communes aux boutons, cases à cocher et boutons radio dans abstractButton, et ne définir que les propriétés qui diffèrent dans les sous-types spécifiques.

Notez que tout état (y compris l’état normal) d’un type plus spécifique prévaut sur tout état d’un type de base. Par exemple, ` button.background.color ` prévaut sur ` hovered.abstractButton.background.color`, même si le curseur survole le contrôle. Et bien sûr, ` hovered.button.background.color ` prévaut sur les deux.

Style et thème

La hiérarchie des types de contrôles se retrouve à la fois dans un « Style » et dans un « Theme ». Lors de la résolution d’une propriété, « StyleKit » examine d’abord la hiérarchie des types de contrôles dans l’ Theme actif, puis dans l’ Style actif. Cela signifie que les propriétés définies dans le thème actif ont priorité sur celles définies dans le style. Par conséquent, un type de base dans le thème remplace également un type plus spécifique dans le style. Par exemple, theme.control.background.color a priorité sur style.button.background.color.

Variations de style

La hiérarchie des types de contrôles est reproduite à l’intérieur d’un « StyleVariation ». Les variations de style peuvent être définies à la fois dans un style et dans un thème, et une variation de style dans un thème a priorité sur le thème lui-même. Étant donné qu’un thème a priorité sur un style, les propriétés de style du thème actuel auront également priorité sur les variations de style définies dans le style. Par exemple, theme.button.background.color a priorité sur style.variation.button.background.color.

Style de secours

Chaque contrôle Style dispose d’un style de secours ( fallback style ) : il s’agit d’un style complet qui sert de dernier recours lorsqu’une propriété ne peut pas être résolue au sein du style actif. Si le processus de résolution complet (couvrant les types de contrôles, les états, le thème actif et toutes les variations de style) ne parvient pas à trouver une valeur, StyleKit répète l’intégralité du processus dans le style de secours. Le style de secours par défaut ressemble au style de base; ainsi, même un style vide produira des contrôles entièrement stylisés.

Le style de secours peut lui-même disposer d’un style de secours, et StyleKit suit cette chaîne de manière récursive jusqu’à ce qu’il trouve une valeur ou que la chaîne soit épuisée. Si aucune valeur n’est trouvée, une valeur par défaut est utilisée.

Mise en pratique

À titre d’exemple, supposons qu’ StyleKit doive résoudre background.color pour un hovered Button . Le style possède un thème, et le style comme le thème disposent tous deux d’une variation active. StyleKit vérifie alors les emplacements suivants dans l’ordre, en utilisant la première valeur trouvée :

• 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

Si aucun emplacement n’a été trouvé après avoir épuisé tous ces emplacements, le même processus est répété dans le style de secours (de manière récursive, si le style de secours dispose lui-même d’un style de secours). Si la valeur n’est toujours pas trouvée, une valeur par défaut est utilisée.

Débogage de la résolution des propriétés

Étant donné que plusieurs types de contrôles, thèmes, variantes et styles de secours contribuent tous à la valeur finale d’une propriété, il peut parfois être difficile de déterminer pourquoi un contrôle particulier présente une apparence donnée. StyleKitDebug est un outil de diagnostic intégré à l’application qui consigne chaque propriété de style lue dans la sortie de débogage, indiquant exactement à partir de quelle couche et de quel type de contrôle une propriété a été résolue.

Pour lancer le traçage, attribuez le contrôle que vous souhaitez analyser à la propriété « 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"
        }
    }
}

Chaque propriété résolue est affichée sur une ligne distincte, par exemple :

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

Le « StyleReader » dans la sortie fait référence à l’ StyleReader que l’ Button utilise en interne pour lire les valeurs de ses propriétés de style.

Utilisez la propriété ` filter ` pour limiter la sortie aux propriétés qui vous intéressent.