Класс QScroller

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

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

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

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

Свойства

• scrollerProperties : QScrollerProperties
• состояние : const State

Функции публичного доступа

Свойства публичного доступа

Сигналы

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

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

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

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

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

или напрямую так:

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

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

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

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

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

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

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

перечисление QScroller::Ввод

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

перечисление QScroller::ТипЖестаПрокрутки

Это перечисление содержит различные типы жестов, поддерживаемые распознавателем жестов 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().