Delegate

When it comes to using models and views in a custom user interface, the delegate plays a huge role in creating a look and behaviour. As each item in a model is visualized through a delegate, what is actually visible to the user are the delegates.

Each delegate gets access to a number of attached properties, some from the data model, others from the view. From the model, the properties convey the data for each item to the delegate. From the view, the properties convey state information related to the delegate within the view. Let’s dive into the properties from the view.

The most commonly used properties attached from the view are ListView.isCurrentItem and ListView.view. The first is a boolean indicating if the item is the current item, while the latter is a read-only reference to the actual view. Through access to the view, it is possible to create general, reusable delegates that adapt to the size and nature of the view in which they are contained. In the example below, the width of each delegate is bound to the width of the view, while the background color of each delegate depends on the attached ListView.isCurrentItem property.

  1. import QtQuick 6.2
  3. Rectangle {
  4.     width: 120
  5.     height: 300
  7.     gradient: Gradient {
  8.         GradientStop { position: 0.0; color: "#f6f6f6" }
  9.         GradientStop { position: 1.0; color: "#d7d7d7" }
  10.     }
  12.     ListView {
  13.         anchors.fill: parent
  14.         anchors.margins: 20
  16.         clip: true
  18.         model: 100
  20.         delegate: numberDelegate
  21.         spacing: 5
  23.         focus: true
  24.     }
  26.     Component {
  27.         id: numberDelegate
  29.         Rectangle {
  30.             width: ListView.view.width
  31.             height: 40
  33.             color: ListView.isCurrentItem?"#157efb":"#53d769"
  34.             border.color: Qt.lighter(color, 1.1)
  36.             Text {
  37.                 anchors.centerIn: parent
  39.                 font.pixelSize: 10
  41.                 text: index
  42.             }
  43.         }
  44.     }
  45. }

image

If each item in the model is associated with an action, for instance, clicking an item acts upon it, that functionality is a part of each delegate. This divides the event management between the view, which handles the navigation between items in the view, and the delegate which handles actions on a specific item.

The most basic way to do this is to create a MouseArea within each delegate and act on the onClicked signal. This is demonstrated in the example in the next section of this chapter.

Animating Added and Removed Items

In some cases, the contents shown in a view changes over time. Items are added and removed as the underlying data model is altered. In these cases, it is often a good idea to employ visual cues to give the user a sense of direction and to help the user understand what data is added or removed.

Conveniently enough, QML views attach two signals, onAdd and onRemove, to each item delegate. By triggering animations from these, it is easy to create the movement necessary to aid the user in identifying what is taking place.

The example below demonstrates this through the use of a dynamically populated ListModel. At the bottom of the screen, a button for adding new items is shown. When it is clicked, a new item is added to the model using the append method. This triggers the creation of a new delegate in the view, and the emission of the GridView.onAdd signal. The SequentialAnimation called addAnimation is started from the signal causes the item to zoom into view by animating the scale property of the delegate.

When a delegate in the view is clicked, the item is removed from the model through a call to the remove method. This causes the GridView.onRemove signal to be emitted, starting the removeAnimation SequentialAnimation. This time, however, the destruction of the delegate must be delayed until the animation has completed. To do this, PropertyAction element is used to set the GridView.delayRemove property to true before the animation, and false after. This ensures that the animation is allowed to complete before the delegate item is removed.

  1. import QtQuick 6.2
  3. Rectangle {
  4.     width: 480
  5.     height: 300
  7.     gradient: Gradient {
  8.         GradientStop { position: 0.0; color: "#dbddde" }
  9.         GradientStop { position: 1.0; color: "#5fc9f8" }
  10.     }
  12.     ListModel {
  13.         id: theModel
  15.         ListElement { number: 0 }
  16.         ListElement { number: 1 }
  17.         ListElement { number: 2 }
  18.         ListElement { number: 3 }
  19.         ListElement { number: 4 }
  20.         ListElement { number: 5 }
  21.         ListElement { number: 6 }
  22.         ListElement { number: 7 }
  23.         ListElement { number: 8 }
  24.         ListElement { number: 9 }
  25.     }
  27.     Rectangle {
  28.         anchors.left: parent.left
  29.         anchors.right: parent.right
  30.         anchors.bottom: parent.bottom
  31.         anchors.margins: 20
  33.         height: 40
  35.         color: "#53d769"
  36.         border.color: Qt.lighter(color, 1.1)
  38.         Text {
  39.             anchors.centerIn: parent
  41.             text: "Add item!"
  42.         }
  44.         MouseArea {
  45.             anchors.fill: parent
  47.             onClicked: {
  48.                 theModel.append({"number": ++parent.count});
  49.             }
  50.         }
  52.         property int count: 9
  53.     }
  55.     GridView {
  56.         anchors.fill: parent
  57.         anchors.margins: 20
  58.         anchors.bottomMargin: 80
  60.         clip: true
  62.         model: theModel
  64.         cellWidth: 45
  65.         cellHeight: 45
  67.         delegate: numberDelegate
  68.     }
  70.     Component {
  71.         id: numberDelegate
  73.         Rectangle {
  74.             id: wrapper
  76.             width: 40
  77.             height: 40
  79.             gradient: Gradient {
  80.                 GradientStop { position: 0.0; color: "#f8306a" }
  81.                 GradientStop { position: 1.0; color: "#fb5b40" }
  82.             }
  84.             Text {
  85.                 anchors.centerIn: parent
  87.                 font.pixelSize: 10
  89.                 text: number
  90.             }
  92.             MouseArea {
  93.                 anchors.fill: parent
  95.                 onClicked: {
  96.                     theModel.remove(index);
  97.                 }
  98.             }
  100.             GridView.onRemove: removeAnimation.start();
  102.             SequentialAnimation {
  103.                 id: removeAnimation
  105.                 PropertyAction { target: wrapper; property: "GridView.delayRemove"; value: true }
  106.                 NumberAnimation { target: wrapper; property: "scale"; to: 0; duration: 250; easing.type: Easing.InOutQuad }
  107.                 PropertyAction { target: wrapper; property: "GridView.delayRemove"; value: false }
  108.             }
  110.             GridView.onAdd: addAnimation.start();
  112.             SequentialAnimation {
  113.                 id: addAnimation
  114.                 NumberAnimation { target: wrapper; property: "scale"; from: 0; to: 1; duration: 250; easing.type: Easing.InOutQuad }
  115.             }
  116.         }
  117.     }
  118. }

Shape-Shifting Delegates

A commonly used mechanism in lists is that the current item is expanded when activated. This can be used to dynamically let the item expand to fill the screen to enter a new part of the user interface, or it can be used to provide slightly more information for the current item in a given list.

In the example below, each item is expanded to the full extent of the ListView containing it when clicked. The extra space is then used to add more information. The mechanism used to control this is a state expanded that each item delegate can enter, where the item is expanded. In that state, a number of properties are altered.

First of all, the height of the wrapper is set to the height of the ListView. The thumbnail image is then enlarged and moved down to make it move from its small position into its larger position. In addition to this, the two hidden items, the factsView and closeButton are shown by altering the opacity of the elements. Finally, the ListView is setup.

Setting up the ListView involves setting the contentsY, that is the top of the visible part of the view, to the y value of the delegate. The other change is to set interactive of the view to false. This prevents the view from moving. The user can no longer scroll through the list or change the current item.

As the item first is clicked, it enters the expanded state, causing the item delegate to fill the ListView and the contents to rearrange. When the close button is clicked, the state is cleared, causing the delegate to return to its previous state and re-enabling the ListView.

  1. import QtQuick 6.2
  3. Item {
  4.     width: 300
  5.     height: 480
  7.     Rectangle {
  8.         anchors.fill: parent
  9.         gradient: Gradient {
  10.             GradientStop { position: 0.0; color: "#4a4a4a" }
  11.             GradientStop { position: 1.0; color: "#2b2b2b" }
  12.         }
  13.     }
  15.     ListView {
  16.         id: listView
  18.         anchors.fill: parent
  20.         delegate: detailsDelegate
  21.         model: planets
  22.     }
  24.     ListModel {
  25.         id: planets
  27.         ListElement { name: "Mercury"; imageSource: "images/mercury.jpeg"; facts: "Mercury is the smallest planet in the Solar System. It is the closest planet to the sun. It makes one trip around the Sun once every 87.969 days." }
  28.         ListElement { name: "Venus"; imageSource: "images/venus.jpeg"; facts: "Venus is the second planet from the Sun. It is a terrestrial planet because it has a solid, rocky surface. The other terrestrial planets are Mercury, Earth and Mars. Astronomers have known Venus for thousands of years." }
  29.         ListElement { name: "Earth"; imageSource: "images/earth.jpeg"; facts: "The Earth is the third planet from the Sun. It is one of the four terrestrial planets in our Solar System. This means most of its mass is solid. The other three are Mercury, Venus and Mars. The Earth is also called the Blue Planet, 'Planet Earth', and 'Terra'." }
  30.         ListElement { name: "Mars"; imageSource: "images/mars.jpeg"; facts: "Mars is the fourth planet from the Sun in the Solar System. Mars is dry, rocky and cold. It is home to the largest volcano in the Solar System. Mars is named after the mythological Roman god of war because it is a red planet, which signifies the colour of blood." }
  31.     }
  33.     Component {
  34.         id: detailsDelegate
  36.         Item {
  37.             id: wrapper
  39.             width: listView.width
  40.             height: 30
  42.             Rectangle {
  43.                 anchors.left: parent.left
  44.                 anchors.right: parent.right
  45.                 anchors.top: parent.top
  47.                 height: 30
  49.                 color: "#333"
  50.                 border.color: Qt.lighter(color, 1.2)
  51.                 Text {
  52.                     anchors.left: parent.left
  53.                     anchors.verticalCenter: parent.verticalCenter
  54.                     anchors.leftMargin: 4
  56.                     font.pixelSize: parent.height-4
  57.                     color: '#fff'
  59.                     text: name
  60.                 }
  61.             }
  64.             Rectangle {
  65.                 id: image
  67.                 width: 26
  68.                 height: 26
  70.                 anchors.right: parent.right
  71.                 anchors.top: parent.top
  72.                 anchors.rightMargin: 2
  73.                 anchors.topMargin: 2
  75.                 color: "black"
  78.                 Image {
  79.                     anchors.fill: parent
  81.                     fillMode: Image.PreserveAspectFit
  83.                     source: imageSource
  84.                 }
  85.             }
  87.             MouseArea {
  88.                 anchors.fill: parent
  89.                 onClicked: parent.state = "expanded"
  90.             }
  92.             Item {
  93.                 id: factsView
  95.                 anchors.top: image.bottom
  96.                 anchors.left: parent.left
  97.                 anchors.right: parent.right
  98.                 anchors.bottom: parent.bottom
  100.                 opacity: 0
  102.                 Rectangle {
  103.                     anchors.fill: parent
  105.                     gradient: Gradient {
  106.                         GradientStop { position: 0.0; color: "#fed958" }
  107.                         GradientStop { position: 1.0; color: "#fecc2f" }
  108.                     }
  109.                     border.color: '#000000'
  110.                     border.width: 2
  112.                     Text {
  113.                         anchors.fill: parent
  114.                         anchors.margins: 5
  116.                         clip: true
  117.                         wrapMode: Text.WordWrap
  118.                         color: '#1f1f21'
  120.                         font.pixelSize: 12
  122.                         text: facts
  123.                     }
  124.                 }
  125.             }
  127.             Rectangle {
  128.                 id: closeButton
  130.                 anchors.right: parent.right
  131.                 anchors.top: parent.top
  132.                 anchors.rightMargin: 2
  133.                 anchors.topMargin: 2
  135.                 width: 26
  136.                 height: 26
  138.                 color: "#157efb"
  139.                 border.color: Qt.lighter(color, 1.1)
  141.                 opacity: 0
  143.                 MouseArea {
  144.                     anchors.fill: parent
  145.                     onClicked: wrapper.state = ""
  146.                 }
  147.             }
  149.             states: [
  150.                 State {
  151.                     name: "expanded"
  153.                     PropertyChanges { target: wrapper; height: listView.height }
  154.                     PropertyChanges { target: image; width: listView.width; height: listView.width; anchors.rightMargin: 0; anchors.topMargin: 30 }
  155.                     PropertyChanges { target: factsView; opacity: 1 }
  156.                     PropertyChanges { target: closeButton; opacity: 1 }
  157.                     PropertyChanges { target: wrapper.ListView.view; contentY: wrapper.y; interactive: false }
  158.                 }
  159.             ]
  161.             transitions: [
  162.                 Transition {
  163.                     NumberAnimation {
  164.                         duration: 200;
  165.                         properties: "height,width,anchors.rightMargin,anchors.topMargin,opacity,contentY"
  166.                     }
  167.                 }
  168.             ]
  169.         }
  170.     }
  171. }

image

image

The techniques demonstrated here to expand the delegate to fill the entire view can be employed to make an item delegate shift shape in a much smaller way. For instance, when browsing through a list of songs, the current item could be made slightly larger, accommodating more information about that particular item.