Тип 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(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; в то время как фильтру событий нужно отфильтровать все QEvents всех типов, и тем самым он становится потенциальной узкой точкой передачи событий.

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

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

enabled : bool

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

grabPermissions : flags

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

По умолчанию 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, Элементом, в котором объявлен обработчик. Однако иногда бывает полезно установить target на другой Элемент, чтобы обрабатывать события внутри одного элемента, но изменять другой; или чтобы null, чтобы отключить стандартное поведение и сделать что-то другое вместо этого.

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

canceled(point)

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

grabChanged(transition, EventPoint point)

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

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