Класс QWheelEvent

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

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

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

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

События прокрутки колесика отправляются виджету под курсором мыши, но если этот виджет не обрабатывает событие, оно отправляется фокусному виджету. События прокрутки генерируются как для колесика мыши, так и для жестов прокрутки на трекпаде.

Существует два способа чтения дельты события прокрутки:

angleDelta() возвращает дельту в градусах поворота колесика. Эти значения всегда предоставляются.

pixelDelta() возвращает дельту в пикселях экрана, и доступна на платформах с высокоточными трекпадами, такими как macOS. В этом случае source() вернёт Qt::MouseEventSynthesizedBySystem.

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

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

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

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

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

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

QWheelEvent::QWheelEvent(QPointF pos, QPointF globalPos, QPoint pixelDelta, QPoint angleDelta, Qt::MouseButtons buttons, Qt::KeyboardModifiers modifiers, Qt::ScrollPhase phase, bool inverted, Qt::MouseEventSource source = Qt::MouseEventNotSynthesized)

Создаёт объект события прокрутки колесика.

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

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

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

Фаза прокрутки события задаётся phase.

Если событие прокрутки поступает с физического колесика мыши, source устанавливается в Qt::MouseEventNotSynthesized. Если оно поступает от жеста, обнаруженного операционной системой, или от устройства ввода, отличного от мыши, так что pixelDelta напрямую связан с перемещением пальцев, source устанавливается в Qt::MouseEventSynthesizedBySystem. Если оно поступает от Qt, source будет установлено в Qt::MouseEventSynthesizedByQt.

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

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

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

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();
}

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

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

\seepixelDelta()

Qt::MouseButtons QWheelEvent::buttons() const

Возвращает состояние мыши в момент возникновения события.

QPointF QWheelEvent::globalPosition() const

Возвращает глобальное положение указателя мыши в момент события. Это важно в асинхронных системах окон, таких как X11; когда вы перемещаете свои виджеты в ответ на события мыши, globalPosition() может сильно отличаться от текущего положения курсора, возвращаемого QCursor::pos().

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

bool QWheelEvent::inverted() const

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

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

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

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

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

Qt::ScrollPhase QWheelEvent::phase() const

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

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

Эта функция была добавлена в 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();
}

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

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

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

QPointF QWheelEvent::position() const

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

Если вы перемещаете виджеты в ответ на события мыши, используйте globalPosition() вместо этой функции.

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

Qt::MouseEventSource QWheelEvent::source() const

Возвращает информацию о источнике события прокрутки.

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

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

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

См. также Qt::MouseEventSource.