Contents

ItemStyle

The ItemStyle attached property contains styling properties for a particular UI element. More...

Properties

Detailed Description

The element provides styling support to any element derived from Item (QQuickItem). The style is selected based on the class and name properties. If neither of these is defined, the framework will use the meta class name to identify the style rule to be used. However this can happen only if the document defining the item refers to the styling attached property.

The following items will use styling as they declare and refer to styling attached properties, and styling Text can be done by defining the ".Text" selector.

Item {
   ItemStyle.class: "button"
}
Text {
   color: (ItemStyle.style) ? ItemStyle.style.color : "black"
}

An item can use private styling by setting the style and/or the delegate property locally. In this case the item won't use the theme defined style/delegate but will use the styling elements defined locally. Switching back to theme defined styles can be achieved by clearing the style/delegate property. It is also possible to set only one of the styling elements locally and use the theme defined one for the other.

// Button.qml
Item {
   id: root
   property bool pressed: false
   property bool hovered: false
   property color color: (ItemStyle.style) ? ItemStyle.style.color : "lightgray"

   signal clicked

   MouseArea {
      anchors.fill: parent
      onClicked: control.clicked()
   }
}

In the example above the Button document refers to the style property of the attached styling, therefore the element by default will use the style defined using the ".Button" selector.

The following example shows a Button item that uses a private delegate but the styles from the themes.

Button {
   id: control
   ItemStyle.delegate: Rectangle {
      anchors.fill: parent
      color: ItemStyle.style.color
      radius: 15
      border {
          width: 2
          color: Qt.darker(color, 1.4)
      }
   }
}

The style is usually applied immediately when a styling property is changed. This may cause performance problems as there are two properties that can affect the style applied. In case the component handles the "Component.onCompleted" signal, the styling will be applied only when the completion occurs. Therefore items can handle the completion by simply adding an empty handler to delay styling. Modifying the Button.qml example above, the component that applies styling on completion would look as follows:

Item {
   id: root
   property bool pressed: false
   property bool hovered: false
   property color color: (ItemStyle.style) ? ItemStyle.style.color : "lightgray"

   signal clicked

   MouseArea {
      anchors.fill: parent
      onClicked: control.clicked()
   }

   Component.onCompleted:{}
}

Attached styling defines two properties in the styling context that can be used from delegates to access the item and the style proeprties. item properties can be accessed through "item", and styling properties through "itemStyle" property.

Property Documentation

class : string

This property holds the style class identifier used by the item. When the engine locates the style rule to be applied on the item, it takes the class and name properties. If none is specified, the meta class name will be used to search for the style. This must be taken into account both when defining themes and designing items and applications.


delegate : Item

The property holds the Item containing the visuals. This can either be defined by a theme or can be a private element. When set, the item will no longer use the theme defined visuals but the ones set. The property must be reset (set to null object) in order to use the theme defined visuals.

Modifying the property alone will only affect the visuals. Styles can be still used from the theme, unless specified explicitly. Therefore custom visuals can be made so that are aware of the styling properties.


name : string

This property holds the item unique identifier used in styling.


path : string

This property holds the style path applied on the attachee item.


style : QtObject

The property holds the object containing the style configuration properties. This can either be defined by a theme style rule or the private style. When set, the item will no longer use the theme defined style properties but the ones set. The property must be reset (set to null object) in order to use the theme defined styles.

Modifying the property alone will only affect the styling. The delegate will be used from the theme unless specified explicitly. Therefore items can be used with custom styling and theme defined delegate, theme style and custom delegate or both theme defined/ custom.