API Documentation

Documentation for developing SailfishOS applications

RemorseItem QML Type

Shows an item that briefly allows a destructive action to be canceled More...

Import Statement:	import Sailfish.Silica 1.0
Inherits:	BackgroundItem

List of all members, including inherited members

Properties

horizontalAlignment : enumeration
leftMargin : real
pending : bool
rightMargin : real
wrapMode : enumeration

Signals

onCanceled()
onTriggered()

Methods

cancel()
execute(Item parent, string text, object callback, int timeout)
trigger()

Detailed Description

The recommended way to use RemorseItem is through remorseDelete() function or if no ListItem is available Remorse singleton API, and leave the life cycle of a remorse object for Silica to handle.

The RemorseItem type allows destructive actions to be delayed until after a remorse period has elapsed. If the RemorseItem control is tapped before this timeout expires, the action is canceled.

When the RemorseItem is activated by the execute() function, it fills the dimensions of the specified Item, showing a countdown timer and allowing the user to cancel the action.

Here is an example. Each delegate in this list has a RemorseItem. When a delegate is tapped, it activates the RemorseItem for its own removal:

 import QtQuick 2.2
 import Sailfish.Silica 1.0

 Page {
     SilicaListView {
         anchors.fill: parent
         model: ListModel {
             id: listModel
             Component.onCompleted: {
                 for (var i=0; i<10; i++) {
                     append({"name": "Item " + i})
                 }
             }
         }

         delegate: BackgroundItem {
             id: myDelegate
             width: ListView.view.width

             Label {
                 text: model.name
                 anchors.centerIn: parent
             }

             RemorseItem { id: remorse }

             function showRemorseItem() {
                 var idx = index
                 remorse.execute(myDelegate, "Deleted", function() { listModel.remove(idx) } )
             }

             onClicked: {
                 showRemorseItem()
             }
         }
     }
 }

RemorseItem is typically used when executing an action for a single UI entry in a list or view. To achieve a similar effect for an action that affects multiple items at the same time, use RemorsePopup.

See also Remorse::itemAction() and RemorsePopup.

Property Documentation

horizontalAlignment : enumeration

This property aligns horizontally all the texts in this RemorseItem.

By default this value is Text.AlignLeft.

leftMargin : real

The margins between the left and right edges of the remorse item and its contents. The default value is Theme.horizontalPageMargin.

pending : bool

This property is true if the RemorseItem is active within the remorse period.

rightMargin : real

The margins between the left and right edges of the remorse item and its contents. The default value is Theme.horizontalPageMargin.

wrapMode : enumeration

This property wraps the title text which is provided by the user via the execute() call. The wrapMode property is useful when the RemorseItem needs to fit into a smaller area. Setting this property to a value other than Text.NoWrap removes the fade effect.

By default this value is Text.NoWrap.

Signal Documentation

onCanceled()

This signal handler is called if the user clicks on the RemorseItem to cancel the action.

onTriggered()

This signal handler is called if the action has not been canceled within the remorse period.

Method Documentation

cancel()

Cancels the RemorseItem without performing the action.

execute(Item parent, string text, object callback, int timeout)

Displays the RemorseItem in place of the parent item with the specified text describing the action being performed. Textual description is optional, the most common use case for remorse is item deletion where text string can be left empty.

Once the timeout has expired callback will be called. If a callback is not supplied then the onTriggered handler may be used to perform the action. Note the callback execution happens in remorse component scope, and references to objects within the page or delegate context that requested the remorse may not be available.

timeout is optional. The default value of 4000ms will be used if it is not supplied.

The remorse text should contain a verb describing the action being performed. Previously the action was displayed in present tense, but now after Sailfish 3.2 past tense should be used instead to better indicate no additional step is needed from user unless they want to undo the action. For example a remorse that used to show "Clearing data" would now display "Cleared data".

Note that the RemorseItem will become a sibling to the target parent item to allow the fading out of the item. RemorseItem handles its own positioning, and won't work if parented inside a Qt Quick positioner like Column.

trigger()

Executes the configured action immediately, if it has not already been triggered or canceled.

This function can be called to invoke the delayed action immediately if a user action causes the remorse period to be cut short. Returns true if an action is triggered, otherwise false.