Тип QML PointHandler

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

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

Свойства

• acceptedButtons : флаги
• acceptedDevices : флаги
• acceptedModifiers : флаги
• acceptedPointerTypes : флаги
• active : bool
• enabled : bool
• grabPermissions : флаги
• margin : вещественное число
• parent : Item
• point : HandlerPoint
• target : Item

Сигналы

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

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

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

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

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

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

Один из возможных вариантов использования — добавить этот обработчик в прозрачный Item, который находится поверх остальной сцены (имея высокое значение z), так что при новом нажатии на точку она будет сначала доставлена этому Item и его обработчикам, что даст возможность захватить пассивную блокировку как можно раньше. Такой элемент (например, стекло над всем пользовательским интерфейсом) может быть удобным родителем для других Item, которые визуализируют тот тип реактивной обратной связи, которая всегда должна быть сверху; аналогичным образом он может быть родителем всплывающих окон, всплывающих окон, диалоговых окон и т. д. Если он будет использоваться таким образом, для вашей main.cpp может быть полезно использовать QQmlContext::setContextProperty(), чтобы сделать «стеклянную панель» доступной по идентификатору для всего пользовательского интерфейса, чтобы другие Items и 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, которое можно использовать в качестве удобного места для размещения Item отслеживания точки; но PointHandler не будет автоматически манипулировать target элементом каким-либо образом. Вам необходимо использовать привязки, чтобы заставить его реагировать на point.

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

См. также MultiPointTouchArea.

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

acceptedButtons : флаги

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

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

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

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

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

acceptedDevices : флаги

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

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

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

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

acceptedModifiers : флаги

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

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

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

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

acceptedPointerTypes : флаги

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

По умолчанию это свойство установлено в 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, успешно захватив эксклюзивный захват этих точек. Это означает, что он поддерживает актуальность своих свойств в соответствии с перемещениями этих Event Points и активно манипулирует своим target (если таковой имеется).

enabled : bool

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

grabPermissions : флаги

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

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

margin : real

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

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

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

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

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

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

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

target : Item

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

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

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

canceled(point)

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

grabChanged(transition, EventPoint point)

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

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