API Documentation

Documentation for developing SailfishOS applications

BackgroundItem QML Type

A simple Sailfish-styled item for building touch-interactive items More...

Import Statement: import Sailfish.Silica 1.0
Inherited By:

DialogHeader, GridItem, ListItem, RemorseItem, RemorsePopup, and ValueButton


Detailed Description

The BackgroundItem type provides a Sailfish-styled item with touch interaction. It provides a default item height and press highlighting behavior. Items that respond to pressing/tapping should use BackgroundItem where possible.

Here is a simple delegate based on BackgroundItem:

 import QtQuick 2.2
 import Sailfish.Silica 1.0

 SilicaListView {
     anchors.fill: parent
     model: 10
     delegate: BackgroundItem {
         width: ListView.view.width
         contentHeight: Theme.itemSizeSmall

         onClicked: console.log("clicked!")

         Label {
             text: "Click me"
             anchors.centerIn: parent
             color: highlighted ? Theme.highlightColor : Theme.primaryColor

Notice that the label text is colored differently when the item is highlighted. See the Theme documentation for guidelines on styling interactive controls in Sailfish OS.

BackgroundItem inherits the QtQuick MouseArea type, so any properties, signals and methods of MouseArea (such as the onClicked handler in the example above) are also available to BackgroundItem objects. See the MouseArea documentation for its full list of available properties, signals and methods.

Accessing child objects of BackgroundItem

BackgroundItem places its children in a contentItem which is sized to the size of the BackgroundItem. This is generally not noticable, though it does affect the usage of childrenRect, e.g.

 BackgroundItem {
     width: contentItem.childrenRect.width
     height: contentItem.childrenRect.height
     Label {
         text: "Hello"

Note that the above could have been written more efficiently without childrenRect:

 BackgroundItem {
     width: label.width
     height: label.height
     Label {
         id: label
         text: "Hello"

Property Documentation

contentHeight : real

This is an alias for contentItem.height.

contentItem : Item

This item contains the children of the BackgroundItem.

contentWidth : real

This is an alias for contentItem.width.

down : bool

This property is true while the BackgroundItem is pressed and the touch position remains within the BackgroundItem area.

See also MouseArea::pressed.

highlighted : bool

This property indicates whether the contents should be shown in a highlighted manner. For example, text shown within a BackgroundItem should be colored differently when highlighted is true:

 BackgroundItem {
     Label {
         text: "Hello"
         color: highlighted ? Theme.highlightColor : Theme.primaryColor

(See the Theme documentation for guidelines on styling interactive controls in Sailfish OS.)

By default, highlighted is true when the item is down.

highlightedColor : color

This property holds the color of the item when highlighted is true.

The default value is a partially-transparent Theme.highlightBackgroundColor.

We use cookies to improve your user experience and to help us to develop our services. By continuing to browse the site, you approve of our use of cookies.