Класс QWheelEvent

Класс QWheelEvent содержит параметры, описывающие событие прокрутки колеса. Подробнее...

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

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

Переопределённые открытые функции

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

События прокрутки колеса отправляются виджету под курсором мыши, но если этот виджет не обрабатывает событие, они отправляются виджету, имеющему фокус. События прокрутки колеса генерируются как для колёс мыши, так и для жестов прокрутки трекпада. Есть два способа чтения дельты события прокрутки: angleDelta() возвращает дельты в градусах поворота колеса. Эти значения всегда предоставляются. pixelDelta() возвращает дельты в пикселях экрана, и доступна на платформах с высокоразрешающими трекпадами, такими как macOS. Если это так, device()->type() вернёт QInputDevice::DeviceType::Touchpad.

Функции position() и globalPosition() возвращают положение курсора мыши в момент события.

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

Функция QWidget::setEnabled() может использоваться для включения или выключения событий мыши и клавиатуры для виджета.

Обработчик событий QWidget::wheelEvent() получает события прокрутки колеса.

См. также QMouseEvent и QWidget::grabMouse().

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

[since 5.12] QWheelEvent::QWheelEvent(const QPointF &pos, const QPointF &globalPos, QPoint pixelDelta, QPoint angleDelta, Qt::MouseButtons buttons, Qt::KeyboardModifiers modifiers, Qt::ScrollPhase phase, bool inverted, Qt::MouseEventSource source = Qt::MouseEventNotSynthesized, const QPointingDevice *device = QPointingDevice::primaryPointingDevice())

Конструирует объект события прокрутки колеса.

pos указывает расположение курсора мыши в окне. Положение в глобальных координатах задаётся параметром globalPos.

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

Состояния мыши и клавиатуры в момент события задаются параметрами buttons и modifiers.

Фаза прокрутки события задаётся параметром phase, а source указывает, является ли это реальным или искусственным (синтезированным) событием.

Если система настроена на инвертирование значений дельты, передаваемых с событием (например, естественная прокрутка трекпада на macOS), inverted должно быть true. В противном случае, inverted равно false

Устройство, с которого исходит событие прокрутки колеса, задаётся параметром device.

Эта функция была добавлена в Qt 5.12.

См. также position(), globalPosition(), angleDelta(), pixelDelta(), phase(), inverted() и device().

QPoint QWheelEvent::angleDelta() const

Возвращает относительное количество поворота колеса в восьмых долях градуса. Положительное значение указывает, что колесо поворачивалось вперёд от пользователя; отрицательное значение указывает, что колесо поворачивалось назад к пользователю. angleDelta().y() предоставляет угол поворота обычного вертикального колеса мыши с момента предыдущего события. angleDelta().x() предоставляет угол поворота горизонтального колеса мыши, если у мыши есть горизонтальное колесо; в противном случае он остаётся нулевым. Некоторые мыши позволяют пользователю наклонять колесо для выполнения горизонтальной прокрутки, а некоторые трекпады поддерживают горизонтальный жест прокрутки; это также будет отображено в angleDelta().x().

Большинство типов мышей работают шагами по 15 градусов, в этом случае значение дельты является кратным 120; то есть 120 единиц * 1/8 = 15 градусов.

Однако у некоторых мышей есть колёса с более высоким разрешением и они отправляют значения дельты, меньшие 120 единиц (меньше 15 градусов). Для поддержки этой возможности вы можете либо кумулятивно складывать значения дельты из событий до достижения значения 120, а затем прокручивать виджет, либо частично прокручивать виджет в ответ на каждое событие прокрутки. Но для более естественного ощущения вы должны отдавать предпочтение pixelDelta() на платформах, где это доступно.

Пример:

void MyWidget::wheelEvent(QWheelEvent *event)
{
    QPoint numPixels = event->pixelDelta();
    QPoint numDegrees = event->angleDelta() / 8;

    if (!numPixels.isNull()) {
        scrollWithPixels(numPixels);
    } else if (!numDegrees.isNull()) {
        QPoint numSteps = numDegrees / 15;
        scrollWithDegrees(numSteps);
    }

    event->accept();
}

Примечание: На платформах, поддерживающих фазы прокрутки phase(), дельта может быть нулевой, когда:

• прокрутка только что началась, но расстояние ещё не изменилось (Qt::ScrollBegin),
• или прокрутка закончилась и расстояние больше не изменилось (Qt::ScrollEnd).

Примечание: Функция-геттер для свойства angleDelta.

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

[since 5.7] bool QWheelEvent::inverted() const

Возвращает, инвертированы ли значения дельты, переданные с событием.

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

Однако на некоторых платформах это настраивается, так что те же операции, описанные выше, дадут отрицательные значения дельты (но с той же величиной). С помощью свойства inverted потребитель события прокрутки колеса может выбрать всегда следовать направлению вращения колеса, независимо от настроек системы, но только для определённых виджетов. (Один из таких вариантов использования может заключаться в том, что пользователь вращает колесо в том же направлении, что и вращается визуальный ползунок. Другой вариант использования заключается в том, чтобы рукоятка ползунка следила за направлением движения пальцев на трекпаде независимо от конфигурации системы.)

Примечание: Многие платформы не предоставляют такой информации. На таких платформах inverted всегда возвращает false.

Примечание: Функция-геттер для свойства inverted.

Эта функция была добавлена в Qt 5.7.

[override virtual] bool QWheelEvent::isBeginEvent() const

Переопределяет: QSinglePointEvent::isBeginEvent() const.

Возвращает true если фаза (phase) этого события равна Qt::ScrollBegin.

[override virtual] bool QWheelEvent::isEndEvent() const

Переопределяет: QSinglePointEvent::isEndEvent() const.

Возвращает true если фаза (phase) этого события равна Qt::ScrollEnd.

[override virtual] bool QWheelEvent::isUpdateEvent() const

Переопределяет: QSinglePointEvent::isUpdateEvent() const.

Возвращает true если фаза (phase) этого события равна Qt::ScrollUpdate или Qt::ScrollMomentum.

[since 5.2] Qt::ScrollPhase QWheelEvent::phase() const

Возвращает фазу прокрутки этого события колеса.

Примечание: Фазы Qt::ScrollBegin и Qt::ScrollEnd в настоящее время поддерживаются только на macOS.

Примечание: Функция-получатель для свойства phase.

Эта функция была добавлена в Qt 5.2.

QPoint QWheelEvent::pixelDelta() const

Возвращает расстояние прокрутки в пикселях на экране. Это значение предоставляется на платформах, которые поддерживают высокоточные значения дельты на основе пикселей, такие как macOS. Значение должно использоваться непосредственно для прокрутки содержимого на экране.

Пример:

void MyWidget::wheelEvent(QWheelEvent *event)
{
    QPoint numPixels = event->pixelDelta();
    QPoint numDegrees = event->angleDelta() / 8;

    if (!numPixels.isNull()) {
        scrollWithPixels(numPixels);
    } else if (!numDegrees.isNull()) {
        QPoint numSteps = numDegrees / 15;
        scrollWithDegrees(numSteps);
    }

    event->accept();
}

Примечание: На платформах, поддерживающих фазы прокрутки phases, дельта может быть нулевой, когда:

• начало прокрутки ещё не произошло, но расстояние ещё не изменилось (Qt::ScrollBegin),
• или прокрутка завершена и расстояние больше не изменилось (Qt::ScrollEnd).

Примечание: В X11 это значение зависит от драйвера и ненадежно, используйте angleDelta() вместо него.

Примечание: Функция-получатель для свойства pixelDelta.