Тип 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(x, real y)
• Item itemAt(x, real y)
• positionViewAtIndex(index, PositionMode mode)

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

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

Вью содержит model, который определяет данные для отображения, и delegate, который определяет способ отображения данных. delegate создаётся для каждого элемента на пути. Элементы могут быть перетащены для перемещения по пути.

Например, если в файле 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()
}

Сам PathView является областью фокуса (см. Фокус клавиатуры в 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 - Представления.

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

preferredHighlightBegin : real

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

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

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

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

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

Примечание: Действительный диапазон требует, чтобы preferredHighlightEnd было больше или равно preferredHighlightBegin.

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 мс.

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 отобразит все элементы на пути.

snapMode : enumeration

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

• 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, real y)

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

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

Item itemAt(x, real y)

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

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

positionViewAtIndex(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)