Тип 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(), чтобы сделать «стеклянную панель» доступной по идентификатору для всего пользовательского интерфейса, чтобы другие элементы и 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, которое может использоваться в качестве удобного места для размещения элемента отслеживания точки; но 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. Если вы установите его в OR-сочетание типов устройств, он будет игнорировать события от несоответствующих устройств.

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

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 в OR-сочетание клавиш модификаторов, это означает, что все эти модификаторы должны быть нажаты для активации обработчика:

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. Если вы установите его в OR-сочетание типов устройств, он будет игнорировать события от несоответствующих событий.

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

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

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

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

Примечание: Если это свойство не задано или установлено в undefined, при чтении значения оно вернёт Qt.ArrowCursor.

Это свойство было добавлено в Qt 5.15.

См. также Qt::CursorShape, QQuickItem::cursor() и HoverHandler::cursorShape.

dragThreshold : int

Расстояние в пикселях, которое пользователь должен переместить точку события, чтобы оно считалось жестом перетаскивания.

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

Это свойство было добавлено в Qt 5.15.

enabled : bool

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

grabPermissions : flags

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

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

margin : real

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

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

[read-only] parent : Item

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

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

[read-only] point : HandlerPoint

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

target : Item

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

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

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

canceled(EventPoint point)

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

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

grabChanged(GrabTransition transition, EventPoint point)

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

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

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