Класс QTouchEvent

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

Этот класс был введён в Qt 4.6.

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

Типы public

Функции public

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

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

События касания возникают при нажатии, отпускании или перемещении одной или нескольких точек касания на устройстве ввода (таком как сенсорный экран или трекпад). Для получения событий касания виджеты должны иметь установленный атрибут 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 могут использоваться для включения или выключения автоматического синтезирования событий касания в события мыши и событий мыши в события касания.

Ограничения

• Как упоминалось выше, включение событий касания означает, что несколько виджетов могут получать события касания одновременно. В сочетании с обработкой QTouchEvents по умолчанию в QWidget::event() это предоставляет большую гибкость при проектировании пользовательских интерфейсов на основе касаний. Будьте осведомлены об этих последствиях. Например, возможно, что пользователь перемещает QSlider одним пальцем и нажимает QPushButton другим. Сигналы, испускаемые этими виджетами, будут чередоваться.
• Рекурсия в цикле событий с помощью одного из методов exec() (например, QDialog::exec() или QMenu::exec()) в обработчике события QTouchEvent не поддерживается. Поскольку существует несколько получателей событий, рекурсия может вызвать проблемы, включая, но не ограничиваясь, потерянными событиями и неожиданной бесконечной рекурсией.
• QTouchEvents не зависят от захвата мыши mouse grab или активного всплывающего виджета active pop-up widget. Поведение 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(), которые для повышения производительности хранят только глобальные позиции в событии касания.