Класс QTouchEvent

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

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

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

Открытые типы

Открытые функции

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

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

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