Тип 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 задержка внешнего 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()

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

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