Класс 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.