Тип QML TapHandler

Обработчик нажатий и щелчков. Подробнее...

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

Свойства

• acceptedButtons : flags
• acceptedDevices : flags
• acceptedModifiers : flags
• acceptedPointerTypes : flags
• active : bool
• cursorShape : Qt::CursorShape
• dragThreshold : int
• enabled : bool
• gesturePolicy : перечисление
• grabPermissions : flags
• longPressThreshold : real
• margin : real
• parent : Item
• point : HandlerPoint
• pressed : bool
• tapCount : int
• target : Item
• timeHeld : real

Сигналы

• canceled(EventPoint point)
• doubleTapped(EventPoint eventPoint)
• grabChanged(GrabTransition transition, EventPoint point)
• longPressed()
• singleTapped(EventPoint eventPoint)
• tapCountChanged()
• tapped(EventPoint eventPoint)

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

TapHandler — это обработчик нажатий на сенсорном экране или щелчков мышью.

Обнаружение корректного жеста нажатия зависит от gesturePolicy. Значение по умолчанию — DragThreshold, которое требует, чтобы нажатие и отпускание были близки друг к другу как по времени, так и по месту. В этом случае DragHandler может работать только с пассивным захватом, и, следовательно, не мешает доставке событий другим элементам или обработчикам ввода. Поэтому значение по умолчанию для gesturePolicy полезно, когда вы хотите изменить поведение существующего элемента управления или элемента, добавив TapHandler с привязками и/или JavaScript-обработчиками.

Обратите внимание, что кнопки (такие как QPushButton) часто реализуются так, чтобы не заботиться о том, произошли ли нажатие и отпускание близко друг к другу: если вы нажимаете кнопку, а затем передумаете, вам нужно переместить указатель за пределы кнопки, чтобы отменить щелчок. В этом случае установите gesturePolicy в TapHandler.ReleaseWithinBounds.

Для многократных нажатий (двойное нажатие, тройное нажатие и т.д.) расстояние между нажатиями не должно превышать QStyleHints::mouseDoubleClickDistance() для мыши и QStyleHints::touchDoubleTapDistance() для сенсорного ввода, а интервал между нажатиями не должен превышать QStyleHints::mouseDoubleClickInterval().

См. также MouseArea.

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

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

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

[с версии 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.

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

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

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

[since 5.15] dragThreshold : int

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

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

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

enabled : bool

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

gesturePolicy : перечисление

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

grabPermissions : флаги

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

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

longPressThreshold : вещественное

Время в секундах, которое точка события должна быть нажата, чтобы вызвать жест длительного нажатия и испустить сигнал longPressed(). Если точка отпущена до истечения этого временного ограничения, нажатие может быть обнаружено, если ограничение gesturePolicy удовлетворено. Значение по умолчанию — QStyleHints::mousePressAndHoldInterval(), преобразованное в секунды.

margin : вещественное

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

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

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

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

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

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

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

[только для чтения] pressed : bool

Содержит значение true, когда точка мыши или касания нажата, и любое перемещение с момента нажатия соответствует текущей gesturePolicy. Когда точка события отпущена или политика нарушена, pressed изменится на false.

[только для чтения] tapCount : int

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

Rectangle {
    width: 100; height: 30
    signal tripleTap
    TapHandler {
        acceptedButtons: Qt.AllButtons
        onTapped: if (tapCount == 3) tripleTap()
    }
}

target : Item

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

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

[только для чтения] timeHeld : вещественное

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

Значение меньше нуля означает, что ни одна точка не удерживается внутри элемента Item этого обработчика.

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

canceled(EventPoint point)

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

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

[since 5.11] doubleTapped(EventPoint eventPoint)

Этот сигнал излучается, когда элемент parent дважды нажаты в короткий промежуток времени (QStyleHints::mouseDoubleClickInterval()) и расстоянии (QStyleHints::mouseDoubleClickDistance() или QStyleHints::touchDoubleTapDistance()). Этот сигнал всегда возникает после singleTapped, tapped и tapCountChanged. Параметр сигнала eventPoint содержит информацию из события отпускания о точке, которая была нажата.

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

Этот сигнал был представлен в Qt 5.11.

grabChanged(GrabTransition transition, EventPoint point)

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

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

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

longPressed()

Этот сигнал излучается, когда элемент parent нажат и удерживается в течение периода времени, превышающего longPressThreshold. То есть, если вы нажимаете и удерживаете точку касания или кнопку, а любое движение не превышает порога перетаскивания, то сигнал longPressed будет излучен в тот момент, когда timeHeld превысит longPressThreshold.

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

[since 5.11] singleTapped(EventPoint eventPoint)

Этот сигнал излучается, когда элемент parent нажат один раз. Через некоторое время, превышающее QStyleHints::mouseDoubleClickInterval, его можно нажать снова; но если время до следующего нажатия меньше, tapCount увеличится. Параметр сигнала eventPoint содержит информацию из события отпускания о точке, которая была нажата.

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

Этот сигнал был представлен в Qt 5.11.

tapCountChanged()

Этот сигнал излучается, когда элемент parent нажат один или несколько раз (в течение заданного интервала времени и расстояния) и когда текущее значение tapCount отличается от предыдущего значения tapCount.

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

tapped(EventPoint eventPoint)

Этот сигнал излучается каждый раз, когда элемент parent нажат.

То есть, если вы нажимаете и отпускаете точку касания или кнопку в течение периода времени меньше, чем longPressThreshold, а любое движение не превышает порога перетаскивания, то сигнал tapped будет излучен в момент отпускания. Параметр сигнала eventPoint содержит информацию из события отпускания о точке, которая была нажата:

import QtQuick 2.12

Rectangle {
    width: 100
    height: 100

    TapHandler {
        acceptedButtons: Qt.LeftButton | Qt.RightButton
        onTapped: (eventPoint)=> console.log("tapped", eventPoint.event.device.name,
                                             "button", eventPoint.event.button,
                                             "@", eventPoint.scenePosition)
    }
}

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