Тип QML PathView

Выстраивает элементы, предоставляемые моделью, по пути. Подробнее...

• Список всех членов, включая наследуемые

Свойства

• cacheItemCount : int
• count : int
• currentIndex : int
• currentItem : Элемент
• delegate : Компонент
• dragMargin : real
• dragging : bool
• flickDeceleration : real
• flicking : bool
• highlight : Компонент
• highlightItem : Элемент
• highlightMoveDuration : int
• highlightRangeMode : перечисление
• interactive : bool
• maximumFlickVelocity : real
• model : модель
• movementDirection : перечисление
• moving : bool
• offset : real
• path : Path
• pathItemCount : int
• preferredHighlightBegin : real
• preferredHighlightEnd : real
• snapMode : перечисление

Присоединённые свойства

• isCurrentItem : bool
• onPath : bool
• view : PathView

Сигналы

• dragEnded()
• dragStarted()
• flickEnded()
• flickStarted()
• movementEnded()
• movementStarted()

Методы

• decrementCurrentIndex()
• incrementCurrentIndex()
• int indexAt(real x, real y)
• Элемент itemAt(real x, real y)
• positionViewAtIndex(int index, PositionMode mode)

Подробное описание

PathView отображает данные из моделей, созданных из встроенных типов QML, таких как ListModel и XmlListModel, или пользовательских классов моделей, определённых в C++, которые наследуют от QAbstractListModel.

Просмотр имеет model, который определяет отображаемые данные, и delegate, который определяет, как должны отображаться данные. delegate экземплируется для каждого элемента на path. Элементы могут быть пролистываемы по пути.

Например, если в файле ContactModel.qml определена простая модель списка, подобно этому:

import QtQuick 2.0

ListModel {
    ListElement {
        name: "Bill Jones"
        icon: "pics/qtlogo.png"
    }
    ListElement {
        name: "Jane Doe"
        icon: "pics/qtlogo.png"
    }
    ListElement {
        name: "John Smith"
        icon: "pics/qtlogo.png"
    }
}

Эти данные могут быть представлены как PathView, как показано ниже:

import QtQuick 2.0

Rectangle {
    width: 240; height: 200

    Component {
        id: delegate
        Column {
            id: wrapper
            opacity: PathView.isCurrentItem ? 1 : 0.5
            Image {
                anchors.horizontalCenter: nameText.horizontalCenter
                width: 64; height: 64
                source: icon
            }
            Text {
                id: nameText
                text: name
                font.pointSize: 16
            }
        }
    }

    PathView {
        anchors.fill: parent
        model: ContactModel {}
        delegate: delegate
        path: Path {
            startX: 120; startY: 100
            PathQuad { x: 120; y: 25; controlX: 260; controlY: 75 }
            PathQuad { x: 120; y: 100; controlX: -20; controlY: 75 }
        }
    }
}

(В приведённом выше примере используется PathAttribute для масштабирования и изменения непрозрачности элементов по мере их вращения. Этот дополнительный код можно увидеть в документации PathAttribute.)

PathView не обрабатывает навигацию по клавиатуре автоматически. Это связано с тем, что используемые клавиши для навигации зависят от формы пути. Навигацию можно добавить довольно просто, установив focus в true и вызвав decrementCurrentIndex() или incrementCurrentIndex(), например, для навигации с помощью клавиш влево и вправо:

PathView {
    // ...
    focus: true
    Keys.onLeftPressed: decrementCurrentIndex()
    Keys.onRightPressed: incrementCurrentIndex()
}

Сам просмотр пути является областью фокусировки (подробнее см. Фокус клавиатуры в Qt Quick).

Делегаты создаются по мере необходимости и могут быть уничтожены в любое время. Состояние никогда не должно храниться в делегате.

PathView присоединяет ряд свойств к корневому элементу делегата, например, PathView.isCurrentItem. В следующем примере корневой элемент делегата может получить доступ к этому присоединённому свойству непосредственно как PathView.isCurrentItem, в то время как объект nameText должен обратиться к этому свойству как wrapper.PathView.isCurrentItem.

    Component {
        id: delegate
        Column {
            id: wrapper
            opacity: PathView.isCurrentItem ? 1 : 0.5
            Image {
                anchors.horizontalCenter: nameText.horizontalCenter
                width: 64; height: 64
                source: icon
            }
            Text {
                id: nameText
                text: name
                font.pointSize: 16
            }
        }
    }

Примечание, что представления не включают clip автоматически. Если представление не ограничено другим элементом или экраном, необходимо установить clip: true, чтобы иметь возможность красиво обрезать элементы, которые находятся вне области видимости.

См. также Path, QML Модели данных, ListView, GridView и Примеры Qt Quick - Представления.

Документация по свойствам

Эти свойства устанавливают предпочтительный диапазон выделения (текущего элемента) в представлении. Предпочтительные значения должны находиться в диапазоне от 0 до 1.

Допустимые значения для highlightRangeMode:

• PathView.NoHighlightRange - диапазон не применяется, и выделение будет свободно перемещаться в пределах представления.
• PathView.ApplyRange - представление попытается сохранить выделение в пределах диапазона, однако выделение может выйти за пределы диапазона в конце пути или из-за взаимодействия с мышью.
• PathView.StrictlyEnforceRange - выделение никогда не выйдет за пределы диапазона. Это означает, что текущий элемент изменится, если действие с клавиатуры или мыши приведет к перемещению выделения за пределы диапазона.

Значение по умолчанию - PathView.StrictlyEnforceRange.

Определение диапазона выделения — это правильный способ повлиять на то, где окажется текущий элемент при перемещении представления. Например, если вы хотите, чтобы выбранный элемент был посередине пути, установите диапазон выделения в 0,5; 0,5 и highlightRangeMode в PathView.StrictlyEnforceRange. Затем при прокрутке пути текущим выбранным элементом будет элемент в этой позиции. Это также относится к изменению текущего выбранного элемента — представление будет прокручено до предпочтительного диапазона выделения. Более того, поведение текущего индекса элемента будет происходить независимо от наличия выделения.

cacheItemCount : int

Это свойство хранит максимальное количество элементов, которые будут кэшированы вне пути.

Например, PathView с моделью, содержащей 20 элементов, pathItemCount 10 и cacheItemCount 4 создаст до 14 элементов, из которых 10 будут видимыми на пути, а 4 — невидимыми кэшированными элементами.

Кэшированные делегаты создаются асинхронно, позволяя создание происходить в течение нескольких кадров и уменьшая вероятность пропуска кадров.

См. также pathItemCount.

count : int

Это свойство хранит количество элементов в модели.

currentIndex : int

Это свойство хранит индекс текущего элемента.

currentItem : Элемент

Это свойство хранит текущий элемент в представлении.

delegate : Компонент

Делегат предоставляет шаблон, определяющий каждый элемент, созданный просмотром. Индекс доступен в виде свойства index. Свойства модели также доступны в зависимости от типа модели данных.

Количество объектов и привязок в делегате напрямую влияет на производительность перелистывания просмотра, когда задан pathItemCount. Если это возможно, поместите функциональность, которая не требуется для нормального отображения делегата, в Loader, который может загружать дополнительные компоненты по мере необходимости.

Обратите внимание, что PathView будет размещать элементы на основе размера корневого элемента в делегате.

Вот пример делегата:

    Component {
        id: delegate
        Column {
            id: wrapper
            opacity: PathView.isCurrentItem ? 1 : 0.5
            Image {
                anchors.horizontalCenter: nameText.horizontalCenter
                width: 64; height: 64
                source: icon
            }
            Text {
                id: nameText
                text: name
                font.pointSize: 16
            }
        }
    }

dragMargin : вещественный

Это свойство содержит максимальное расстояние от пути, которое инициирует перетаскивание мышью.

По умолчанию путь можно перетащить только щелкнув по элементу. Если dragMargin больше нуля, перетаскивание можно инициировать, щелкнув в пределах dragMargin пикселей от пути.

dragging : логическое

Это свойство содержит значение, указывающее, перемещается ли просмотр в настоящее время из-за перетаскивания пользователем.

flickDeceleration : вещественный

Это свойство содержит скорость замедления перелистывания.

Значение по умолчанию равно 100.

flicking : логическое

Это свойство содержит значение, указывающее, перемещается ли просмотр в настоящее время из-за перелистывания пользователем.

highlight : Компонент

Это свойство содержит компонент, который следует использовать в качестве выделения.

Экземпляр компонента выделения будет создан для каждого просмотра. Геометрия результирующего экземпляра компонента будет управляться просмотром, чтобы оставаться с текущим элементом.

Ниже приведен пример, демонстрирующий, как создать простое выделение. Обратите внимание на использование присоединённого свойства PathView.onPath, чтобы убедиться, что выделение скрыто, когда перелистывание удаляет его с пути.

Component {
    Rectangle {
        visible: PathView.onPath
        // ...
    }
}

См. также highlightItem и highlightRangeMode.

highlightItem : Элемент

highlightItem содержит элемент выделения, который был создан из компонента highlight.

См. также highlight.

highlightMoveDuration : целое

Это свойство содержит продолжительность анимации перемещения делегата выделения.

Если highlightRangeMode равен StrictlyEnforceRange, то это свойство определяет скорость перемещения элементов по пути.

Значение по умолчанию для продолжительности составляет 300 мс.

interactive : логическое

Пользователь не может перетащить или перелистнуть PathView, который не интерактивный.

Это свойство полезно для временного отключения перелистывания. Это позволяет осуществлять специальные взаимодействия с элементами PathView.

maximumFlickVelocity : вещественный

Это свойство содержит приблизительную максимальную скорость, с которой пользователь может перелистнуть просмотр в пикселях/секунду.

Значение по умолчанию зависит от платформы.

model : модель

Это свойство содержит модель, предоставляющую данные для просмотра.

Модель предоставляет набор данных, используемых для создания элементов для просмотра. Для больших или динамических наборов данных модель обычно предоставляется объектом модели C++. Модели также могут быть созданы непосредственно в QML, используя тип ListModel.

См. также модели данных.

[с 5.7] movementDirection : перечисление

Это свойство определяет направление, в котором элементы перемещаются при установке текущего индекса. Возможные значения:

• PathView.Shortest (по умолчанию) - элементы перемещаются в направлении, требующем наименьшего перемещения, что может быть как Negative или Positive.
• PathView.Negative - элементы перемещаются назад к месту назначения.
• PathView.Positive - элементы перемещаются вперед к месту назначения.

Например, предположим, что в модели есть 5 элементов, и currentIndex равен 0. Если currentIndex установлен на 2,

• направление перемещения Positive приведет к следующему порядку: 0, 1, 2
• направление перемещения Negative приведет к следующему порядку: 0, 5, 4, 3, 2
• направление перемещения Shortest приведет к тому же порядку, что и Positive .

Это свойство было добавлено в Qt 5.7.

moving : логическое

Это свойство содержит значение, указывающее, перемещается ли просмотр в настоящее время из-за перетаскивания или перелистывания пользователем.

offset : вещественный

Смещение определяет, насколько далеко по пути элементы находятся от своих начальных позиций. Это вещественное число, которое изменяется от 0 до количества элементов в модели.

path : Путь

Это свойство содержит путь, используемый для расположения элементов. Дополнительную информацию можно найти в документации по Пути.

pathItemCount : целое

Это свойство содержит количество элементов, видимых на пути в любой момент времени.

Установление pathItemCount в undefined отобразит все элементы на пути.

snapMode : перечисление

Это свойство определяет, как элементы будут устанавливаться после перетаскивания или перелистывания. Возможные значения:

• PathView.NoSnap (по умолчанию) - элементы останавливаются где угодно вдоль пути.
• PathView.SnapToItem - элементы устанавливаются, когда элемент выровнен с preferredHighlightBegin.
• PathView.SnapOneItem - элементы устанавливаются не дальше чем на один элемент от элемента, ближайшего к preferredHighlightBegin в момент отпускания нажатия. Этот режим особенно полезен для перемещения по одной странице за раз.

snapMode не влияет на currentIndex. Чтобы обновить currentIndex по мере перемещения просмотра, установите highlightRangeMode в PathView.StrictlyEnforceRange (значение по умолчанию для PathView).

См. также highlightRangeMode.

Документация по присоединенным свойствам

PathView.isCurrentItem : логическое

Это присоединенное свойство равно true, если этот делегат является текущим элементом; в противном случае false.

Присоединяется к каждому экземпляру делегата.

Это свойство может использоваться для изменения внешнего вида текущего элемента.

    Component {
        id: delegate
        Column {
            id: wrapper
            opacity: PathView.isCurrentItem ? 1 : 0.5
            Image {
                anchors.horizontalCenter: nameText.horizontalCenter
                width: 64; height: 64
                source: icon
            }
            Text {
                id: nameText
                text: name
                font.pointSize: 16
            }
        }
    }

PathView.onPath : логическое

Это присоединенное свойство содержит значение, указывающее, находится ли элемент в данный момент на пути.

Если был установлен pathItemCount, возможно, некоторые элементы будут созданы, но не считаться в настоящий момент на пути. Обычно эти элементы будут сделаны невидимыми, например:

Component {
    Rectangle {
        visible: PathView.onPath
        // ...
    }
}

Присоединяется к каждому экземпляру делегата.

PathView.view : PathView

Это присоединенное свойство содержит просмотр, управляющий данным экземпляром делегата.

Присоединяется к каждому экземпляру делегата.

Документация по сигналам

dragEnded()

Этот сигнал генерируется, когда пользователь прекращает перетаскивание просмотра.

Если скорость перетаскивания достаточна в момент отпускания сенсорной/мышиной кнопки, начнется перелистывание.

Примечание: Соответствующий обработчик — onDragEnded.

dragStarted()

Этот сигнал генерируется, когда просмотр начинает перетаскиваться из-за взаимодействия пользователя.

Примечание: Соответствующий обработчик — onDragStarted.

flickEnded()

Этот сигнал генерируется, когда просмотр прекращает движение из-за перелистывания.

Примечание: Соответствующий обработчик — onFlickEnded.

flickStarted()

Этот сигнал излучается, когда представление прокручивается. Прокрутка начинается с точки, в которой мышь или сенсорный экран отпускаются, при этом движение продолжается.

Примечание: Соответствующий обработчик — onFlickStarted.

movementEnded()

Этот сигнал излучается, когда движение представления прекращается из-за взаимодействия пользователя. Если была инициирована прокрутка, этот сигнал будет излучен, как только прокрутка остановится. Если прокрутка не была инициирована, этот сигнал будет излучен, когда пользователь перестанет перемещать представление — т. е. при отпускании мыши или сенсорного экрана.

Примечание: Соответствующий обработчик — onMovementEnded.

movementStarted()

Этот сигнал излучается, когда движение представления начинается из-за взаимодействия пользователя.

Примечание: Соответствующий обработчик — onMovementStarted.

Документация методов

decrementCurrentIndex()

Уменьшает текущий индекс.

Примечание: методы следует вызывать только после завершения компонента.

incrementCurrentIndex()

Увеличивает текущий индекс.

Примечание: методы следует вызывать только после завершения компонента.

int indexAt(real x, real y)

Возвращает индекс элемента, содержащего точку x, y в координатах содержимого. Если в указанной точке нет элемента, возвращается -1.

Примечание: методы следует вызывать только после завершения компонента.

Item itemAt(real x, real y)

Возвращает элемент, содержащий точку x, y в координатах содержимого. Если в указанной точке нет элемента, возвращается null.

Примечание: методы следует вызывать только после завершения компонента.

positionViewAtIndex(int index, PositionMode mode)

Позиционирует представление так, чтобы элемент с индексом index находился в позиции, заданной mode:

• PathView.Начало — позиционирует элемент в начале пути.
• PathView.Центр — позиционирует элемент в центре пути.
• PathView.Конец — позиционирует элемент в конце пути.
• PathView.Содержит — гарантирует позиционирование элемента на пути.
• PathView.ТочкаПривязки — позиционирует элемент в точке preferredHighlightBegin. Этот режим допустим только если highlightRangeMode равен StrictlyEnforceRange или привязка включена через snapMode.

Примечание: методы следует вызывать только после завершения компонента. Для позиционирования представления при запуске следует вызвать этот метод в Component.onCompleted. Например, для позиционирования представления в конце:

Component.onCompleted: positionViewAtIndex(count - 1, PathView.End)