Класс QScroller

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

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

Открытые типы

Свойства

• scrollerProperties : QScrollerProperties
• state : const State

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

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

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

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

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

Сигналы

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

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

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

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

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

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

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

Эта функция выполняет фактическую прокрутку, вызывая 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().