Тип QML TapHandler

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

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

Свойства

• acceptedButtons : флаги
• acceptedDevices : флаги
• acceptedModifiers : флаги
• acceptedPointerTypes : флаги
• active : bool
• enabled : bool
• gesturePolicy : перечисление
• grabPermissions : флаги
• longPressThreshold : вещественное
• margin : вещественное
• parent : Item
• point : HandlerPoint
• pressed : bool
• tapCount : int
• target : Item
• timeHeld : вещественное

Сигналы

• 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.

Для жестов с несколькими нажатиями (двойное нажатие, тройное нажатие и т. д.) перемещение должно быть не более QPlatformTheme::MouseDoubleClickDistance для мыши и QPlatformTheme::TouchDoubleTapDistance для сенсорного ввода, а время между нажатиями не должно превышать QStyleHints::mouseDoubleClickInterval().

См. также MouseArea.

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

acceptedButtons : флаги

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

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

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

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

Примечание: Нажатие на сенсорном экране или нажатие стилусом на графическом планшете эмулирует нажатие левой кнопки мыши. Это поведение можно изменить с помощью acceptedDevices или acceptedPointerTypes.

acceptedDevices : флаги

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

По умолчанию это свойство установлено в PointerDevice.AllDevices. Если установить его в логическое ИЛИ комбинацию типов устройств, оно будет игнорировать события от несоответствующих устройств.

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

Item {
   TapHandler {
       acceptedDevices: PointerDevice.Mouse | PointerDevice.Stylus
       onTapped: console.log("clicked")
   }
   TapHandler {
       acceptedDevices: PointerDevice.TouchScreen
       onTapped: console.log("tapped")
   }
}

acceptedModifiers : флаги

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

Если это свойство установлено в Qt.KeyboardModifierMask (значение по умолчанию), то PointerHandler игнорирует клавиши модификаторов.

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

Item {
   TapHandler {
       acceptedModifiers: Qt.ControlModifier
       onTapped: console.log("control-tapped")
   }
   TapHandler {
       acceptedModifiers: Qt.NoModifier
       onTapped: console.log("tapped")
   }
}

acceptedPointerTypes : флаги

Типы указательных инструментов (палец, стилус, ластик и т. д.), которые могут активировать этот обработчик указателя.

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

enabled : bool

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

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

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

grabPermissions : флаги

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

target : Item

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

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

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

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

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

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

canceled(EventPoint point)

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

doubleTapped(EventPoint eventPoint)

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

Примечание: В момент излучения этого сигнала, point был сброшен (все координаты 0).

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

grabChanged(GrabTransition transition, EventPoint point)

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

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

longPressed()

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

singleTapped(EventPoint eventPoint)

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

Примечание: В момент излучения этого сигнала, point был сброшен (все координаты 0).

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

tapCountChanged()

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

tapped(EventPoint eventPoint)

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

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

import QtQuick 2.12

Rectangle {
    width: 100
    height: 100

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

Примечание: В момент излучения этого сигнала, point был сброшен (все координаты 0).