Тип QML PointHandler

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

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

Свойства

• acceptedButtons : flags
• acceptedDevices : flags
• acceptedModifiers : flags
• acceptedPointerTypes : flags
• active : bool
• cursorShape : Qt::CursorShape
• dragThreshold : int
• enabled : bool
• grabPermissions : flags
• margin : real
• родитель : 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; тогда как фильтру событий необходимо фильтровать все QEvents всех типов, и тем самым он устанавливает себя как потенциальную узкую горловину передачи событий.

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