Тип 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 : модель
• 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
            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()
}

Сам PathView является областью фокуса (подробнее см. Фокус клавиатуры в 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 автоматически. Если представление не обрезается другим элементом или экраном, необходимо установить 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
            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 : перечисление

Эти свойства устанавливают предпочтительный диапазон выделения (текущего элемента) в пределах виджета. Предпочтительные значения должны находиться в диапазоне от 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 : перечисление

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

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

Это свойство QML было введено в 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(real x, real y)

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

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

Item itemAt(real x, real y)

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

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

positionViewAtIndex(int index, PositionMode mode)

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

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

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

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