Тип QML PathView

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

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

Свойства

• cacheItemCount : int
• count : int
• currentIndex : int
• currentItem : Item
• delegate : Component
• dragMargin : real
• dragging : bool
• flickDeceleration : real
• flicking : bool
• highlight : Component
• highlightItem : Item
• highlightMoveDuration : int
• highlightRangeMode : перечисление
• interactive : bool
• maximumFlickVelocity : real
• model : 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)
• Item 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: true, чтобы корректно обрезать элементы, выходящие за пределы видимости.

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

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

cacheItemCount : int

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

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

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

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

См. также pathItemCount.

count : int

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

currentIndex : int

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

currentItem : Item

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

delegate : Component

Делегат предоставляет шаблон, определяющий каждый элемент, создаваемый представлением. Индекс доступен как доступное 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 : 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
            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 : 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)