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

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

Qt::MouseButtons QWheelEvent::buttons() const

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

QPointF QWheelEvent::globalPosition() const

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

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

bool QWheelEvent::inverted() const

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

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

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

Примечание: Многие платформы не предоставляют такой информации. На таких платформах 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();
}

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

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

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

QPointF QWheelEvent::position() const

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

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

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

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

Qt::MouseEventSource QWheelEvent::source() const

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

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

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

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

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