Auflösung von StyleKit-Eigenschaften

Eine Stileigenschaft – wie beispielsweise „ background.color “ – kann je nach dem „ state “ des Steuerelements, dem aktiven „ Theme “ und dem effektiven „ style variations “ viele verschiedene Werte annehmen. So kann sie sich beispielsweise zwischen den Zuständen „ pressed “ und „ hovered “ oder zwischen den Designs „ light “ und „ dark “ unterscheiden. In diesem Dokument wird detailliert beschrieben, wie „ StyleKit “ den Wert ermittelt, den eine Eigenschaft erhält, wenn sie zur Gestaltung eines bestimmten „ Control “ verwendet wird.

Zustände von Steuerelementen

Steuerelemente ändern ihr Erscheinungsbild je nach Interaktion – hovered, pressed, checked, focused, disabled und so weiter. Bei der Auflösung einer Eigenschaft prüft StyleKit zunächst alle zustandsspezifischen Werte, bevor der Normalzustand überprüft wird.

Wenn beispielsweise eine „ Button “ der Wert „ hovered “ ist, wird „ hovered.button.background.color “ vor „ button.background.color “ geprüft. Und wenn sie zudem „ pressed “ ist, wird „ pressed.button.background.color “ vor beiden geprüft. Die Rangfolge der Zustände ist im „ ControlStateStyle documentation “ dokumentiert.

Zustände können auch verschachtelt werden. Eine Kombination wie pressed.hovered.button.background.color ist spezifischer als entweder pressed.button.background.color oder hovered.button.background.color allein und hat Vorrang vor beiden.

Fallback-Eigenschaften

Einige Stileigenschaften können auf mehr als eine Weise festgelegt werden. Beispielsweise kann der Radius der oberen linken Ecke des Hintergrunds entweder direkt mit „ background.topLeftRadius “ oder indirekt mit „ background.radius “ (wodurch alle Ecken auf denselben Radius gesetzt werden) festgelegt werden. Bei solchen Eigenschaften prüft StyleKit zuerst die spezifische Eigenschaft, dann die Fallback-Eigenschaft und erschöpft beide im aktuellen Zustand, bevor zu einem weniger spezifischen Zustand übergegangen wird. Beispielsweise hat button.hovered.background.radius Vorrang vor button.background.topLeftRadius, wenn der Mauszeiger über dem Steuerelement schwebt. Und natürlich hat button.hovered.background.topLeftRadius Vorrang vor beiden.

Hierarchie der Steuerelementtypen

The controls bilden eine Hierarchie. Ein „ button “ greift auf „ abstractButton “ zurück, das wiederum auf „ control “ zurückgreift. Ein „ groupBox “ greift auf „ frame “ zurück, das wiederum auf „ pane “ zurückgreift, welches wiederum auf „ control “ zurückgreift und so weiter. „ control “ ist der Stammtyp in der Hierarchie und spiegelt die Typenhierarchie von Qt Quick Controls. In der „ documentation “ für jeden Steuerelementtyp finden Sie den direkten Fallback-Typ.

Wenn alle Zustände und Fallback-Eigenschaften für einen bestimmten Steuerelementtyp ausgeschöpft sind, durchläuft „ StyleKit “ die Hierarchie nach oben, um zu prüfen, ob der Wert in einem Basistyp festgelegt ist. Ist beispielsweise „ button.background.color “ nicht festgelegt, prüft „ StyleKit “ stattdessen „ abstractButton.background.color “ und so weiter. Dies motiviert den Entwickler, die Eigenschaftswerte, die mehreren Steuerelementen gemeinsam sind, in einem gemeinsamen Basistyp zusammenzufassen, um die Wiederverwendbarkeit zu maximieren und Duplikate zu minimieren. So können Sie beispielsweise alle Eigenschaftswerte, die Schaltflächen, Kontrollkästchen und Optionsfeldern gemeinsam sind, in „ abstractButton “ zusammenfassen und in den spezifischen Untertypen nur die Eigenschaften festlegen, die sich unterscheiden.

Beachten Sie, dass jeder Zustand (einschließlich des Normalzustands) in einem spezifischeren Typ Vorrang vor jedem Zustand in einem Basistyp hat. Beispielsweise hat „ button.background.color “ Vorrang vor „ hovered.abstractButton.background.color “, selbst wenn der Mauszeiger über dem Steuerelement schwebt. Und natürlich hat „ hovered.button.background.color “ Vorrang vor beiden.

Stil und Design

Die Steuerelement-Typhierarchie wiederholt sich sowohl innerhalb eines „ Style “ als auch eines „ Theme “. Bei der Auflösung einer Eigenschaft durchsucht „ StyleKit “ zunächst die Steuerelement-Typhierarchie im aktiven „ Theme “ und anschließend im aktiven „ Style “. Das bedeutet, dass im aktiven Thema festgelegte Eigenschaften Vorrang vor denen im Stil haben. Folglich überschreibt ein Basistyp im Thema auch einen spezifischeren Typ im Stil. Beispielsweise hat „ theme.control.background.color “ Vorrang vor „ style.button.background.color “.

Stilvarianten

Die Steuerelement-Typ-Hierarchie wird innerhalb eines „ StyleVariation “ wiederholt. Stilvariationen können sowohl in einem Stil als auch in einem Thema definiert werden, wobei eine Stilvariation im Thema Vorrang vor dem Thema selbst hat. Da ein Thema Vorrang vor einem Stil hat, haben die Stileigenschaften im aktuellen Thema ebenfalls Vorrang vor den Stilvariationen im Stil. Beispielsweise hat „ theme.button.background.color “ Vorrang vor „ style.variation.button.background.color “.

Fallback-Stil

Jedes „ Style “ verfügt über einen „ fallback style “ – einen vollständigen Stil, der als letzte Instanz dient, wenn eine Eigenschaft innerhalb des aktiven Stils nicht aufgelöst werden kann. Wenn der vollständige Auflösungsprozess (über Steuerelementtypen, Zustände, das aktive Thema und alle Stilvarianten hinweg) keinen Wert findet, wiederholt „ StyleKit “ den gesamten Prozess im Fallback-Stil. Der Standard-Fallback-Stil ähnelt dem „Basic Style“, sodass selbst ein leerer Stil vollständig gestylte Steuerelemente erzeugt.

Der Fallback-Stil kann selbst einen Fallback-Stil haben, und „ StyleKit “ folgt dieser Kette rekursiv, bis entweder ein Wert gefunden wird oder die Kette erschöpft ist. Wird kein Wert gefunden, wird ein Standardwert verwendet.

Alles zusammen

Nehmen wir als Beispiel an, „ StyleKit “ muss „ background.color “ für „ hovered “ Button auflösen. Der Stil verfügt über ein Thema, und sowohl der Stil als auch das Thema haben eine aktive Variante. „ StyleKit “ überprüft dann der Reihe nach die folgenden Speicherorte und verwendet dabei den ersten gefundenen Wert:

• 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

Wenn alle diese Speicherorte durchsucht wurden, ohne dass ein Wert gefunden wurde, wird derselbe Vorgang im Fallback-Stil wiederholt (rekursiv, falls der Fallback-Stil ebenfalls einen Fallback-Stil hat). Wird der Wert immer noch nicht gefunden, wird ein Standardwert verwendet.

Fehlerbehebung bei der Eigenschaftsauflösung

Da mehrere Steuerelementtypen, Designs, Variationen und Fallback-Stile zum endgültigen Wert einer Eigenschaft beitragen, ist es manchmal schwer zu erkennen, warum ein bestimmtes Steuerelement letztendlich ein bestimmtes Erscheinungsbild aufweist. „ StyleKitDebug “ ist ein diagnostisches In-App-Tool, das jede gelesene Stileigenschaft in der Debug-Ausgabe protokolliert und genau anzeigt, aus welcher Ebene und welchem Steuerelementtyp eine Eigenschaft aufgelöst wurde.

Um die Ablaufverfolgung zu starten, weisen Sie das Steuerelement, das Sie untersuchen möchten, der Eigenschaft „ StyleKit.debug.control “ zu:

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"
        }
    }
}

Jede aufgelöste Eigenschaft wird als einzelne Zeile ausgegeben, zum Beispiel:

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

Der Begriff „ StyleReader “ in der Ausgabe bezieht sich auf den „ StyleReader “, den das „ Button “ intern zum Auslesen seiner Stil-Eigenschaftswerte verwendet.

Verwenden Sie die Eigenschaft „ filter “, um die Ausgabe auf die für Sie relevanten Eigenschaften zu beschränken.