Тип QML PointHandler

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

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

Свойства

• acceptedButtons : flags
• acceptedDevices : flags
• acceptedModifiers : flags
• acceptedPointerTypes : flags
• active : bool
• 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, поэтому мы не хотим его отключать, включив touch. Однако MultiPointTouchArea включает touch, тем самым отключая распознавание нативных жестов во всем окне; поэтому это альтернатива, если вы хотите реагировать только на все точки касания, но не требуете плавного опыта распознавания нативных жестов.

См. также 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")
   }
}

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

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

enabled : bool

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

grabPermissions : flags

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

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

margin : real

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

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

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

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

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

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

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

target : Item

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

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

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

canceled(EventPoint point)

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

grabChanged(GrabTransition transition, EventPoint point)

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

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