Класс QTouchEvent

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

Подробнее...

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

Общие типы

Общие функции

• 2 общих функции, унаследованные от QInputEvent
• 7 общих функций, унаследованных от QEvent

Дополнительные унаследованные члены

• 1 свойство, унаследованное от QEvent
• 1 общедоступная переменная, унаследованная от QEvent
• 1 статический общедоступный член, унаследованный от QEvent
• 2 защищенные переменные, унаследованные от QEvent

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

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

Включение событий касания

События касания возникают при нажатии, отпускании или перемещении одной или нескольких точек касания на сенсорном устройстве (например, сенсорном экране или трекпаде). Для получения событий касания виджеты должны иметь установленный атрибут Qt::WA_AcceptTouchEvents, а графические элементы должны иметь атрибут acceptTouchEvents установленный в значение true.

При использовании виджетов на основе QAbstractScrollArea следует включить атрибут Qt::WA_AcceptTouchEvents для области прокрутки viewport.

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

Обработка событий

Все события касания имеют тип QEvent::TouchBegin, QEvent::TouchUpdate, QEvent::TouchEnd или QEvent::TouchCancel. Для получения событий касания переопределите QWidget::event() или QAbstractScrollArea::viewportEvent() для виджетов и QGraphicsItem::sceneEvent() для элементов в графическом представлении.

В отличие от виджетов, QWindows всегда получают события касания, нет необходимости в включении. При работе непосредственно с QWindow достаточно переопределить QWindow::touchEvent().

События QEvent::TouchUpdate и QEvent::TouchEnd отправляются виджету или элементу, который принял событие QEvent::TouchBegin. Если событие QEvent::TouchBegin не принимается и не отфильтровывается фильтром событий, то дальнейшие события касания не отправляются до следующего события QEvent::TouchBegin.

Некоторые системы могут отправлять событие типа QEvent::TouchCancel. При получении этого события приложениям предлагается игнорировать всю активную последовательность касаний. Например, в составленной системе компоновщик может принять решение рассматривать определенные жесты как системные жесты. Всякий раз, когда принимается такое решение (жест распознается), клиенты будут уведомлены событием QEvent::TouchCancel, чтобы они могли соответствующим образом обновить свое состояние.

Функция touchPoints() возвращает список всех точек касания, содержащихся в событии. Обратите внимание, что этот список может быть пустым, например, в случае события QEvent::TouchCancel. Информацию о каждой точке касания можно получить с помощью класса QTouchEvent::TouchPoint. Перечисление Qt::TouchPointState описывает различные состояния, которые может иметь точка касания.

Примечание: Список touchPoints() никогда не будет частичным: событие касания всегда будет содержать точку касания для каждого существующего физического контакта, направленного на окно или виджет, которому отправляется событие. Например, предполагая, что все касания направлены на одно и то же окно или виджет, событие с условием touchPoints().count()==2 гарантированно подразумевает, что количество пальцев, касающихся сенсорного экрана или трекпада, равно ровно двум.

Доставка и распространение событий

По умолчанию QGuiApplication преобразует первую точку касания в QTouchEvent в QMouseEvent. Это позволяет включить события касания в существующих виджетах, которые обычно не обрабатывают QTouchEvent. См. ниже информацию о некоторых специальных соображениях, необходимых при этом.

QEvent::TouchBegin — это первое событие касания, отправленное в виджет. Событие QEvent::TouchBegin содержит специальный флаг принятия, который указывает, хочет ли получатель событие. По умолчанию событие принимается. Вы должны вызвать ignore(), если событие касания не обрабатывается вашим виджетом. Событие QEvent::TouchBegin распространяется вверх по цепочке родительских виджетов до тех пор, пока виджет не примет его с помощью accept() или фильтр событий не потребляет его. Для QGraphicsItems событие QEvent::TouchBegin распространяется на элементы под указателем (аналогично распространению событий мыши для QGraphicsItems).

Группировка точек касания

Как упоминалось выше, возможно, что несколько виджетов могут получать QTouchEvents одновременно. Однако Qt гарантирует, что никогда не отправляет дублируемые события QEvent::TouchBegin одному и тому же виджету, что теоретически могло произойти во время распространения, если, например, пользователь коснулся 2 отдельных виджетов в QGroupBox, и оба виджета проигнорировали событие QEvent::TouchBegin.

Для предотвращения этого Qt будет группировать новые точки касания по следующим правилам:

• При обнаружении первой точки касания целевой виджет определяется сначала по расположению на экране, а затем по правилам распространения.
• При обнаружении дополнительных точек касания Qt сначала проверяет, есть ли какие-либо активные точки касания на каком-либо предке или потомке виджета под новой точкой касания. Если они есть, новая точка касания группируется с первой, а новая точка касания будет отправлена ​​в одном QTouchEvent в виджет, который обработал первую точку касания. (Виджет под новой точкой касания не получит события).

Это позволяет независимо обрабатывать события касания для соседних виджетов, одновременно гарантируя, что последовательность QTouchEvents всегда будет корректной.

События мыши и синтезирование событий касания

Доставка QTouchEvent независима от QMouseEvent. Флаги приложения Qt::AA_SynthesizeTouchForUnhandledMouseEvents и Qt::AA_SynthesizeMouseForUnhandledTouchEvents могут использоваться для включения или отключения автоматического синтезирования событий касания в события мыши и событий мыши в события касания.

Ограничения

• Как упоминалось выше, включение событий касания означает, что несколько виджетов могут получать события касания одновременно. В сочетании с обработкой QWidget::event() по умолчанию для QTouchEvents это дает вам большую гибкость в проектировании сенсорных пользовательских интерфейсов. Будьте осведомлены о последствиях. Например, возможно, что пользователь перемещает QSlider одним пальцем и нажимает QPushButton другим. Сигналы, испускаемые этими виджетами, будут чередоваться.
• Рекурсия в цикл событий с использованием одного из методов exec() (например, QDialog::exec() или QMenu::exec()) в обработчике событий QTouchEvent не поддерживается. Поскольку есть несколько получателей событий, рекурсия может вызвать проблемы, включая, но не ограничиваясь, потерянными событиями и непредвиденной бесконечной рекурсией.
• QTouchEvents не зависят от захвата мыши или активного всплывающего виджета. Поведение QTouchEvents не определено при открытии всплывающего окна или захвате мыши, когда существует более одной активной точки касания.

См. также QTouchEvent::TouchPoint, Qt::TouchPointState, Qt::WA_AcceptTouchEvents и QGraphicsItem::acceptTouchEvents().

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

QTouchEvent::QTouchEvent(QEvent::Type eventType, QTouchDevice *device = nullptr, Qt::KeyboardModifiers modifiers = Qt::NoModifier, Qt::TouchPointStates touchPointStates = Qt::TouchPointStates(), const QList<QTouchEvent::TouchPoint> &touchPoints = QList<QTouchEvent::TouchPoint>())

Конструирует QTouchEvent с заданным eventType, device и touchPoints. touchPointStates и modifiers — текущие состояния точек касания и модификаторы клавиатуры на момент возникновения события.

[virtual] QTouchEvent::~QTouchEvent()

Уничтожает QTouchEvent.

QTouchDevice *QTouchEvent::device() const

Возвращает устройство касания, из которого происходит данное событие касания.

QObject *QTouchEvent::target() const

Возвращает целевой объект в окне, в котором произошло событие. Обычно это QWidget или QQuickItem. Может быть 0, если целевой объект не определён.

Qt::TouchPointStates QTouchEvent::touchPointStates() const

Возвращает битовую сумму всех состояний точек касания для данного события.

const QList<QTouchEvent::TouchPoint> &QTouchEvent::touchPoints() const

Возвращает список точек касания, содержащихся в событии касания.

QWindow *QTouchEvent::window() const

Возвращает окно, в котором произошло событие. Полезно для выполнения глобально-локального отображения данных, таких как rawScreenPositions(), которые для повышения производительности хранят только глобальные позиции в событии касания.