API Documentation

Documentation for developing SailfishOS applications

Remorse QML Type

Shows prompts that brief allow destructive actions to be canceled More...

Import Statement: import Sailfish.Silica 1.0

List of all members, including inherited members

Methods

itemAction(Item parent, string text, object callback, int timeout)
popupAction(Page parent, string text, object callback, int timeout)

Detailed Description

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

There are four common ways to use remorses.

1. Deleting an item in a list or grid

When user selects to delete an item with context menu the app shows a remorse item in-place of the deleted item with description "Deleted". The recommended way to implement item deletion is through remorseDelete() function to leave the life cycle of a remorse object for Silica to handle.

 ListItem {
     id: listItem
     menu: Component {
         ContextMenu {
             MenuItem {
                 text: "Delete"
                 onClicked: listItem.remorseDelete(function() { model.remove(index) })
             }
         }
     }
 }

2. Deleting a full-screen item

When user chooses to delete a full-screen item (image, document, video, email, etc.) the app pops the full-screen viewer page, temporarily hides the respective item from the parent page list or grid by setting, and shows remorse popup. The item pending deletion can be hidden by setting ListItem's hidden property to true.

 Page {
     PullDownMenu {
         MenuItem {
             text: "Delete"
             onClicked: {
                 var remorse = Remorse.popupAction(root, "", function() {
                     pageStack.pop()

                 })
                 // Note when deletion of data from model often takes time. If you remove hiding too early
                 listPage.idPendingDeletion = Qt.binding(function() { return remorse && remorse.active ? model.id : -1 })
             }
         }
     }

     ListItem {
         hidden: model.id === listPage.idPendingDeletion
     }
 }

3. Clearing data

When user chooses to clear saved data (counters, caches, history, etc.) the page hides the cleared data and shows remorse popup with description "Cleared".

 Page {
     property Item remorse
     DetailItem {
         label: "Sent"
         value: Format.formatFileSize(remorse && remorse.active ? 0 : model.totalSent)
     }
     Button {
         text: "Clear"
         onClicked: remorse = Remorse.popupAction("Cleared data", function () { model.clearCounter() })
     }
 }

4. Deleting multiple items

When user selects multiple items to delete the app hides the respective list or grid items from the view and shows remorse popup. The items pending deletion can be hidden by setting ListItem's hidden property to true.

 Page {
     PullDownMenu {
         MenuItem {
             text: "Delete"
             onClicked: remorse = Remorse.popupAction(root, "", function() { model.delete(selectedItems) })
         }
     }

     ListItem {
         hidden: remorse && remorse.active && model.selected
     }
 }

When a remorse prompt is activated by the itemAction() function a RemorseItem is created which fills the dimensions specified Item showing a countdown timer and allowing the user to cancel the action.

A prompt activated by the popupAction() function creates a RemorsePopup which is displayed across the top of specified Page showing a countdown timer and allowing the user to cancel the action.

See also RemorseItem and RemorsePopup.

Method Documentation

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

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

The recommended way to use RemorseItem is through remorseDelete() function.

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".

Once the timeout has expired callback function will be called. 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.

Here is an example employing the Remorse singleton to remove a list item when a delegate is tapped:

 import QtQuick 2.2
 import Sailfish.Silica 1.0

 Page {
     id: 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
             }

             onClicked: {
                 var idx = index
                 Remorse.itemAction(myDelegate, "", function() { listModel.remove(idx) })
             }
         }
     }
 }

See also RemorseItem.

popupAction(Page parent, string text, object callback, int timeout)

Displays a RemorsePopup across the top of parent with the specified text.