API Documentation

Documentation for developing SailfishOS applications

ListItem QML Type

A simple Sailfish-styled item for building touch-interactive list items More...

Import Statement:	import Sailfish.Silica 1.0
Inherits:	BackgroundItem

Properties

contentHeight : real
hidden : bool
highlighted : bool
menu : var
menuOpen : bool
openMenuOnPressAndHold : bool

Methods

animateRemoval(Item delegate)
closeMenu()
openMenu(object properties)
remorseAction(string text, object action, int timeout)
remorseDelete(object action, int timeout)

Detailed Description

The ListItem type provides a Sailfish-styled list-entry item with touch interaction and optional features common to list-type items. It can:

show a context menu (specified with the menu property) when the press-and-hold gesture is triggered
replace itself with a RemorseItem when remorseAction() is called (this is commonly used to show a remorse timer when the user triggers the item's removal via a context menu option)
run a remove-type animation on itself when animateRemoval() is called

An example:

 import QtQuick 2.2
 import Sailfish.Silica 1.0

 ListView {
     id: view

     delegate: ListItem {
         id: listItem
         menu: contextMenu
         contentHeight: Theme.itemSizeMedium // two line delegate
         ListView.onRemove: animateRemoval(listItem)

         function remove() {
             remorseAction("Deleting", function() { view.model.remove(index) })
         }

         Label {
             id: label
             text: "Item: " + index
         }
         Label {
             anchors.top: label.bottom
             text: "Bottom line of text"
             font.pixelSize: Theme.fontSizeSmall
         }

         Component {
             id: contextMenu
             ContextMenu {
                 MenuItem {
                     text: "Remove"
                     onClicked: remove()
                 }
             }
         }
     }

 }

Note: The ListItem height should not be modified, as the height automatically expands when the menu is opened. Set the contentHeight property instead.

See also GridItem and BackgroundItem.

Property Documentation

contentHeight : real

Sets the normal height of the delegate. The delegate height may expand when a ContextMenu is open, but the content height will remain contentHeight.

The default value is Theme.itemSizeSmall.

hidden : bool

This property can be set to true to momentarily hide the item when it has been chosen to be deleted elsewhere, for example is part of multiple items selected for deletion. See Remorse documentation for more information.

highlighted : bool

This is true if down is true or the menu is open and thus the contents should be shown in a highlighted manner.

(See the Theme documentation for guidelines on styling interactive controls in Sailfish OS.)

See also BackgroundItem::highlighted.

This property holds the ContextMenu to open when "press and hold" is activated.

This property may be either a Component with a top-level ContextMenu, or a pre-created ContextMenu object. If a Component is provided the ContextMenu will be created and destroyed as needed. In most cases you should use the Component approach to avoid loading menu unnecessarily.

[read-only] menuOpen : bool

True if the menu is open, otherwise false.

openMenuOnPressAndHold : bool

True if the menu should be opened when "press and hold" is activated, otherwise false.

The default value is true.

Method Documentation

animateRemoval(Item delegate)

Creates and starts a RemoveAnimation. If the ListItem is not the top-level Item of the delegate, the delegate must be set to the top level Item of the delegate.

Using animateRemoval() this is slightly faster than creating the RemoveAnimation during delegate creation.

See also RemoveAnimation.

closeMenu()

Hides the menu if it is currently shown.

openMenu(object properties)

Displays the supplied menu.

The optional properties parameter specifies a map of properties to be set on the menu.

remorseAction(string text, object action, int timeout)

Creates a RemorseItem with text and sets the callback to action. timeout is optional and will default to 4 seconds if not provided.

The most common use case for a remorse is item deletion, in which case you can omit text parameter and use remorseDelete() function instead. In deletion cases the textual description is 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".

From technical behavior point of view remorse items function like before.

Returns the RemorseItem instance created. This instance will be destroyed automatically after the action is either triggered or canceled.

remorseDelete(object action, int timeout)

Creates a RemorseItem and sets the callback to action. timeout is optional and will default to 4 seconds if not provided.