Класс QTouchEvent

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

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

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

Типы public

Функции public

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

Защищенные переменные

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

• 1 свойство, унаследованное от QEvent
• 1 статический public член, унаследованный от 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 содержит специальный флаг accept, указывающий, хочет ли получатель событие. По умолчанию, событие принимается. Вы должны вызвать 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 могут использоваться для включения или отключения автоматического синтезирования событий касания в события мыши и событий мыши в события касания.

Ограничения

• Как упоминалось выше, включение событий касания означает, что несколько виджетов могут получать события касания одновременно. В сочетании с обработкой QWidget::event() по умолчанию для QTouchEvents это обеспечивает большую гибкость при проектировании сенсорных пользовательских интерфейсов. Имейте в виду последствия. Например, возможно, пользователь перемещает 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 = ..., const QList<QTouchEvent::TouchPoint> &touchPoints = ...)

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