Тип QML PointHandler

Обработчик реакций на одну точку касания. Подробнее...

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

Свойства

• acceptedButtons : flags
• acceptedDevices : flags
• acceptedModifiers : flags
• acceptedPointerTypes : flags
• active : bool
• cursorShape : Qt::CursorShape
• dragThreshold : int
• enabled : bool
• grabPermissions : flags
• margin : real
• parent : Item
• point : HandlerPoint
• target : Item

Сигналы

• canceled(EventPoint point)
• grabChanged(GrabTransition transition, EventPoint point)

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

PointHandler можно использовать для отображения откликов на точку касания или положение мыши или для других реакций на события указателя.

При возникновении события нажатия каждый экземпляр PointHandler выбирает одну точку, которая ещё не «захвачена» в этот момент: если нажатие происходит в пределах границ PointerHandler::parent и ни один из других PointHandler в рамках той же области PointerHandler::parent ещё не захватил пассивный захват на этой точке, и если другие ограничения, такие как acceptedButtons, acceptedDevices и т. д., удовлетворены, он подходит, и PointHandler затем получает пассивный захват. Таким образом, PointerHandler::parent действует как эксклюзивная группа: может быть несколько экземпляров PointHandler, и набор нажатых точек будет распределен между ними. Каждый PointHandler, который выбрал точку для отслеживания, имеет свойство active true. Затем он продолжает отслеживать выбранную точку до отпускания: свойства point будут сохраняться актуальными. Любой элемент может привязаться к этим свойствам и тем самым отслеживать перемещения точки.

Будучи только пассивным захватом, он имеет возможность поддерживать независимый контроль всех перемещений. Пассивный захват нельзя украсть или переопределить даже при обнаружении других жестов и возникновении эксклюзивных захватов.

Если ваша цель – ортогональное наблюдение за точками событий, более старой альтернативой было QObject::installEventFilter(), но это никогда не было встроенной функцией QtQuick: требуется некоторый код C++, например, подкласс QQuickItem. PointHandler более эффективен, поскольку только события указателя будут передаваться ему в ходе обычной передачи событий в QQuickWindow, тогда как фильтру событий необходимо фильтровать все события QEvent всех типов, и тем самым он устанавливает себя как потенциальную узкую точку передачи событий.

Одно из возможных применений – добавить этот обработчик в прозрачный элемент, который находится поверх остальной сцены (за счёт высокого значения z), так что, когда точка нажимается, она передаётся этому элементу и его обработчикам в первую очередь, что обеспечивает возможность получить пассивный захват как можно раньше. Такой элемент (например, стекло над всем пользовательским интерфейсом) может быть удобным родителем для других элементов, которые визуализируют тип обратной связи, который должен всегда находиться поверх; аналогично, он может быть родителем для всплывающих окон, всплывающих подсказок, диалогов и т. д. Если он будет использоваться таким образом, для вашего main.cpp может быть полезно использовать QQmlContext::setContextProperty(), чтобы сделать «стеклянный поддон» доступным по идентификатору для всего пользовательского интерфейса, так что другие элементы и PointHandler могут быть переведены в его родительское подчинение.

import QtQuick 2.12
import QtQuick.Window 2.2

Window {
    width: 480
    height: 320
    visible: true

    Item {
        id: glassPane
        z: 10000
        anchors.fill: parent

        PointHandler {
            id: handler
            acceptedDevices: PointerDevice.TouchScreen | PointerDevice.TouchPad
            target: Rectangle {
                parent: glassPane
                color: "red"
                visible: handler.active
                x: handler.point.position.x - width / 2
                y: handler.point.position.y - height / 2
                width: 20; height: width; radius: width / 2
            }
        }
    }
}

Как и все обработчики ввода, у PointHandler есть свойство target, которое может быть удобно использовано для размещения элемента отслеживания точек; но PointHandler не будет автоматически управлять элементом target каким-либо образом. Вам нужно использовать привязки, чтобы он реагировал на point.

Примечание: В macOS PointHandler по умолчанию не реагирует на трекпад. Это связано с тем, что macOS может предоставлять либо распознавание жестов нативными средствами, либо сырые точки касания, но не оба одновременно. Мы предпочитаем использовать событие жеста нативного уровня в PinchHandler, поэтому не хотим отключать его, включив касания. Однако MultiPointTouchArea включает касания, тем самым отключая распознавание жестов нативного уровня в окне; поэтому это альтернатива, если вам нужно реагировать только на все точки касания, но вам не требуется гладкий опыт распознавания жестов нативного уровня.

См. также MultiPointTouchArea.

Документация по свойствам

acceptedButtons : flags

Кнопки мыши, которые могут активировать этот обработчик указателя.

По умолчанию это свойство устанавливается в Qt.LeftButton. Оно может быть установлено в комбинацию клавиш мыши с «ИЛИ», и будет игнорировать события от других кнопок.

Например, управление может реагировать на щелчки левой и правой кнопкой мыши по-разному, с помощью двух обработчиков:

Item {
    TapHandler {
        onTapped: console.log("left clicked")
    }
    TapHandler {
        acceptedButtons: Qt.RightButton
        onTapped: console.log("right clicked")
    }
}

Примечание: Нажатие на сенсорный экран или нажатие стилусом на графический планшет эмулирует нажатие левой кнопки мыши. Это поведение может быть изменено с помощью acceptedDevices или acceptedPointerTypes.

acceptedDevices : flags

Типы указательных устройств, которые могут активировать этот обработчик указателя.

По умолчанию это свойство устанавливается в PointerDevice.AllDevices. Если установить комбинацию типов устройств с «ИЛИ», события от устройств, не соответствующих типу, будут игнорироваться.

Например, управление может реагировать на нажатия мышью и стилусом одним способом, а на нажатия на сенсорном экране – другим, с помощью двух обработчиков:

Item {
   TapHandler {
       acceptedDevices: PointerDevice.Mouse | PointerDevice.Stylus
       onTapped: console.log("clicked")
   }
   TapHandler {
       acceptedDevices: PointerDevice.TouchScreen
       onTapped: console.log("tapped")
   }
}

acceptedModifiers : flags

Если это свойство установлено, для реакции на события указателя потребуются указанные клавиши модификаторов, а в противном случае они будут игнорироваться.

Если это свойство установлено в Qt.KeyboardModifierMask (значение по умолчанию), то PointerHandler игнорирует клавиши модификаторов.

Например, элемент Item может иметь два обработчика одного типа, один из которых активируется только при нажатии необходимых клавиш модификаторов:

Item {
   TapHandler {
       acceptedModifiers: Qt.ControlModifier
       onTapped: console.log("control-tapped")
   }
   TapHandler {
       acceptedModifiers: Qt.NoModifier
       onTapped: console.log("tapped")
   }
}

Если вы установите acceptedModifiers в комбинацию клавиш модификаторов с «ИЛИ», это означает, что все эти модификаторы должны быть нажаты для активации обработчика:

Item {
   TapHandler {
       acceptedModifiers: Qt.ControlModifier | Qt.AltModifier | Qt.ShiftModifier
       onTapped: console.log("control-alt-shift-tapped")
   }
}

Доступные модификаторы следующие:

Если вам нужно даже более сложное поведение, чем может быть достигнуто с помощью комбинаций нескольких обработчиков с несколькими флагами модификаторов, вы можете проверить модификаторы в JavaScript-коде:

Item {
    TapHandler {
        onTapped:
            switch (point.modifiers) {
            case Qt.ControlModifier | Qt.AltModifier:
                console.log("CTRL+ALT");
                break;
            case Qt.ControlModifier | Qt.AltModifier | Qt.MetaModifier:
                console.log("CTRL+META+ALT");
                break;
            default:
                console.log("other modifiers", point.modifiers);
                break;
            }
    }
}

См. также Qt::KeyboardModifier.

acceptedPointerTypes : flags

Типы указательных устройств (палец, стилус, ластик и т. д.), которые могут активировать этот обработчик указателя.

По умолчанию это свойство устанавливается в PointerDevice.AllPointerTypes. Если установить комбинацию типов устройств с «ИЛИ», события от устройств, не соответствующих типу, будут игнорироваться.

Например, управление может реагировать на нажатия мышью, касанием и стилусом каким-то образом, но удаляет само себя, если нажатие выполнено инструментом ластика на графическом планшете, с помощью двух обработчиков:

Rectangle {
   id: rect
   TapHandler {
       acceptedPointerTypes: PointerDevice.GenericPointer | PointerDevice.Finger | PointerDevice.Pen
       onTapped: console.log("clicked")
   }
   TapHandler {
       acceptedPointerTypes: PointerDevice.Eraser
       onTapped: rect.destroy()
   }
}

[только для чтения] active : bool

Это значение истинно, когда этот обработчик ввода принял на себя исключительную ответственность за обработку одной или нескольких EventPoints, успешно получив эксклюзивный захват этих точек. Это означает, что он сохраняет свои свойства актуальными в соответствии с движениями этих точек событий и активно управляет своим target (если таковой имеется).

[since 5.15] cursorShape : Qt::CursorShape

Это свойство определяет форму курсора, которая будет отображаться, когда указатель мыши наведён на элемент родитель, при условии, что свойство active равно true.

Доступные формы курсора:

• Qt.ArrowCursor
• Qt.UpArrowCursor
• Qt.CrossCursor
• Qt.WaitCursor
• Qt.IBeamCursor
• Qt.SizeVerCursor
• Qt.SizeHorCursor
• Qt.SizeBDiagCursor
• Qt.SizeFDiagCursor
• Qt.SizeAllCursor
• Qt.BlankCursor
• Qt.SplitVCursor
• Qt.SplitHCursor
• Qt.PointingHandCursor
• Qt.ForbiddenCursor
• Qt.WhatsThisCursor
• Qt.BusyCursor
• Qt.OpenHandCursor
• Qt.ClosedHandCursor
• Qt.DragCopyCursor
• Qt.DragMoveCursor
• Qt.DragLinkCursor

Значение по умолчанию не задано, что позволяет отображать курсор элемента родителя parent. Это свойство можно сбросить до исходного состояния, присвоив ему значение undefined.

Примечание: Если это свойство не задано или ему присвоено значение undefined, при чтении его значения будет возвращено значение Qt.ArrowCursor.

Это свойство было добавлено в Qt 5.15.

См. также Qt::CursorShape, QQuickItem::cursor() и HoverHandler::cursorShape.

[since 5.15] dragThreshold : int

Расстояние в пикселях, на которое пользователь должен переместить точку события, чтобы оно было обработано как жесты перетаскивания.

Значение по умолчанию зависит от платформы и разрешения экрана. Его можно сбросить до значения по умолчанию, установив его в undefined. Поведение при начале жеста перетаскивания различно в разных обработчиках.

Это свойство было добавлено в Qt 5.15.

enabled : bool

Если обработчик PointerHandler отключен, он будет отклонять все события, и не будет генерироваться никаких сигналов.

grabPermissions : flags

Это свойство определяет разрешения, когда логика данного обработчика решает захватить эксклюзивный захват, или когда его просят одобрить захват или отмену захвата другим обработчиком.

Значение по умолчанию PointerHandler.CanTakeOverFromItems | PointerHandler.CanTakeOverFromHandlersOfDifferentType | PointerHandler.ApprovesTakeOverByAnything, что позволяет большинству сценариев захвата, но избегает, например, конфликтов между двумя PinchHandlers за те же точки касания.

margin : real

Отступ за пределами границ элемента родитель, в пределах которого точка события может активировать этот обработчик. Например, в PinchHandler, где target также является parent, полезно установить это значение на расстояние, по меньшей мере, половины ширины типичного пальца пользователя, чтобы, если parent был масштабирован до очень маленького размера, жест щипка всё ещё был возможен. Или, если кнопка на основе TapHandler размещена около края экрана, можно использовать это, чтобы соответствовать закону Фиттса: реагировать на щелчки мыши на краю экрана, даже если кнопка визуально отнесена от края на несколько пикселей.

Значение по умолчанию равно 0.

[только для чтения] parent : Item

Элемент Item, который является областью действия обработчика; элемент, в котором он был объявлен. Обработчик будет обрабатывать события от имени этого элемента, что означает, что событие указателя важно, если хотя бы одна из его точек событий находится внутри области элемента. Изначально target() такое же, но оно может быть переназначено.

См. также target и QObject::parent().

[только для чтения] point : HandlerPoint

Точка события, которая в настоящее время обрабатывается. Когда ни одна точка не обрабатывается, этот объект сбрасывается до значений по умолчанию (все координаты равны 0).

target : Item

Элемент Item, который будет изменять этот обработчик.

По умолчанию он такой же, как parent, элемент, в котором объявлен обработчик. Однако иногда может быть полезно установить целевой объект на другой элемент, чтобы обрабатывать события в одном элементе, но изменять другой; или null, чтобы отключить стандартное поведение и сделать что-то другое вместо этого.

Документация сигналов

canceled(EventPoint point)

Если этот обработчик уже захватил указанную точку point, этот сигнал генерируется, когда захват похищен другим обработчиком указателя или элементом.

Примечание: Соответствующий обработчик onCanceled.

grabChanged(GrabTransition transition, EventPoint point)

Этот сигнал генерируется, когда захват каким-либо образом изменился, что важно для этого обработчика.

transition (глагол) указывает, что произошло. point (объект) — это точка, которая была захвачена или освобождена.

Примечание: Соответствующий обработчик onGrabChanged.