API Documentation

Documentation for developing SailfishOS applications

GridItem QML Type

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

Import Statement:	import Sailfish.Silica 1.0
Inherits:	BackgroundItem

List of all members, including inherited members

Properties

contentHeight : real
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 GridItem type provides a Sailfish-styled grid-entry item with touch interaction and optional features common to grid-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
 import Nemo.Thumbnailer 1.0

 SilicaGridView {
     id: view
     cellWidth: width/3
     cellHeight: cellWidth // square

     delegate: GridItem {

         function remove() {
             remorseDelete(function() { view.model.remove(index) })
         }

         menu: Component {
             ContextMenu {
                 MenuItem { text: "Edit" }
                 MenuItem {
                     text: "Remove"
                     onClicked: remove()
                 }
             }
         }

         Image {
             source: "image://nemoThumbnail/" + model.url
             fillMode: Image.PreserveAspectCrop
             anchors.fill: parent
             sourceSize { width: width; height: height }
             z: -1
         }
     }
 }

Note: The GridItem can be used within SilicaGridView or Grid positioner, but doesn't work with normal Qt Quick GridView. When used inside SilicaGridView the dimensions automatically follow the cellWidth and cellHeight defined by the view.

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

See also ListItem 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 follows GridView.cellHeight.

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

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.