Ubuntu.Components.ViewItems

A set of properties attached to the ListItem's parent item or ListView. More...

Import Statement: import Ubuntu.Components 1.3
Since: Ubuntu.Components 1.2

Attached Properties

Attached Signals

Detailed Description

These properties are automatically attached to the parent item of the ListItem, or to ListView, when the component is used as delegate.

Attached Property Documentation

ViewItems.dragMode : bool

The property drives the dragging mode of the ListItems within a ListView. It has no effect on any other parent of the ListItem.

When set, ListItem content will be disabled and a panel will be shown enabling the dragging mode. The items can be dragged by dragging this handler only. The feature can be activated same time with ListItem::selectMode.

The panel is configured by the style.

See also ListItemStyle and dragUpdated.


ViewItems.expandedIndices : list<int>

The property contains the indexes of the ListItems marked as expanded. The indexes are model indexes when used in ListView, and child indexes in other components. The property being writable, initial expansion configuration can be provided for a view, and provides ability to save the expansion state.

Note: If the ViewItems::expansionFlags is having ViewItems.Exclusive flags set, only the last item from the list will be considered and set as expanded.

This QML property was introduced in Ubuntu.Components 1.3.


ViewItems.expansionFlags : ExpansionFlags

Flags driving the expansion behavior.

Flagdescription
ViewItems.ExclusiveWhen set, only one ListItem can be expanded at a time. Set by default.
ViewItems.UnlockExpandedWhen set, the ListItem's leading/trailing actions can be swiped in.
ViewItems.CollapseOnOutsidePressWhen set, the active expaned ListItem collapses automatically when clicked outside of its area. The flag also turns ViewItems.Exclusive flag on.

This QML property was introduced in Ubuntu.Components 1.3.


ViewItems.selectMode : bool

The property drives whether list items are selectable or not.

When set, the ListItems of the Item the property is attached to will enter into selection state. ListItems provide a visual clue which can be used to toggle the selection state of each, which in order will be reflected in the ViewItems.selectedIndices list.


ViewItems.selectedIndices : list<int>

The property contains the indexes of the ListItems marked as selected. The indexes are model indexes when used in ListView, and child indexes in other components. The property being writable, initial selection configuration can be provided for a view, and provides ability to save the selection state.


Attached Signal Documentation

dragUpdated(ListItemDrag event)

The signal is emitted whenever a dragging related event occurrs. The event.status specifies the dragging event type. Depending on the type, the ListItemDrag event properties will have the following meaning:

statusfromtominimumIndexmaximumIndex
Startedthe index of the item to be dragged-1default (-1), can be changed to restrict movesdefault (-1), can be changed to restrict moves
Movingsource index from where the item dragged fromdestination index where the item can be dragged tothe same value set at Started, can be changedthe same value set at Started, can be changed
Droppedsource index from where the item dragged fromdestination index where the item can be dragged tothe value set at Started/Moving, changes are omittedthe value set at Started/Moving, changes are omitted

Implementations must move the model data in order to re-order the ListView content. If the move is not acceptable, it must be cancelled by setting event.accept to false, in which case the dragged index (from) will not be updated and next time the signal is emitted will be the same.

An example implementation of a live dragging with restrictions:

import QtQuick 2.4
import Ubuntu.Components 1.2
ListView {
width: units.gu(40)
height: units.gu(40)
model: ListModel {
// initiate with random data
}
delegate: ListItem {
// content
}
ViewItems.dragMode: true
ViewItems.onDragUpdated: {
if (event.status == ListViewDrag.Started) {
if (event.from < 5) {
// deny dragging on the first 5 element
event.accept = false;
} else if (event.from >= 5 && event.from <= 10 &&
event.to >= 5 && event.to <= 10) {
// specify the interval
event.minimumIndex = 5;
event.maximumIndex = 10;
} else if (event.from > 10) {
// prevent dragging to the first 11 items area
event.minimumIndex = 11;
}
} else {
model.move(event.from, event.to, 1);
}
}
}

A drag'n'drop implementation might be required when model changes are too expensive, and continuously updating while dragging would cause lot of traffic. The following example illustrates how to implement such a scenario:

import QtQuick 2.4
import Ubuntu.Components 1.2
ListView {
width: units.gu(40)
height: units.gu(40)
model: ListModel {
// initiate with random data
}
delegate: ListItem {
// content
}
ViewItems.dragMode: true
ViewItems.onDragUpdated: {
if (event.direction == ListItemDrag.Dropped) {
// this is the last event, so drop the item
model.move(event.from, event.to, 1);
} else if (event.direction != ListItemDrag.Started) {
// do not accept the moving events, so drag.from will
// always contain the original drag index
event.accept = false;
}
}
}

Note: Do not forget to set event.accept to false in dragUpdated in case the drag event handling is not accepted, otherwise the system will not know whether the move has been performed or not, and selected indexes will not be synchronized properly.