Тип 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 : Переход
• 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(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. Размер элемента содержимого определяется значениями 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.

Эти свойства истинны, если виджет 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 : перечисление

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

boundsMovement : перечисление

Это свойство указывает, будет ли у 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 : Элемент

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

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

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

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

flickDeceleration : вещественное

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

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

flickableDirection : перечисление

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

• 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 : вещественное

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

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

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

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

interactive : логическое

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

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

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

maximumFlickVelocity : вещественное

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

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

pixelAligned : логическое

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

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

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

pressDelay : целое

Это свойство хранит время задержки (мс) доставки нажатия на дочерние элементы 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" }
        }
    }
}

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

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

synchronousDrag : bool

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

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

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

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(xVelocity, qreal yVelocity)

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

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

resizeContent(width, real height, QPointF center)

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

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

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

returnToBounds()

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

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