Тип QML Flickable

Обеспечивает поверхность, которую можно "встряхнуть" Подробнее...

Оператор импорта:	import QtQuick 2.7
Наследует от:	Item
Наследует:	GridView и ListView

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

Свойства

atXBeginning : bool
atXEnd : bool
atYBeginning : bool
atYEnd : bool
bottomMargin : real
boundsBehavior : перечисление
contentHeight : real
contentItem : Item
contentWidth : real
contentX : real
contentY : real
dragging : bool
draggingHorizontally : bool
draggingVertically : bool
flickDeceleration : real
flickableDirection : перечисление
flicking : bool
flickingHorizontally : bool
flickingVertically : bool
horizontalOvershoot : real
horizontalVelocity : real
interactive : bool
leftMargin : real
maximumFlickVelocity : real
moving : bool
movingHorizontally : bool
movingVertically : bool
originX : real
originY : real
pixelAligned : bool
pressDelay : int
rebound : Transition
rightMargin : real
topMargin : real
verticalOvershoot : real
verticalVelocity : real
visibleArea
- visibleArea.xPosition : real
- visibleArea.widthRatio : real
- visibleArea.yPosition : real
- visibleArea.heightRatio : real

Сигналы

Методы

cancelFlick()
flick(qreal xVelocity, qreal yVelocity)
resizeContent(real width, real height, QPointF center)
returnToBounds()

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

Элемент Flickable размещает своих потомков на поверхности, которую можно перетаскивать и "встряхивать", вызывая прокрутку отображения на элементах потомков. Это поведение является основой элементов, которые предназначены для отображения большого количества элементов потомков, таких как ListView и GridView.

В традиционных пользовательских интерфейсах прокрутку представлений можно выполнять с помощью стандартных элементов управления, таких как полосы прокрутки и кнопки со стрелками. В некоторых ситуациях также можно перетаскивать представление непосредственно, удерживая нажатой кнопку мыши, перемещая указатель. В интерфейсах, ориентированных на сенсорное управление, это перетаскивание часто дополняется "встряхиванием", когда прокрутка продолжается после того, как пользователь перестал касаться представления.

Flickable не автоматически обрезает содержимое. Если он не используется как элемент на весь экран, рекомендуется установить свойство clip в значение true.

Пример использования

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

import QtQuick 2.0

Flickable {
    width: 200; height: 200
    contentWidth: image.width; contentHeight: image.height

    Image { id: image; source: "bigImage.png" }
}

Элементы, объявленные как потомки Flickable, автоматически добавляются в иерархию потомков contentItem Flickable. Это следует учитывать при работе с потомками Flickable; обычно имеют значение потомки contentItem. Например, границы элементов, добавленных в Flickable, будут доступны с помощью contentItem.childrenRect

Ограничения

Примечание: Из-за особенности реализации элементы, размещенные внутри Flickable, не могут быть привязаны к Flickable. Вместо этого используйте parent, который ссылается на contentItem Flickable. Размер элемента содержимого определяется contentWidth и contentHeight.

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

atXBeginning : bool

Эти свойства равны true, если представление flickable расположено в начале или конце соответственно.

atXEnd : bool

Эти свойства равны true, если представление flickable расположено в начале или конце соответственно.

atYBeginning : bool

Эти свойства равны true, если представление flickable расположено в начале или конце соответственно.

atYEnd : bool

Эти свойства равны true, если представление flickable расположено в начале или конце соответственно.

bottomMargin : real

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

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

Это свойство определяет, можно ли перетаскивать поверхность за границы Flickable или превышать границы Flickable при "встряхивании".

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

Значение boundsBehavior может быть одним из следующих:

Flickable.StopAtBounds - содержимое не может быть перетащено за пределы границы flickable, и встряхивание не выйдет за пределы.
Flickable.DragOverBounds - содержимое может быть перетащено за пределы границы Flickable, но встряхивание не выйдет за пределы.
Flickable.OvershootBounds - содержимое может выйти за пределы при "встряхивании", но содержимое не может быть перетащено за пределы границы flickable. (с QtQuick 2.5)
Flickable.DragAndOvershootBounds (по умолчанию) - содержимое может быть перетащено за пределы границы Flickable и может выйти за пределы при "встряхивании".

См. также horizontalOvershoot и verticalOvershoot.

contentHeight : real

Размеры содержимого (поверхности, управляемой Flickable). Обычно это должно быть равно суммарному размеру элементов, помещенных в Flickable.

Следующий фрагмент показывает, как используются эти свойства для отображения изображения, которое больше, чем сам элемент Flickable:

import QtQuick 2.0

Flickable {
    width: 200; height: 200
    contentWidth: image.width; contentHeight: image.height

    Image { id: image; source: "bigImage.png" }
}

В некоторых случаях размеры содержимого могут автоматически устанавливаться на основе свойств childrenRect.width и childrenRect.height элемента contentItem. Например, предыдущий фрагмент кода можно переписать следующим образом:

contentWidth: contentItem.childrenRect.width; contentHeight: contentItem.childrenRect.height

Хотя это предполагает, что начало координат childrenRect равно 0,0.

contentItem : Item

Внутренний элемент, содержащий элементы, которые нужно перемещать в Flickable.

Элементы, объявленные как дочерние элементы Flickable, автоматически становятся дочерними элементами contentItem Flickable.

Динамически созданные элементы необходимо явно привязать к элементу contentItem:

Flickable {
    id: myFlickable
    function addItem(file) {
        var component = Qt.createComponent(file)
        component.createObject(myFlickable.contentItem);
    }
}

contentWidth : real

Размеры содержимого (поверхности, контролируемой Flickable). Обычно это должно быть равно объединенному размеру элементов, размещенных в Flickable.

Следующий фрагмент кода демонстрирует, как эти свойства используются для отображения изображения, размер которого больше, чем сам элемент Flickable:

import QtQuick 2.0

Flickable {
    width: 200; height: 200
    contentWidth: image.width; contentHeight: image.height

    Image { id: image; source: "bigImage.png" }
}

contentWidth: contentItem.childrenRect.width; contentHeight: contentItem.childrenRect.height

Хотя это предполагает, что начало координат childrenRect равно 0,0.

contentX : real

Эти свойства хранят координату поверхности, которая в данный момент находится в верхнем левом углу Flickable. Например, если вы перетащите изображение вверх на 100 пикселей, contentY увеличится на 100.

Примечание: Если вы вернетесь к началу координат (верхнему левому углу) после анимации отскока, contentX установится на то же значение, что и originX, а contentY на то же, что и originY. Обычно они равны (0,0), однако у ListView и GridView может быть произвольное начало координат из-за изменения размеров делегатов или вставки/удаления элементов за пределами видимой области. Поэтому, если вы хотите реализовать что-то вроде вертикальной полосы прокрутки, один из способов — использовать y: (contentY - originY) * (height / contentHeight) для положения; другой способ — использовать нормализованные значения в visibleArea.

См. также originX и originY.

contentY : real

См. также originX и originY.

dragging : bool

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

draggingHorizontally : bool

draggingVertically : bool

flickDeceleration : real

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

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

flickableDirection : enumeration

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

Flickable.AutoFlickDirection (по умолчанию) — позволяет выполнять рывок по вертикали, если contentHeight не равно height Flickable. Позволяет выполнять рывок по горизонтали, если contentWidth не равно width Flickable.
Flickable.AutoFlickIfNeeded — позволяет выполнять рывок по вертикали, если contentHeight больше height Flickable. Позволяет выполнять рывок по горизонтали, если contentWidth больше width Flickable. (начиная с QtQuick 2.7)
Flickable.HorizontalFlick — позволяет выполнять рывок по горизонтали.
Flickable.VerticalFlick — позволяет выполнять рывок по вертикали.
Flickable.HorizontalAndVerticalFlick — позволяет выполнять рывок в обоих направлениях.

flicking : bool

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

flickingHorizontally : bool

flickingVertically : bool

horizontalOvershoot : real

Это свойство хранит горизонтальный отскок, то есть горизонтальное расстояние, на которое содержимое было перетащено или протащено за пределы Flickable. Значение отрицательное, когда содержимое перетащено или протащено за начало, и положительное — за конец; 0.0 в противном случае.

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

См. также verticalOvershoot и boundsBehavior.

horizontalVelocity : real

Мгновенная скорость движения по осям x и y в пикселях/сек.

Отчетная скорость сглаживается, чтобы избежать нестабильных значений.

Обратите внимание, что для представлений с большим размером содержимого (более чем в 10 раз больше размера представления) скорость рывка может превысить скорость касания в случае нескольких быстрых последовательных рывков. Это позволяет пользователю прокручивать большое содержимое быстрее.

interactive : bool

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

По умолчанию это свойство равно true.

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

leftMargin : real

Эти свойства содержат отступы вокруг содержимого. Это пространство зарезервировано в дополнение к contentWidth и contentHeight.

maximumFlickVelocity : real

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

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

moving : bool

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

movingHorizontally : bool

movingVertically : bool

originX : real

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

Обычно это (0,0), однако у ListView и GridView может быть произвольное начало из-за изменения размеров делегатов или вставки/удаления элементов за пределами видимой области.

См. также contentX и contentY.

originY : real

См. также contentX и contentY.

pixelAligned : bool

Это свойство устанавливает выравнивание contentX и contentY по пикселям (true) или субпикселям (false).

Включите pixelAligned для оптимизации статического содержимого или движущегося содержимого с чёткими границами, такими как линии шириной в один пиксель, текст или векторная графика. Отключите pixelAligned при оптимизации качества анимации.

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

pressDelay : int

Это свойство содержит время задержки (мс) доставки события нажатия на дочерние элементы Flickable. Это может быть полезно, когда реагирование на нажатие перед действием flicking имеет нежелательные последствия.

Если Flickable перетаскивается/flickется до истечения времени задержки, событие нажатия не будет доставлено. Если кнопка отпущена в течение таймаута, будут доставлены как событие нажатия, так и событие отпуска.

Обратите внимание, что для вложенных Flickable с установленным pressDelay задержка pressDelay внешних Flickable перекрывается внутренним Flickable. Если перетаскивание превышает порог перетаскивания платформы, событие нажатия будет доставлено независимо от этого свойства.

См. также QStyleHints.

rebound : Transition

Это свойство содержит переход, который должен быть применён к области отображения содержимого, когда она возвращается к границам Flickable. Переход запускается, когда область отображения содержимого перетаскивается или flickется за пределы области содержимого, или когда вызывается returnToBounds().

import QtQuick 2.0

Flickable {
    width: 150; height: 150
    contentWidth: 300; contentHeight: 300

    rebound: Transition {
        NumberAnimation {
            properties: "x,y"
            duration: 1000
            easing.type: Easing.OutBounce
        }
    }

    Rectangle {
        width: 300; height: 300
        gradient: Gradient {
            GradientStop { position: 0.0; color: "lightsteelblue" }
            GradientStop { position: 1.0; color: "blue" }
        }
    }
}

Когда указанная область отображения содержимого flickется за её пределы, она вернётся к границам с использованием заданного перехода:

Если это свойство не установлено, применяется анимация по умолчанию.

rightMargin : real

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

topMargin : real

verticalOvershoot : real

Это свойство хранит вертикальное превышение, то есть вертикальное расстояние, на которое содержимое было перетащено или flicked за пределы границ Flickable. Значение отрицательно, когда содержимое перетащено или flicked за начало, и положительно, когда за конец; 0.0 в противном случае.

Это свойство QML было введено в Qt 5.9.

См. также horizontalOvershoot и boundsBehavior.

verticalVelocity : real

Мгновенная скорость движения по осям x и y в пикселях/с.

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

Обратите внимание, что для представлений с большим размером содержимого (более чем в 10 раз превышающим размер представления) скорость flick может превысить скорость касания в случае нескольких быстрых последовательных flick. Это позволяет пользователю быстрее пролистывать большой объём содержимого.

visibleArea.xPosition : real

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

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

Rectangle {
    width: 200; height: 200

    Flickable {
        id: flickable
        ...
    }

    Rectangle {
        id: scrollbar
        anchors.right: flickable.right
        y: flickable.visibleArea.yPosition * flickable.height
        width: 10
        height: flickable.visibleArea.heightRatio * flickable.height
        color: "black"
    }
}

См. также UI-компоненты: Пример полосы прокрутки.

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

flickEnded()

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

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

flickStarted()

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

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

movementEnded()

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

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

movementStarted()

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

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

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

cancelFlick()

Отменяет текущую анимацию flick.

flick(qreal xVelocity, qreal yVelocity)

Инициирует flick содержимого со скоростью xVelocity по горизонтали и yVelocity по вертикали в пикселях/с.

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

resizeContent(real width, real height, QPointF center)

Изменяет размер содержимого на width x height относительно точки center.

Это не масштабирует содержимое Flickable — оно только изменяет размер contentWidth и contentHeight.

Изменение размера содержимого может привести к тому, что содержимое будет находиться за пределами границ Flickable. Вызов returnToBounds() вернёт содержимое в пределах допустимых границ.

returnToBounds()

Обеспечивает, что содержимое находится в пределах допустимых границ.

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

© The Qt Company Ltd
Licensed under the GNU Free Documentation License, Version 1.3.
https://doc.qt.io/qt-5.9/qml-qtquick-flickable.html