Qt включает в себя каркас для программирования жестов, который даёт возможность образовывать жесты из серий событий, независимо от используемых методов ввода информации. Жестом может быть особое перемещение мыши, действие с сенсорным экраном или серия событий из некоторых других источников. Тип ввода информации, интерпретация жеста и принятое действие выбирается разработчиком.

Краткий обзор

QGesture - главный класс в каркасе по работе с жестами в Qt, предоставляющий контейнер для информации о жестах, совершаемых пользователем. QGesture делает видимыми свойства, которые дают полную информацию, общую для всех жестов, и могут быть расширены для предоставления дополнительной информации связанной с жестами. Простые жесты панорамирования (panning), сжатия (pinching) и удара (swiping) представляются специализированными классами: QPanGesture, QPinchGesture и QSwipeGesture.

Разработчики могут также реализовать новые жесты создавая подклассы и расширяя класс QGestureRecognizer. Добавление поддержки для нового жеста приводит к реализации кода для распознания жеста в событиях ввода информации. Это описывается в разделе Создание своего распознавателя жестов.

Использование стандартных жестов с виджетами

Жесты можно активировать для экземпляров подклассов QWidget и QGraphicsObject. Объект, который принимает ввод жеста, упоминается в документации как объект-приёмник.

Чтобы разрешить жест для объекта-приёмника, вызовите его функцию QWidget::grabGesture() или QGraphicsObject::grabGesture() с аргументом, описывающим требуемый тип жеста. Стандартные типы определены в перечислении Qt::GestureType и включают в себя многие широко применяемые жесты.

     grabGesture(Qt::PanGesture);
     grabGesture(Qt::PinchGesture);
     grabGesture(Qt::SwipeGesture);

В выше приведённом коде жесты устанавливается в конструкторе самого объекта-приёмника.

Обработка событий

Когда пользователь совершает жест, события QGestureEvent будут доставлены объекту-приёмнику и могут быть обработаны переопределённой функцией-обработчиком QWidget::event() для виджетов или QGraphicsItem::sceneEvent() для графических объектов.

Так как один объект-приёмник может быть подписан на более чем один тип жестов, то QGestureEvent может содержать более одного QGesture, указывая сколько возможных жестов активны в одно и то же время. Затем в виджете определятся, как обрабатывать это множество жестов и выбрать те, которые могут быть отменены в пользу других.

К каждому жесту QGesture, содержащемуся внутри объекта QGestureEvent, по отдельности или ко всем вместе может быть применена функция accepted() или ignored(). Кроме того, вы можете запросить объекты данных отдельного QGesture (состояние) используя несколько геттеров.

Стандартная процедура для обработки события

QGesture по умолчанию принимается когда достигает вашего виджета. Однако, будет правильным всегда явно принимать или отклонять жест. Основное правило заключается в том, что если вы приняли жест, то вы его используете. Если вы его проигнорировали, то он вам не интересен. Игнорирование жеста может означать, что он предназначен другому объекту-приёмнику, или он будет отклонён.

Каждый жест QGesture обладает несколькими состояниями, через которые он проходит; имеется хорошо описанный способ изменения состояния, обычно пользовательский ввод приводит к изменениям состояния (например, начиная и останавливая взаимодействие), но виджет также может вызвать изменение состояния.

В начале отдельный QGesture, доставленный в виджет или графический элемент, находится в состоянии Qt::GestureStarted. Способ обработки жеста в этой точке оказывает воздействие на то как вы будете взаимодействовать с ним позднее.

• Принятие жеста означает, что виджет реагирует на жест и следующие жесты будут отслеживаться с помощью Qt::GestureUpdatedstate.
• Игнорирование жеста будет означать, что жест никогда больше не будет предложен снова. Он будет предложен родительскому виджету или элементу.
• Вызов setGestureCancelPolicy() на жесте когда она находится в начальном состоянии и является принятым, может вызвать отмену других жестов.

Использование QGesture::CancelAllInContext для отмены жеста вызовет отмену всех жестов, в любом состоянии, пока они не будут явно приняты. Это означает, что активные жесты на дочерних виджетам будут отменены. Это также означает, что жесты, доставленные в некоторых QGestureEvent, будут отменены, если виджет их проигнорировал. Это может быть полезно для фильтрации всех жестов за исключением одного, интересного вам.

Пример обработки события

Для удобства, Пример "Image Gestures" переопределяет основную функцию-обработчик event() и делегирует события жестов специализированной функции gestureEvent():

 bool ImageWidget::event(QEvent *event)
 {
     if (event->type() == QEvent::Gesture)
         return gestureEvent(static_cast<QGestureEvent*>(event));
     return QWidget::event(event);
 }

События жестов, доставленные в объект-приёмник, могут быть изучены по отдельности и соответственно обрабатываются:

 bool ImageWidget::gestureEvent(QGestureEvent *event)
 {
     if (QGesture *swipe = event->gesture(Qt::SwipeGesture))
         swipeTriggered(static_cast<QSwipeGesture *>(swipe));
     else if (QGesture *pan = event->gesture(Qt::PanGesture))
         panTriggered(static_cast<QPanGesture *>(pan));
     if (QGesture *pinch = event->gesture(Qt::PinchGesture))
         pinchTriggered(static_cast<QPinchGesture *>(pinch));
     return true;
 }

Реакция на жест - просто вопрос получения объекта QGesture, доставленного в QGestureEvent, отправленного в объект-приёмник и изучения содержащейся в нём информации.

 void ImageWidget::swipeTriggered(QSwipeGesture *gesture)
 {
     if (gesture->state() == Qt::GestureFinished) {
         if (gesture->horizontalDirection() == QSwipeGesture::Left
             || gesture->verticalDirection() == QSwipeGesture::Up)
             goPrevImage();
         else
             goNextImage();
         update();
     }
 }

Здесь мы изучаем направление, в котором пользователь ударяет виджет и соответственно модифицируем его содержимое.

Создание своего распознавателя жеста

Добавление поддержки нового жеста приводит к созданию и регистрации нового распознавателя жеста. В зависимости от обстоятельств процесс распознавания жеста может привести также к созданию нового объекта жеста.

Для создания нового распознавателя, вам нужно создать подкласс QGestureRecognizer чтобы создать класс пользовательского распознавателя. Имеется одна виртуальная функция, которую вы можете переопределить, и две другие, которые можно переопределить если потребуется.

Фильтрация входных событий

Функция recognize() может быть переопределена. Эта функция обрабатывает и фильтрует входящие события ввода информации для объектов-приёмников и определяет, соответствуют ли они или не соответствуют жесту, который ищет распознаватель.

Хотя логика распознавания жестов реализована в этой функции, возможно используя основанный на перечислениях Qt::GestureState конечный автомат, вы можете сохранить постоянную информацию о состоянии процесса распознавания в доставленном объекте QGesture.

Ваша функция recognize() должна возвращать значение QGestureRecognizer::Result, которое указывает состояние распознавания для заданного жеста и объекта-приёмника. Этим определяется, будет ли событие доставлено объекту-приёмнику.

Пользовательские жесты

Если вы выбрали представление жеста пользовательским подклассом QGesture, вам нужно переопределить функцию create() для создания экземпляров вашего класса жеста вместо стандартных экземпляров QGesture. В качестве альтернативы, вы можете захотеть использовать стандартные экземпляры QGesture, но добавить к ним дополнительные динамические свойства для изображения определённых деталей жеста, который вы хотите обработать.

Сброс жестов в исходное положение

Если вы используете объекты жестов, которые нужно сбросить или иным образом специально обработать, когда жест отменяется, вам нужно переопределить функцию reset() для выполнения этих специальных задач.

Обратите внимание на то, что объекты QGesture создаются только однажды для каждого сочетания объекта-приёмника и типа жеста, и они могут быть повторно использованы каждый раз, когда пользователь пытается выполнить жест одного и того же типа на объекте-приёмнике. В результате, это может быть полезно для переопределения функции reset() для очистки после каждой предыдущей попытки распознавания жеста.

Использование нового распознавателя жеста

Чтобы использовать распознаватель жестов создаём экземпляр вашего подкласса QGestureRecognizer, и регистрируем его вместе с приложением с помощью QGestureRecognizer::registerRecognizer(). Распознаватель для заданного типа жестов можно удалить с помощью QGestureRecognizer::unregisterRecognizer().

Дополнительные материалы

Пример "Image Gestures" показывает, как активировать жесты для виджета в приложении простого просмотрщика изображений.