ControlStateStyle QML Type

Defines the style for a control in a given state. More...

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

• List of all members, including inherited members

Properties

• background : DelegateStyle
• bottomPadding : real
• checked : ControlStateStyle
• disabled : ControlStateStyle
• focused : ControlStateStyle
• handle : HandleStyle
• highlighted : ControlStateStyle
• hovered : ControlStateStyle
• indicator : IndicatorStyle
• leftPadding : real
• padding : real
• pressed : ControlStateStyle
• rightPadding : real
• spacing : real
• text : TextStyle
• topPadding : real
• transition : Transition
• vertical : ControlStateStyle

Detailed Description

A ControlStateStyle contains the properties that can be styled for each state a control can be in. This includes the visual building blocks background, indicator, handle, and text, along with layout properties such as padding and spacing, and more.

A ControlStyle inherits ControlStateStyle, since it represents the normal state — that is, properties set directly on a ControlStyle describe how the control looks when no other state is active. State-specific overrides are set through nested states such as pressed, hovered, and checked, and can be animated by a transition.

Nested states are not mutually exclusive. Multiple states can be active at the same time — for example, a button can be both hovered and pressed simultaneously. When several states are active, all matching state overrides are applied. If the same property is set in multiple active states, conflicts are resolved using the following priority order: pressed, hovered, highlighted, focused, checked, vertical. So for example pressed.background.color wins over checked.background.color if the control is both pressed and checked.

The disabled state is an exception: a disabled control cannot be interacted with, so the pressed, hovered, highlighted, and focused states will not apply. However, disabled can still be combined with states like checked and vertical.

The more deeply nested a state is, the more qualified it is. For example, hovered.pressed.background.color takes precedence over hovered.background.color when both hovered and pressed are active. The nesting order does not matter: hovered.pressed and pressed.hovered are equivalent. However, if both forms are used at the same time, which one wins is undefined.

Deeper nesting of states can also be used to resolve conflicts. If the same property is set in both hovered and checked, the priority order means the hovered value wins. If you would rather have the checked value win, or use an altogether different value in that situation, you can override the property in hovered.checked, which then takes precedence over both.

The following snippet shows how to style a button differently depending on its state:

button {
    text.color: "white"
    background.color: "cornflowerblue"

    pressed.background.color: "cadetblue"
    hovered.background.color: "dodgerblue"
    highlighted.background.color: "lightblue"
    focused.background.color: "lightskyblue"
    checked.background.color: "darkseagreen"
    disabled.background.color: "gray"

    // hovered.checked takes precedence over both hovered and checked
    hovered.checked.background.color: "mediumseagreen"

    hovered.checked {
        // Nested states are grouped properties, so you can use the compact
        // per-property form above, or structure them hierarchically for
        // better readability. Both forms are functionally equivalent.
        pressed {
            // hovered.checked.pressed takes precedence over hovered.checked
            background {
                color: "mediumaquamarine"
                scale: 0.95
            }
            text {
                bold: true
            }
        }
    }
}

See also ControlStyle, DelegateStyle, and FallbackStyle Reference.

Property Documentation

background : DelegateStyle

Grouped property for styling the background of a control.

The background delegate is typically the main visual rectangle behind the control. Use it to set colors, borders, radii, shadows, gradients, and images.

bottomPadding : real

The bottom padding of the control. If not set, falls back to padding.

See also padding, topPadding, leftPadding, and rightPadding.

checked : ControlStateStyle

Style overrides applied when the control is in a checked or toggled-on state (e.g. a checked CheckBox or a toggled Button).

See also pressed, hovered, highlighted, focused, vertical, and disabled.

disabled : ControlStateStyle

Style overrides applied when the control is disabled.

A disabled control cannot be interacted with, so pressed, hovered, highlighted, and focused will not be applied at the same time as disabled.

See also pressed, hovered, highlighted, focused, checked, and vertical.

focused : ControlStateStyle

Style overrides applied when the control has input focus.

See also pressed, hovered, highlighted, checked, vertical, and disabled.

handle : HandleStyle

Grouped property for styling the handle of a control.

The handle is used by controls such as Switch, Slider, and RangeSlider. For a RangeSlider, the two handles can be styled individually through handle.first and handle.second.

See also HandleStyle and DelegateStyle.

highlighted : ControlStateStyle

Style overrides applied when the control is highlighted. A control is typically highlighted in order to draw the user's attention towards it.

See also pressed, hovered, focused, checked, vertical, and disabled.

hovered : ControlStateStyle

Style overrides applied when the mouse cursor is over the control.

See also pressed, highlighted, focused, checked, vertical, and disabled.

indicator : IndicatorStyle

Grouped property for styling the indicator of a control. For a checkBox, the indicator is the frame, and its foreground is the check mark. For a slider, the indicator is the groove, and the foreground is the fill.

See also DelegateStyle.

leftPadding : real

The left padding of the control. If not set, falls back to padding.

See also padding, rightPadding, topPadding, and bottomPadding.

padding : real

The uniform spacing between the control's content area and the bounds of the control. Setting this provides a default value for leftPadding, rightPadding, topPadding, and bottomPadding. Each side can be overridden individually.

See also leftPadding, rightPadding, topPadding, and bottomPadding.

pressed : ControlStateStyle

Style overrides applied when the control is pressed (e.g. the user is holding down a mouse button on it).

See also hovered, highlighted, focused, checked, vertical, and disabled.

rightPadding : real

The right padding of the control. If not set, falls back to padding.

See also padding, leftPadding, topPadding, and bottomPadding.

spacing : real

The spacing between visual elements inside the control, for example between an indicator and a label.

text : TextStyle

Grouped property for styling the text label of a control.

topPadding : real

The top padding of the control. If not set, falls back to padding.

See also padding, bottomPadding, leftPadding, and rightPadding.

transition : Transition

A Transition used to animate style properties when the control enters a new state, such as hovered or pressed. If set to null (the default), property changes are applied immediately without animation.

button {
    background.color: "mistyrose"
    hovered.background.color: "plum"
    transition: Transition {
        ColorAnimation {
            properties: "background.color, background.shadow.color, handle.color"
            easing.type: Easing.OutQuad
            duration: 500
        }
        NumberAnimation {
            properties: "background.leftRadius, background.rightRadius"
            easing.type: Easing.OutQuad
            duration: 500
        }
    }

    // I only want a fade-out effect (not fade-in). So while the button
    // is hovered, remove the transition, so that it only applies in the
    // normal state. In other words, it's the state being entered that
    // determines the transition, not the state that is left.
    hovered.transition: null
}

To avoid repeating the same target properties for each delegate, StyleKit provides StyleAnimation for convenience, which can be used instead of, or in combination with, the standard animations:

comboBox {
    background.color: "mistyrose"
    hovered.background.color: "plum"
    transition: Transition {
        StyleAnimation {
            animateColors: true
            animateBackgroundRadii: true
            animateIndicatorRadii: true
            animateBackgroundShadow: true
            easing.type: Easing.OutQuad
            duration: 500
        }
    }
}

Also note that ColorAnimation has a special feature that animates all color properties that changed during a state change if property and properties are left unset.

vertical : ControlStateStyle

Style overrides applied when the control has a vertical orientation (e.g. a vertical Slider or ScrollBar).

See also pressed, hovered, highlighted, focused, checked, and disabled.