Тип QML Flickable

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

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

Свойства

• atXBeginning : bool
• atXEnd : bool
• atYBeginning : bool
• atYEnd : bool
• bottomMargin : real
• boundsBehavior : перечисление
• boundsMovement : перечисление
• contentHeight : real
• contentItem : Элемент
• 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 : Переход
• 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.

Ограничения

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

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

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

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

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

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

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

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

boundsBehavior : enumeration

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

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

Это свойство может быть одним из:

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

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

[since 5.10] boundsMovement : enumeration

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

Это свойство может быть одним из:

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

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

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

Это свойство определяет скорость замедления флика: чем больше число, тем быстрее он замедляется, когда пользователь прекращает флик с помощью касания, тачпада или колесика мыши. Например, 0.0001 почти «беспроблемный», а 10000 ощущается довольно «вязким».

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

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 - позволяет прокручивать в обоих направлениях.

[since 5.9] horizontalOvershoot : real

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

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

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

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

interactive : bool

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

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

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

maximumFlickVelocity : real

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

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

pixelAligned : bool

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

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

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

pressDelay : int

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

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

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

См. также QStyleHints.

rebound : Transition

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

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

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

[с 5.12] synchronousDrag : bool

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

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

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

[с 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 Components: Scrollbar Example.

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

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

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

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