Тип Flickable QML

Обеспечивает поверхность, по которой можно «проводить пальцем». Подробнее...

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

Свойства

• atXBeginning : bool
• atXEnd : bool
• atYBeginning : bool
• atYEnd : bool
• bottomMargin : real
• boundsBehavior : enumeration
• boundsMovement : enumeration
• contentHeight : real
• contentItem : Item
• contentWidth : real
• contentX : real
• contentY : real
• dragging : bool
• draggingHorizontally : bool
• draggingVertically : bool
• flickDeceleration : real
• flickableDirection : enumeration
• 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 раз больше размера представления) скорость прокрутки может превышать скорость касания в случае нескольких быстрых последовательных прокруток. Это позволяет пользователю быстрее прокручивать большой контент.

Эти свойства содержат координату поверхности, которая в данный момент находится в левом верхнем углу 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. Это может быть полезно в тех случаях, когда реакция на нажатие до начала действия прокрутки имеет нежелательные последствия.

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

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

См. также QStyleHints.

rebound : Transition

Здесь хранится переход, который применяется к представлению содержимого, когда оно возвращается к границам прокручиваемого элемента. Переход активируется, когда представление прокручивается или перетаскивается за край области содержимого, или когда вызывается 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

Это свойство хранит вертикальное перерасстояние, то есть вертикальное расстояние, на которое содержимое было перетащено или прокручено за пределы границ прокручиваемого элемента. Значение отрицательное, когда содержимое перетаскивается или прокручивается за начало, и положительное, когда за конец; 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"
    }
}

См. также Компоненты пользовательского интерфейса: пример полосы прокрутки.

Описание сигналов

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

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

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