Класс 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 описывает различные состояния, которые может иметь точка касания.

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

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

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

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

[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

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