# ListItemActions QML Type

Provides configuration for actions to be added to a ListItem. More...

Import Statement: | import Lomiri.Components 1.3
Since: | Lomiri.Components 1.2

- List of all members, including inherited members

## Properties

- actions : list<Action>
- delegate : Component

## Detailed Description

ListItem accepts actions that can be configured to appear when swiped to left or right. The API does not limit the number of actions to be assigned for leading or trailing actions, however the design constraints are allowing a maximum of 1 action on leading- and a maximum of 3 actions on trailing side of the ListItem.

The actions are Action instances or elements derived from Action. The default visualization of the actions can be overridden using the delegate property, and the default implementation uses the `name` property of the Action.

#### Using with ListViews

ListItemActions instances can be shared between ListItem instances within the same view. When shared, the memory footprint of the view will be lot smaller, as there will be no individual action container created for each list's actions. Having individual ListItemActions instances increases the memory footprint, and also has performance impact on kinetic scrolling.

The examples below illustrate the worst and best practice when used in a ListView. The worst case:

    import QtQuick 2.4
    import Lomiri.Components 1.2
    MainView {
        width: units.gu(40)
        height: units.gu(71)

        LomiriListView {
            anchors.fill: parent
            model: 10000
            delegate: ListItem {
                leadingActions: ListItemActions {
                    actions: [
                        Action {
                            iconName: "delete"
                        }
                    ]
                }
                trailingActions: ListItemActions {
                    actions: [
                        Action {
                            iconName: "toolkit_input-search"
                        },
                        Action {
                            iconName: "edit"
                        },
                        Action {
                            iconName: "copy"
                        }
                    ]
                }
            }
        }
    }

This example can be optimized by sharing the action arrays between the items:

    import QtQuick 2.4
    import Lomiri.Components 1.2
    MainView {
        width: units.gu(40)
        height: units.gu(71)

        ListItemActions {
            id: leading
            actions: Action {
                iconName: "delete"
            }
        }
        ListItemActions {
            id: trailing
            actions: [
                Action {
                    iconName: "toolkit_input-search"
                },
                Action {
                    iconName: "edit"
                },
                Action {
                    iconName: "copy"
                }
            ]
        }

        LomiriListView {
            anchors.fill: parent
            model: 10000
            delegate: ListItem {
                leadingActions: leading
                trailingActions: trailing
            }
        }
    }

#### Action parameter types

Actions handled by the ListItem are all triggered with the ListItem's index as parameter. This index can either be the model index when used with ListView, or the child index from the parentItem's childItems list. Actions can use this parameter to identify the instance of the ListItem on which it was executed, in which case ListItem will change the type from `Actions.None` to `Actions.Integer` when it is triggered.

## Property Documentation

actions : list<Action>

The property holds the actions to be displayed. It can hold instances cached or declared in place. An example of cached actions:

    ListItemActions {
        id: cachedActions
        actions: [
            copyAction, searchAction, cutAction
        ]
    }

delegate : Component

The property holds the custom delegate to visualize the actions listed in the ListItemActions. When set to null, the default delegate specified by the ListItemStyle will be used.

ListItemActions provides the `action` context property which contains the Action instance currently visualized. Using this property delegates can access the information to be visualized. The action is triggered by the panel item holding the visualized action, therefore only visualization is needed by the custom delegate. The other context property exposed to delegates is the `index`, which specifies the index of the action visualized.

Specifying a custom delegate will not override the triggering logic of the action, that will be still handled by the panel itself. However custom delegates may still need to distinguish the pressed/released state visually. This can be achieved using the `pressed` context property, which informs the delegate about the pressed state of the action.

The delegate height is set automatically by the panel item, only the width must be specified which will be clamped between height and the maximum width of the list item divided by the number of actions in the list.

    import QtQuick 2.4
    import Lomiri.Components 1.2

    MainView {
        width: units.gu(40)
        height: units.gu(71)

        LomiriListView {
            anchors.fill: parent
            model: 50
            delegate: ListItem {
                trailingActions: actionsList
            }
            ListItemActions {
                id: actionsList
                delegate: Column {
                    width: height + units.gu(2)
                    Icon {
                        name: action.iconName
                        width: units.gu(3)
                        height: width
                        color: pressed ? "blue" : "lightblue"
                        anchors.horizontalCenter: parent.horizontalCenter
                    }
                    Label {
                        text: action.text + "#" + index
                        width: parent.width
                        horizontalAlignment: Text.AlignHCenter
                    }
                }
                actions: Action {
                    iconName: "starred"
                    text: "Star"
                }
            }
        }
    }

Note: Putting a Rectangle in the delegate can be used to override the color of the panel. Also all ListItem attached properties can be used in the delegates.

Defaults to null.