SwipeDelegate QML Type | Qt Quick Controls 2 5.9

Qt 5.9 | Qt Quick Controls 2 | QML Types | SwipeDelegate QML Type

Qt 5.9.2 Reference Documentation

# SwipeDelegate QML Type

Swipable item delegate. More...

Import Statement: | import QtQuick.Controls 2.2
Since: | Qt 5.7
Inherits: | ItemDelegate

- List of all members, including inherited members

## Properties

- swipe
  - swipe.position : real
  - swipe.complete : bool
  - swipe.enabled : bool
  - swipe.left : Component
  - swipe.behind : Component
  - swipe.right : Component
  - swipe.leftItem : Item
  - swipe.behindItem : Item
  - swipe.rightItem : Item
  - swipe.transition : Transition

## Attached Properties

- pressed : bool

## Signals

- void swipe.closed()
- void swipe.completed()
- void swipe.opened()

## Attached Signals

- void clicked()

## Methods

- void swipe.close()
- void swipe.open(enumeration side)

## Detailed Description

SwipeDelegate presents a view item that can be swiped left or right to expose more options or information. It is used as a delegate in views such as ListView.

In the following example, SwipeDelegate is used in a ListView to allow items to be removed from it by swiping to the left:

      ListView {
          id: listView
          anchors.fill: parent
          model: ListModel {
              ListElement { sender: "Bob Bobbleton"; title: "How are you going?" }
              ListElement { sender: "Rug Emporium"; title: "SALE! All rugs MUST go!" }
              ListElement { sender: "Electric Co."; title: "Electricity bill 15/07/2016 overdue" }
              ListElement { sender: "Tips"; title: "Five ways this tip will save your life" }
          }
          delegate: SwipeDelegate {
              id: swipeDelegate
              text: model.sender + " - " + model.title
              width: parent.width

              ListView.onRemove: SequentialAnimation {
                  PropertyAction {
                      target: swipeDelegate
                      property: "ListView.delayRemove"
                      value: true
                  }
                  NumberAnimation {
                      target: swipeDelegate
                      property: "height"
                      to: 0
                      easing.type: Easing.InOutQuad
                  }
                  PropertyAction {
                      target: swipeDelegate;
                      property: "ListView.delayRemove";
                      value: false
                  }
              }

              swipe.right: Label {
                  id: deleteLabel
                  text: qsTr("Delete")
                  color: "white"
                  verticalAlignment: Label.AlignVCenter
                  padding: 12
                  height: parent.height
                  anchors.right: parent.right

                  SwipeDelegate.onClicked: listView.model.remove(index)

                  background: Rectangle {
                      color: deleteLabel.SwipeDelegate.pressed ? Qt.darker("tomato", 1.1) : "tomato"
                  }
              }
          }
      }

SwipeDelegate inherits its API from ItemDelegate, which is inherited from AbstractButton. For instance, you can set text, and react to clicks using the AbstractButton API.

Information regarding the progress of a swipe, as well as the components that should be shown upon swiping, are both available through the swipe grouped property object. For example, `swipe.position` holds the position of the swipe within the range `-1.0` to `1.0`. The `swipe.left` property determines which item will be displayed when the control is swiped to the right, and vice versa for `swipe.right`. The positioning of these components is left to applications to decide. For example, without specifying any position for `swipe.left` or `swipe.right`, the following will occur:

If `swipe.left` and `swipe.right` are anchored to the left and right of the background item (respectively), they'll behave like this:

When using `swipe.left` and `swipe.right`, the control cannot be swiped past the left and right edges. To achieve this type of "wrapping" behavior, set `swipe.behind` instead. This will result in the same item being shown regardless of which direction the control is swiped. For example, in the image below, we set `swipe.behind` and then swipe the control repeatedly in both directions:

See also Customizing SwipeDelegate, Delegate Controls, and Swipe to Remove Example.

## Property Documentation

swipe group
swipe.position : real
swipe.complete : bool
swipe.enabled : bool
swipe.left : Component
swipe.behind : Component
swipe.right : Component
swipe.leftItem : Item
swipe.behindItem : Item
swipe.rightItem : Item
swipe.transition : Transition

Name | Description
--- | ---
position | This read-only property holds the position of the swipe relative to either side of the control. When this value reaches either `-1.0` (left side) or `1.0` (right side) and the mouse button is released, `complete` will be `true`.
complete | This read-only property holds whether the control is fully exposed after having been swiped to the left or right. When complete is `true`, any interactive items declared in `left`, `right`, or `behind` will receive mouse events.
enabled | This property determines whether or not the control can be swiped. This property was added in QtQuick.Controls 2.2.
left | This property holds the left delegate. The left delegate sits behind both contentItem and background. When the SwipeDelegate is swiped to the right, this item will be gradually revealed. Both interactive and non-interactive items can be used here. Normal event handling rules apply; if an interactive control like Button is used, interaction signals of SwipeDelegate such as clicked() will not get emitted if the button is clicked.
behind | This property holds the delegate that is shown when the SwipeDelegate is swiped to both the left and right. As with the `left` and `right` delegates, it sits behind both contentItem and background. However, a SwipeDelegate whose `behind` has been set can be continuously swiped from either side, and will always show the same item. Both interactive and non-interactive items can be used here. Normal event handling rules apply; if an interactive control like Button is used, interaction signals of SwipeDelegate such as clicked() will not get emitted if the button is clicked.
right | This property holds the right delegate. The right delegate sits behind both contentItem and background. When the SwipeDelegate is swiped to the left, this item will be gradually revealed. Both interactive and non-interactive items can be used here. Normal event handling rules apply; if an interactive control like Button is used, interaction signals of SwipeDelegate such as clicked() will not get emitted if the button is clicked.
leftItem | This read-only property holds the item instantiated from the `left` component. If `left` has not been set, or the position hasn't changed since creation of the SwipeDelegate, this property will be `null`.
behindItem | This read-only property holds the item instantiated from the `behind` component. If `behind` has not been set, or the position hasn't changed since creation of the SwipeDelegate, this property will be `null`.
rightItem | This read-only property holds the item instantiated from the `right` component. If `right` has not been set, or the position hasn't changed since creation of the SwipeDelegate, this property will be `null`.
transition | This property holds the transition that is applied when a swipe is released, or swipe.open() or swipe.close() is called.
      SwipeDelegate {
          swipe.transition: Transition {
              SmoothedAnimation { velocity: 3; easing.type: Easing.InOutCubic }
          }
      }
This property was added in Qt Quick Controls 2.2.

See also contentItem, background, swipe.open(), and swipe.close().

## Attached Property Documentation

[read-only] SwipeDelegate.pressed : bool

This property can be attached to a non-interactive item declared in `swipe.left`, `swipe.right`, or `swipe.behind`, in order to detect if it is pressed. Items can only be pressed when `swipe.complete` is `true`.

For example:

      swipe.right: Label {
          anchors.right: parent.right
          height: parent.height
          text: "Action"
          color: "white"
          padding: 12
          background: Rectangle {
              color: SwipeDelegate.pressed ? Qt.darker("tomato", 1.1) : "tomato"
          }
      }

It is possible to have multiple items which individually receive mouse and touch events. For example, to have two actions in the `swipe.right` item, use the following code:

      swipe.right: Row {
          anchors.right: parent.right
          height: parent.height

          Label {
              id: moveLabel
              text: qsTr("Move")
              color: "white"
              verticalAlignment: Label.AlignVCenter
              padding: 12
              height: parent.height

              SwipeDelegate.onClicked: console.log("Moving...")

              background: Rectangle {
                  color: moveLabel.SwipeDelegate.pressed ? Qt.darker("#ffbf47", 1.1) : "#ffbf47"
              }
          }
          Label {
              id: deleteLabel
              text: qsTr("Delete")
              color: "white"
              verticalAlignment: Label.AlignVCenter
              padding: 12
              height: parent.height

              SwipeDelegate.onClicked: console.log("Deleting...")

              background: Rectangle {
                  color: deleteLabel.SwipeDelegate.pressed ? Qt.darker("tomato", 1.1) : "tomato"
              }
          }
      }

Note how the `color` assignment in each background item qualifies the attached property with the `id` of the label. This is important; using the attached properties on an item causes that item to accept events. Suppose we had left out the `id` in the previous example:

      color: SwipeDelegate.pressed ? Qt.darker("tomato", 1.1) : "tomato"

The Rectangle background item is a child of the label, so it naturally receives events before it. In practice, this means that the background color will change, but the `onClicked` handler in the label will never get called.

For interactive controls (such as Button) declared in these items, use their respective `pressed` property instead.

For presses on the SwipeDelegate itself, use its pressed property.

This QML property was introduced in QtQuick.Controls 2.1 (Qt 5.8).

See also clicked().

## Signal Documentation

void swipe.closed()

This signal is emitted when the delegate has been swiped to closed and the transition has finished.

It is useful for performing some action upon cancellation of a swipe. For example, it can be used to cancel the removal of the delegate from the list that it is in.

This QML signal was introduced in QtQuick.Controls 2.2 (Qt 5.9).

See also swipe and swipe.opened().

void swipe.completed()

This signal is emitted when `swipe.complete` becomes `true`.

It is useful for performing some action upon completion of a swipe. For example, it can be used to remove the delegate from the list that it is in.

This QML signal was introduced in QtQuick.Controls 2.1 (Qt 5.8).

See also swipe.

void swipe.opened()

This signal is emitted when the delegate has been swiped open and the transition has finished.

It is useful for performing some action upon completion of a swipe. For example, it can be used to remove the delegate from the list that it is in.

This QML signal was introduced in QtQuick.Controls 2.2 (Qt 5.9).

See also swipe and swipe.closed().

## Attached Signal Documentation

void clicked()

This signal can be attached to a non-interactive item declared in `swipe.left`, `swipe.right`, or `swipe.behind`, in order to react to clicks. Items can only be clicked when `swipe.complete` is `true`.

For interactive controls (such as Button) declared in these items, use their respective `clicked()` signal instead.

To respond to clicks on the SwipeDelegate itself, use its clicked() signal.

Note: See the documentation for pressed for information on how to use the event-related properties correctly.

This QML signal was introduced in QtQuick.Controls 2.1 (Qt 5.8).

See also pressed.

## Method Documentation

void swipe.close()

This method sets the `position` of the swipe to `0`. Any animations defined for the x position of contentItem and background will be triggered.

This QML method was introduced in QtQuick.Controls 2.1 (Qt 5.8).

See also swipe and swipe.open().

void swipe.open(enumeration side)

This method sets the `position` of the swipe so that it opens from the specified side.

Available values:

Constant | Description
--- | ---
`SwipeDelegate.Left` | The `position` is set to `1`, which makes the swipe open from the left. Either `swipe.left` or `swipe.behind` must have been specified; otherwise the call is ignored.
`SwipeDelegate.Right` | The `position` is set to `-1`, which makes the swipe open from the right. Either `swipe.right` or `swipe.behind` must have been specified; otherwise the call is ignored.

Any animations defined for the x position of contentItem and background will be triggered.

This QML method was introduced in QtQuick.Controls 2.2 (Qt 5.9).

See also swipe and swipe.close().