Picker QML Type

Picker is a slot-machine style value selection component. More...

Import Statement: import Ubuntu.Components.Pickers 1.0
Inherits:

StyledItem

Properties

Methods

Detailed Description

The Picker lists the elements specified by the model using the delegate vertically using a slot-machine tumbler-like list. The selected item is always the one in the center of the component, and it is represented by the selectedIndex property.

The elements can be either in a circular list or in a normal list.

Delegates must be composed using PickerDelegate.

Example:

import QtQuick 2.4
import Ubuntu.Components 1.2
import Ubuntu.Components.Pickers 1.0

Picker {
    model: ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sept", "Oct", "Nov", "Dec"]
    delegate: PickerDelegate {
        Label {
            text: modelData
        }
    }
    selectedIndex: 5
    onSelectedIndexChanged: {
        print("selected month: " + selectedIndex);
    }
}

Note: the selectedIndex must be set explicitly to the desired index if the model is set, filled or changed after the component is complete. In the following example the selected item must be set after the model is set.

Picker {
    selectedIndex: 5 // this will be set to 0 at the model completion
    delegate: PickerDelegate {
        Label {
            text: modelData
        }
    }
    Component.onCompleted: {
        var stack = [];
        for (var i = 0; i < 10; i++) {
            stack.push("Line " + i);
        }
        model = stack;
        // selectedIndex must be set explicitly
        selectedIndex = 3;
    }
}

Known issues

Property Documentation

activeFocusOnPress : bool

The property specifies whether the StyledItem can gain focus on a mouse press/touch or not. When the value is true, the focus will be set on the component when the mouse is pressed over it or touched. However if one of the component's ancestor StyledItem or derived is having the property value false, the focus will not be gained automatically.

In the following example the TextField will stay focused when clicked on the red rectangle.

import QtQuick 2.4
import Ubuntu.Components 1.2

Column {
    width: units.gu(50)
    height: units.gu(100)

    StyledItem {
        objectName: "passiveScope"
        width: parent.width
        height: units.gu(30)
        Rectangle {
            anchors.fill: parent
            color: "red"
            StyledItem {
                objectName: "activeScope"
                activeFocusOnPress: true
                anchors.fill: parent
            }
        }
    }

    TextField {
        id: input
        text: "The input stays focus even if red box is clicked"
    }

    Component.onCompleted: input.forceActiveFocus()

    Connections {
        target: window
        onActiveFocusItemChanged: console.debug("focus on", window.activeFocusItem)
    }
}

The default value is false.

This QML property was introduced in Ubuntu.Components 1.1.


circular : bool

Property specifying whether the tumbler list is wrap-around (true), or normal (false). Default value is true.


delegate : Component

The delegate visualizing the model elements. Any kind of component can be used as delegate, however it is recommended to use PickerDelegate, which integrates selection functionality into the Picker.


live : bool

Defines whether the selectedIndex should be updated while the tumbler changes the selected item during draggingm or only when the tumbler's motion ends. The default behavior is non-live update.


model : var

Specifies the model listing the content of the picker.


read-onlymoving : bool

The property holds whether the picker's view is moving due to the user interaction either by dragging, flicking or due to the manual change of the selectedIndex property.


selectedIndex : int

The property holds the index of the selected item


style : Component

Component instantiated immediately and placed below everything else.


Method Documentation

positionViewAtIndex( index)

The function positions the picker's view to the given index without animating the view. The component must be ready when calling the function, e.g. to make sure the Picker shows up at the given index, do the following:

Picker {
    model: 120
    delegate: PickerDelegate {
        Label {
            anchors.fill: parent
            verticalCenter: Text.AlignVCenter
            text: modelData
        }
    }
    Component.onCompleted: positionViewAtIndex(10)
}