Тип 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 : Путь
• 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.

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

Например, если определена простая модель списка в файле 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
            Image {
                anchors.horizontalCenter: nameText.horizontalCenter
                width: 64; height: 64
                source: icon
            }
            Text {
                id: nameText
                text: name
                font.pointSize: 16
                color: wrapper.PathView.isCurrentItem ? "red" : "black"
            }
        }
    }

    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
            Image {
                anchors.horizontalCenter: nameText.horizontalCenter
                width: 64; height: 64
                source: icon
            }
            Text {
                id: nameText
                text: name
                font.pointSize: 16
                color: wrapper.PathView.isCurrentItem ? "red" : "black"
            }
        }
    }

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

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

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

cacheItemCount : int

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

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

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

Примечание: Установка этого свойства не является заменой для создания эффективных делегатов. Оно может улучшить плавность прокрутки за счет дополнительного использования памяти. Чем меньше объектов и связей в делегате, тем быстрее представление может прокручиваться. Важно понимать, что установка cacheItemCount лишь отсрочит проблемы, вызванные медленной загрузкой делегатов, это не решение для такой ситуации.

См. также pathItemCount.

count : int

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

currentIndex : int

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

currentItem : Элемент

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

delegate : Компонент

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

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

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

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

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

dragMargin : real

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

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

dragging : bool

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

flickDeceleration : real

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

По умолчанию значение равно 100.

flicking : bool

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

highlight : Component

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

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

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

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

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

highlightItem : Item

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

См. также highlight.

highlightMoveDuration : int

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

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

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

highlightRangeMode : enumeration

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

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

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

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

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

Примечание: Для корректного диапазона необходимо, чтобы preferredHighlightEnd было больше или равно preferredHighlightBegin.

interactive : bool

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

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

maximumFlickVelocity : real

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

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

model : model

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

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

Примечание: изменение модели сбросит смещение и currentIndex до 0.

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

movementDirection : enumeration

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

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

Примечание: это свойство не влияет на перемещение incrementCurrentIndex() и decrementCurrentIndex().

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

moving : bool

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

offset : real

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

path : Path

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

pathItemCount : int

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

Установка pathItemCount в undefined покажет все элементы на пути.

preferredHighlightBegin : real

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

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

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

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

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

Примечание: Для корректного диапазона необходимо, чтобы preferredHighlightEnd было больше или равно preferredHighlightBegin.

preferredHighlightEnd : real

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

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

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

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

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

Примечание: Для корректного диапазона необходимо, чтобы preferredHighlightEnd было больше или равно preferredHighlightBegin.

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

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

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

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

См. также highlightRangeMode.

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

PathView.isCurrentItem : bool

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

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

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

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

PathView.onPath : bool

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

Если свойство 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(вещественное x, вещественное y)

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

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

Элемент itemAt(вещественное x, вещественное y)

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

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

positionViewAtIndex(int индекс, PositionMode режим)

Размещает просмотр таким образом, чтобы индекс находился в позиции, заданной режимом:

• PathView.Beginning - позиционирование элемента в начале пути.
• PathView.Center - позиционирование элемента в центре пути.
• PathView.End - позиционирование элемента в конце пути.
• PathView.Contain - обеспечение позиционирования элемента на пути.
• PathView.SnapPosition - позиционирование элемента в preferredHighlightBegin. Этот режим действителен только в том случае, если highlightRangeMode равен StrictlyEnforceRange или принудительное сцепление включено через snapMode.

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

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