Тип QML Flickable

Предоставляет поверхность, которую можно «провести». Подробнее...

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

Свойства

• atXBeginning : bool
• atXEnd : bool
• atYBeginning : bool
• atYEnd : bool
• bottomMargin : real
• boundsBehavior : перечисление
• boundsMovement : перечисление
• 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
• synchronousDrag : bool
• topMargin : real
• verticalOvershoot : real
• verticalVelocity : real
• visibleArea
  • visibleArea.heightRatio : real
  • visibleArea.widthRatio : real
  • visibleArea.xPosition : real
  • visibleArea.yPosition : real

Сигналы

• flickEnded()
• flickStarted()
• movementEnded()
• movementStarted()

Методы

• 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

Примеры contentX и contentY

На следующих изображениях показан flickable, который прокручивается в различных направлениях, и соответствующие значения contentX и contentY. Синий квадрат представляет содержимое flickable, а черная рамка представляет границы flickable.

Ограничения

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

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

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

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

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

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

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

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

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

Размеры содержимого (поверхности, управляемой 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.

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

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

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

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

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

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

См. также Примеры contentX и contentY, originX и originY.

boundsBehavior : enumeration

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

Когда boundsMovement равен Flickable.FollowBoundsBehavior, значение, отличное от Flickable.StopAtBounds, создаст ощущение мягких краев представления, а не жёстких физических границ.

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

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

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

[since 5.10] boundsMovement : enumeration

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

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

• Flickable.StopAtBounds — это позволяет реализовывать пользовательские эффекты краёв, где содержимое не следует перетаскиванию или flick за пределы границ flickable. Можно использовать значения horizontalOvershoot и verticalOvershoot для реализации пользовательских эффектов краёв.
• Flickable.FollowBoundsBehavior (по умолчанию) — то, следует ли содержимое перетаскиванию или flick за пределы границ flickable, определяется свойством boundsBehavior.

Следующий пример удерживает содержимое в пределах границ и вместо этого применяет эффект переворота при flick за горизонтальные границы:

Flickable {
    id: flickable
    boundsMovement: Flickable.StopAtBounds
    boundsBehavior: Flickable.DragAndOvershootBounds
    transform: Rotation {
        axis { x: 0; y: 1; z: 0 }
        origin.x: flickable.width / 2
        origin.y: flickable.height / 2
        angle: Math.min(30, Math.max(-30, flickable.horizontalOvershoot))
    }
}

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

Flickable {
    boundsMovement: Flickable.StopAtBounds
    boundsBehavior: Flickable.DragOverBounds
    opacity: Math.max(0.5, 1.0 - Math.abs(verticalOvershoot) / height)
}

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

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

contentItem : Item

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

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

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

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

flickDeceleration : real

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

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

flickableDirection : enumeration

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

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

[since 5.9] horizontalOvershoot : real

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

Сообщается ли значение для перетаскивания и/или flick определяется свойством boundsBehavior. Расстояние отскока сообщается даже при boundsMovement Flickable.StopAtBounds.

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

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

interactive : bool

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

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

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

maximumFlickVelocity : real

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

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

pixelAligned : bool

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

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

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

pressDelay : int

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

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

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

См. также QStyleHints.

rebound : Transition

Это свойство задаёт анимацию, которая будет применена к представлению содержимого, когда оно возвращается к границам Flickable. Анимация запускается, когда представление перетаскивается или фликкается за пределы области содержимого, или когда вызывается 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" }
        }
    }
}

Когда вышеупомянутое представление фликкается за пределы своих границ, оно возвращается в эти границы с использованием заданной анимации:

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

[since 5.12] synchronousDrag : bool

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

Значение по умолчанию — false, что обеспечивает более плавное взаимодействие (без рывков) ценой того, что часть расстояния перетаскивания «теряется» в начале.

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

[since 5.9] verticalOvershoot : real

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

Отчитываются ли значения для перетаскивания и/или фликкания, определяется свойством boundsBehavior. Расстояние смещения отчитывается даже когда boundsMovement равно Flickable.StopAtBounds.

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

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

visibleArea.heightRatio : 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()

Этот сигнал испускается, когда представление перестаёт двигаться из-за фликка.

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

flickStarted()

Этот сигнал испускается, когда представление фликкается. Флик начинается в тот момент, когда мышь или сенсор отпущены, но движение ещё продолжается.

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

movementEnded()

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

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

movementStarted()

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

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

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

cancelFlick()

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

flick(qreal xVelocity, qreal yVelocity)

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

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

resizeContent(real width, real height, QPointF center)

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

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

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

returnToBounds()

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

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