Тип 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.xPosition : real
  • visibleArea.widthRatio : real
  • visibleArea.yPosition : real
  • visibleArea.heightRatio : real

Сигналы

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

Методы

• cancelFlick()
• flick(xVelocity, qreal yVelocity)
• resizeContent(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. Размер элемента content определяется значениями contentWidth и contentHeight.

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

moving : bool

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

dragging : bool

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

flicking : bool

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

originX : real

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

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

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

topMargin : real

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

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" }
}

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

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

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

atXBeginning : bool

Эти свойства равны true, если область прокрутки находится в начале или конце соответственно.

horizontalVelocity : real

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

Указанная скорость сглажена для предотвращения нестабильных результатов.

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

contentX : real

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

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

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

boundsBehavior : enumeration

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

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

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

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

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

boundsMovement : enumeration

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

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

• 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

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

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

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

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, pressDelay внешних Flickable переопределяется самым внутренним Flickable. Если перетаскивание превышает порог перетаскивания платформы, событие press будет доставлено независимо от этого свойства.

См. также 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" }
        }
    }
}

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

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

synchronousDrag : bool

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

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

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

verticalOvershoot : real

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

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

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

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

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"
    }
}

См. также Примеры пользовательских элементов управления: пример полосы прокрутки.

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

flickEnded()

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

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

flickStarted()

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

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

movementEnded()

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

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

movementStarted()

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

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

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

cancelFlick()

Отменяет текущую анимацию прокрутки.

flick(xVelocity, qreal yVelocity)

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

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

resizeContent(width, real height, QPointF center)

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

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

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

returnToBounds()

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

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