API Documentation

Documentation for developing SailfishOS applications

RemorsePopup QML Type

Shows a pop-up 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

active : bool
leftMargin : real
rightMargin : real
text : string

Signals

onCanceled()
onTriggered()

Methods

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

Detailed Description

The recommended way to use RemorsePopup is through Remorse singleton API, and leave the life cycle of a remorse object for Silica to handle.

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

When the RemorsePopup is activated by the execute() function, it is displayed across the top of its parent, showing a countdown timer and allowing the user to cancel the action.

Here is an example employing a RemorsePopup to clear a list when the menu option is activated:

 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
             }
         }

         RemorsePopup { id: remorse }

         PullDownMenu {
             MenuItem {
                 text: "Clear"
                 onClicked: remorse.execute("Clearing", function() { listModel.clear() } )
             }
         }
     }
 }

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

See also Remorse::popupAction() and RemorseItem.

Property Documentation

[read-only] active : bool

Returns true if the remorse counter is running.

leftMargin : real

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

rightMargin : real

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

text : string

This property contains the description of the action to be potentially cancelled.

This property is typically provided by calling the execute() function.

Signal Documentation

onCanceled()

This signal handler is called if the user clicks on the RemorsePopup 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 RemorsePopup without performing the action.

execute(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 most common use case for remorse is item deletion. In deletion cases the textual description can be omitted altogether.

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

trigger()

Triggers the RemorsePopup action.