Класс QScroller

Класс QScroller позволяет реализовать кинетическое прокручивание для любых виджетов прокрутки или графических элементов. Подробнее...

Этот класс был представлен в Qt 5.0.

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

Типы публичного доступа

Свойства

• scrollerProperties : QScrollerProperties
• state : const State

Публичные функции

Свойства доступа

Сигналы

Статические публичные члены

Подробное описание

Кинетическое прокручивание позволяет пользователю прижать виджет в заданном направлении, и он будет продолжать прокручиваться в этом направлении до тех пор, пока не остановится либо пользователем, либо трением. Параметры инерции, трения и других физических концепций можно изменить, чтобы настроить интуитивно понятный пользовательский опыт.

Объект QScroller — это объект, который хранит текущее положение и скорость прокрутки и отвечает за обновления. QScroller может быть активирован жестом фликом

    QWidget *w = ...;
    QScroller::grabGesture(w, QScroller::LeftMouseButtonGesture);

или напрямую, например:

    QWidget *w = ...;
    QScroller *scroller = QScroller::scroller(w);
    scroller->scrollTo(QPointF(100, 100));

Прокручиваемые объекты получают QScrollPrepareEvent всякий раз, когда прокручивателю необходимо обновить информацию о своей геометрии, и QScrollEvent — всякий раз, когда содержимое объекта фактически должно быть прокручено.

Прокручиватель использует глобальный таймер QAbstractAnimation, чтобы генерировать свои QScrollEvents. Это можно изменить с помощью QScrollerProperties::FrameRate на основе каждого QScroller.

Несколько примеров в каталоге scroller показывают, как можно использовать QScroller, QScrollEvent и жесты прокрутки.

Несмотря на то, что у этого кинетического прокручивателя имеется большое количество настроек, доступных через QScrollerProperties, мы рекомендуем оставить их все по умолчанию, оптимизированным для платформы. Прежде чем их менять, вы можете поэкспериментировать с примером plot в каталоге scroller примеров.

См. также QScrollEvent, QScrollPrepareEvent и QScrollerProperties.

Документация по типам членов

перечисление QScroller::Input

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

перечисление QScroller::ScrollerGestureType

Это перечисление содержит различные типы жестов, которые поддерживаются распознавателем жестов QScroller.

enum QScroller::State

Этот перечисление содержит различные состояния QScroller.

Документация по членам-функциям

[slot] void QScroller::ensureVisible(const QRectF &rect, qreal xmargin, qreal ymargin, int scrollTime)

Это перегруженная функция.

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

[slot] void QScroller::ensureVisible(const QRectF &rect, qreal xmargin, qreal ymargin)

Начинает прокрутку так, чтобы прямоугольник rect был виден внутри области просмотра с дополнительными отступами, указанными в пикселях xmargin и ymargin вокруг прямоугольника.

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

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

Эта функция выполняет фактическую прокрутку, вызывая scrollTo().

См. также scrollTo().

[slot] void QScroller::resendPrepareEvent()

Эта функция повторно отправляет QScrollPrepareEvent. Вызов resendPrepareEvent вызывает QScrollPrepareEvent из прокрутчика. Это позволяет получателю повторно установить позицию содержимого и размер содержимого во время прокрутки. Вызов этой функции в состоянии Inactive бесполезен, так как событие prepare снова отправляется перед началом прокрутки.

[slot] void QScroller::scrollTo(const QPointF &pos, int scrollTime)

Это перегруженная функция.

Этот вариант достигнет своей конечной позиции за scrollTime миллисекунд.

[slot] void QScroller::scrollTo(const QPointF &pos)

Начинает прокрутку виджета так, чтобы точка pos была в верхнем левом углу области просмотра.

Поведение при прокрутке за пределами допустимой области прокрутки не определено. В этом случае прокрутчик может или не может перескочить.

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

pos задается в координатах области просмотра.

См. также ensureVisible().

[signal] void QScroller::scrollerPropertiesChanged(const QScrollerProperties &newProperties)

QScroller излучает этот сигнал всякий раз, когда меняются его свойства прокрутки. newProperties — новые свойства прокрутки.

Примечание: Сигнал уведомления для свойства scrollerProperties.

См. также scrollerProperties.

[signal] void QScroller::stateChanged(QScroller::State newState)

QScroller излучает этот сигнал всякий раз, когда состояние меняется. newState — новое состояние.

Примечание: Сигнал уведомления для свойства state.

См. также state.

[static] QList<QScroller *> QScroller::activeScrollers()

Возвращает список всех активных объектов QScroller в приложении. Активные объекты QScroller находятся в состоянии state(), которое не равно QScroller::Inactive. Эта функция полезна при написании собственного распознавателя жестов.

QPointF QScroller::finalPosition() const

Возвращает оценочную конечную позицию для текущего движения прокрутки. Возвращает текущую позицию, если состояние прокрутчика не Scrolling. Результат не определён, когда состояние прокрутчика Inactive.

Целевая позиция задается в пикселях.

См. также pixelPerMeter() и scrollTo().

[static] Qt::GestureType QScroller::grabGesture(QObject *target, QScroller::ScrollerGestureType scrollGestureType = TouchGesture)

Регистрирует пользовательский распознаватель жестов прокрутки, захватывает его для target и возвращает тип полученного жеста. Если scrollGestureType установлен в TouchGesture, жест срабатывает на событиях касания. Если он установлен в LeftMouseButtonGesture, RightMouseButtonGesture или MiddleMouseButtonGesture, он срабатывает на событиях мыши соответствующей кнопки.

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

Примечание: Чтобы избежать нежелательных побочных эффектов, события мыши потребляются во время срабатывания жеста. Поскольку начальное событие нажатия мыши не потребляется, жест отправляет фальшивое событие отпускания мыши в глобальной позиции (INT_MIN, INT_MIN). Это гарантирует согласованность внутренних состояний виджета, который получил первоначальное нажатие мыши.

См. также ungrabGesture() и grabbedGesture().

[static] Qt::GestureType QScroller::grabbedGesture(QObject *target)

Возвращает тип жеста, в данный момент захваченного для target, или 0, если ни один жест не захвачен.

См. также grabGesture() и ungrabGesture().

bool QScroller::handleInput(QScroller::Input input, const QPointF &position, qint64 timestamp = 0)

Эта функция используется распознавателями жестов для информирования прокрутки о новом событии ввода. Прокрутка изменяет своё внутреннее состояние state() в соответствии с событием ввода и свойствами прикрепленной прокрутки. Прокрутка не различает тип устройства ввода, с которого произошло событие. Поэтому событие необходимо разделить на тип input, position и миллисекундное timestamp. Position должно быть в системе координат целевого объекта.

Возвращаемое значение — true если событие должно быть обработано вызывающим фильтром или false если событие должно быть передано в компонент.

Примечание: Использование grabGesture() должно быть достаточно для большинства случаев использования.

[static] bool QScroller::hasScroller(QObject *target)

Возвращает true если для target уже был создан объект QScroller; false в противном случае.

См. также scroller().

QPointF QScroller::pixelPerMeter() const

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

Значение отображается для осей X и Y отдельно с помощью QPointF.

Примечание: Обратите внимание, что это значение должно быть физически корректным. Фактические настройки DPI, возвращаемые Qt для дисплея, могут быть неправильно отображены операционной системой, например, в macOS.

[static] QScroller *QScroller::scroller(QObject *target)

Возвращает прокрутку для заданного target. Пока объект существует, эта функция всегда будет возвращать тот же экземпляр QScroller. Если для target нет объекта QScroller, он будет неявно создан. Одновременно на объекте не будет активнее одного объекта QScroller.

См. также hasScroller() и target().

[static] const QScroller *QScroller::scroller(const QObject *target)

Это перегруженная функция.

Это версия scroller() с const.

void QScroller::setSnapPositionsX(const QList<qreal> &positions)

Устанавливает позиции привязки для горизонтальной оси в список positions. Это перезаписывает все ранее установленные позиции привязки и ранее установленный интервал привязки. Привязка может быть отключена пустым списком позиций.

void QScroller::setSnapPositionsX(qreal first, qreal interval)

Устанавливает позиции привязки для горизонтальной оси с равномерно распределёнными интервалами. Первая позиция привязки — first. Следующая — first + interval. Это может использоваться для реализации заголовка списка. Это перезаписывает все ранее установленные позиции привязки и ранее установленный интервал привязки. Привязка может быть отключена, установив интервал 0.0.

void QScroller::setSnapPositionsY(const QList<qreal> &positions)

Устанавливает позиции привязки для вертикальной оси в список positions. Это перезаписывает все ранее установленные позиции привязки и ранее установленный интервал привязки. Привязка может быть отключена пустым списком позиций.

void QScroller::setSnapPositionsY(qreal first, qreal interval)

Устанавливает позиции привязки для вертикальной оси с равномерно распределёнными интервалами. Первая позиция привязки — first. Следующая — first + interval. Это перезаписывает все ранее установленные позиции привязки и ранее установленный интервал привязки. Привязка может быть отключена, установив интервал 0.0.

void QScroller::stop()

Останавливает прокрутку и сбрасывает её состояние обратно в Неактивно.

QObject *QScroller::target() const

Возвращает целевой объект этой прокрутки.

См. также hasScroller() и scroller().

[static] void QScroller::ungrabGesture(QObject *target)

Отменяет захват жеста для target. Ничего не делает, если жест не захвачен.

См. также grabGesture() и grabbedGesture().

QPointF QScroller::velocity() const

Возвращает текущую скорость прокрутки в метрах в секунду, когда состояние равно Прокрутка или Перетаскивание. Возвращает нулевую скорость в противном случае.

Скорость отображается для осей X и Y отдельно с помощью QPointF.

См. также pixelPerMeter().