Класс QTouchEvent

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

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

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

Типы

Публичные функции

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

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

• 1 свойство, унаследованное от QEvent
• 1 статический публичный член, унаследованный от 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 для включения или выключения автоматического синтеза событий касания в события мыши и событий мыши в события касания.

Ограничения

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

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

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

QTouchEvent::QTouchEvent(QEvent::Type eventType, QTouchDevice *device = Q_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 представляют собой текущие состояния точек касания и модификаторы клавиатуры на момент события.

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()), так как для повышения производительности глобальные координаты хранятся только в событии касания.