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

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

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

[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

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