Класс QTouchEvent

Класс 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, чтобы они могли соответствующим образом обновить своё состояние.

Функции pointCount() и point() могут использоваться для доступа и итерации по отдельным точкам касания.

Функция points() возвращает список всех точек касания, содержащихся в событии. Обратите внимание, что этот список может быть пустым, например, в случае события QEvent::TouchCancel. Каждый элемент списка — экземпляр класса QEventPoint. Перечисление QEventPoint::State описывает различные состояния, которые может иметь точка касания.

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

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

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

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

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

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

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

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

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

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

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

Ограничения

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

См. также QEventPoint, QEventPoint::State, Qt::WA_AcceptTouchEvents и QGraphicsItem::acceptTouchEvents().

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

QTouchEvent::QTouchEvent(QEvent::Type eventType, const QPointingDevice *device = nullptr, Qt::KeyboardModifiers modifiers = Qt::NoModifier, const QList<QEventPoint> &touchPoints = {})

Создаёт QTouchEvent с заданным eventType, device, touchPoints и текущими модификаторами клавиатуры в момент события.

[virtual] QTouchEvent::~QTouchEvent()

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

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

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

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

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

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

Возвращает true, если это событие не включает новых нажатых или отпущенных точек касания.

QObject *QTouchEvent::target() const

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

QEventPoint::States QTouchEvent::touchPointStates() const

Возвращает побитовое ИЛИ всех состояний точек касания для этого события.