Класс QScroller

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

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

Типы

Свойства

• scrollerProperties : QScrollerProperties
• state : const State

• 1 свойство унаследовано от QObject

Открытые функции

• 34 открытых функции унаследованы от QObject

Открытые слоты

• 1 открытый слот унаследован от QObject

Сигналы

• 2 сигнала унаследованы от QObject

Статические открытые члены

• 10 статических открытых членов унаследованы от QObject

Дополнительные унаследованные члены

• 1 открытая переменная унаследована от QObject
• 9 защищенных функций унаследованы от QObject
• 2 защищенные переменные унаследованы от QObject

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

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

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

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

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

или напрямую, как показано ниже:

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

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

Scroller использует глобальный таймер QAbstractAnimation для создания событий QScrollEvent. Это можно изменить с помощью QScrollerProperties::FrameRate для каждого QScroller.

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

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

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

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

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

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

enum QScroller::ScrollerGestureType

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

enum QScroller::State

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

[slot] void QScroller::resendPrepareEvent()

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

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

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

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

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

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

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

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

Это перегруженный метод.

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

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

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

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

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

Это перегруженный метод.

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

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

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

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

См. также scrollerProperties.

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.

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

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

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

См. также state.

void QScroller::stop()

Останавливает скроллер и сбрасывает его состояние в Inactive.

QObject *QScroller::target() const

Возвращает целевой объект этого скроллера.

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

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

Отпускает жестикуляцию для target. Не делает ничего, если жестикуляция не захвачена.

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

QPointF QScroller::velocity() const

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

Скорость возвращается для осей x и y по отдельности с помощью QPointF.

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