StyleVariation QML Type

Defines alternative styling for specific controls. More...

This type is in technology preview and is subject to change.

• List of all members, including inherited members

Properties

• name : string

Attached Properties

• controlType : int
• variations : list<string>

Detailed Description

A StyleVariation lets you define alternative styling that can be applied to specific controls in the application (instance variations), or to all descendants of a particular parent control type (type variations). For example, you can give controls in a sidebar a compact appearance, or make buttons inside all toolbars look different from buttons elsewhere.

Instance Variations

Instance variations are activated by setting the variations attached property on any item in the application — all StyleKit controls that are children or descendants of that item will receive the alternative styling. Variations can also be set at multiple levels of the hierarchy simultaneously; when they conflict, the variation closest to the control takes precedence.

Instance variations are defined in the Style or Theme that they affect:

Style {
    StyleVariation {
        name: "mini"
        control {
            padding: 2
            background.implicitHeight: 15
            indicator.implicitWidth: 15
            indicator.implicitHeight: 15
            handle.implicitWidth: 15
            handle.implicitHeight: 15
        }
    }

    StyleVariation {
        name: "alert"
        abstractButton.background.color: "red"
    }
}

And they are applied from the application using the variations attached property:

GroupBox {
    title: "Mini controls"
    StyleVariation.variations: ["mini"]

    Row {
        spacing: 10
        Button { text: "Save" }
        CheckBox { text: "Option" }
        // This button also has the "alert" variation, in addition to "mini"
        Button {
            text: "Delete"
            StyleVariation.variations: ["alert"]
        }
    }
}

Variation names referred to from the application that are not defined in the active style (or theme) are silently ignored — they act as hints that the style author can choose to implement or leave unhandled.

Type Variations

Type variations are assigned to the variations property of a specific ControlStyle, without requiring a name. Unlike instance variations — which require the application to explicitly opt in — type variations are applied automatically to all controls of a given type whenever they are descendants of the specified parent control type.

The following snippet shows how to make all Buttons inside a Frame look distinct from buttons elsewhere:

Style {
    frame {
        variations: StyleVariation {
            button {
                text.color: "ghostwhite"
                background.border.width: 0
                background.color: "slategrey"
            }
        }
    }

    groupBox {
        // groupBox falls back to frame. Therefore, if the varations set on a
        // frame is not wanted on a groupBox, just override it and set it back to [].
        variations: []
    }
}

Because groupBox falls back to frame in the style hierarchy, type variations set on frame are automatically inherited by groupBox as well. To opt out, reset the variations for the subtype.

Propagation order

A StyleVariation is local to the Style or Theme where it is defined. A Theme cannot shadow an entire StyleVariation defined in the Style — only individual properties within it can be overridden, just like any other style property.

For example, if both the Style and the active Theme define frame.variations, both type variation arrays take effect for a Frame. The resolution order for individual properties is: the Theme's variation properties take precedence over the Theme's direct properties, which take precedence over the Style's variation properties, which take precedence over the Style's direct properties.

The same applies to instance variations. A StyleVariation defined in a Theme takes precedence over the Theme's direct properties. If a StyleVariation with the same name is also defined in the Style, both take effect, following the same resolution order as described above.

In the following snippet, a button with StyleVariation.variations: ["alert"] will be red in the light theme and cyan in the dark theme, with a 4-pixel border in both. Because the dark theme overrides button.background.radius to be 6, that property takes precedence over the background.radius set in the Style's variation. As a result, the button's radius ends up being 6 in the dark theme, but 0 in the light theme:

Style {
    button.background.radius: 2
    StyleVariation {
        name: "alert"
        button.background.border.width: 4
        button.background.radius: 0
    }

    light: Theme {
        StyleVariation {
            name: "alert"
            button.background.color: "red"
        }
    }

    dark: Theme {
        button.background.radius: 6
        StyleVariation {
            name: "alert"
            button.background.color: "cyan"
        }
    }
}

See also Style, Theme, ControlStyle.variations, and StyleVariation.variations.

Property Documentation

name : string

The name of this variation.

The name identifies this variation when used as an instance variation.

See also variations and Instance Variations.

Attached Property Documentation

StyleVariation.controlType : int [attached]

This property identifies the control type of the item it is attached to.

StyleKit uses it to resolve type variations for descendant controls — if a parent item's controlType matches a control type that has variations defined in the Style, those variations apply to all descendant controls.

Built-in StyleKit controls set this property automatically. Custom controls must set it explicitly to participate in type variation resolution.

See also ControlStyle.variations and StyleReader.

StyleVariation.variations : list<string> [attached]

This property holds the list of instance variations to activate for a Control, and its descendant controls.

If multiple variations in the list sets the same property, the first one in the list takes precedence.

If variations are set on both a parent item and a descendant control, both sets apply, with the control's own variations taking precedence over those inherited from the parent.

GroupBox {
    title: "Mini controls"
    StyleVariation.variations: ["mini"]

    Row {
        spacing: 10
        Button { text: "Save" }
        CheckBox { text: "Option" }
        // This button also has the "alert" variation, in addition to "mini"
        Button {
            text: "Delete"
            StyleVariation.variations: ["alert"]
        }
    }
}

See also name.