Класс QScroller

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

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

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

Свойства

• 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));

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

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

Пример Dir View демонстрирует один из способов использования QScroller с QTreeView. Пример в каталоге scroller также демонстрирует QScroller.

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

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

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

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

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

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

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

enum QScroller::State

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

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

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

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

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

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

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

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

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

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

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

void QScroller::resendPrepareEvent()

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

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

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

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

void QScroller::scrollTo(const QPointF &pos)

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

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

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

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

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

void QScroller::scrollerPropertiesChanged(const QScrollerProperties &newProperties)

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

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

См. также scrollerProperties.

void QScroller::stateChanged(QScroller::State newState)

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

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

См. также state.

QList<QScroller *> QScroller::activeScrollers()

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

QPointF QScroller::finalPosition() const

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

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

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

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

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

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

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

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

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().