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

См. также MultiPointTouchArea.

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

acceptedButtons : flags

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

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

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

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

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.

[read-only] 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 (если он есть).

[since 5.15] cursorShape : Qt::CursorShape

Это свойство задаёт форму курсора, который будет отображаться, когда мышь находится над элементом parent, при этом свойство 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

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

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

margin : real

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

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

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

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

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

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

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

target : Item

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

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

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

canceled(EventPoint point)

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

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

grabChanged(GrabTransition transition, EventPoint point)

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

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

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