Тип 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(point)
• doubleTapped(eventPoint)
• grabChanged(transition, EventPoint point)
• longPressed()
• singleTapped(eventPoint)
• tapCountChanged()
• tapped(eventPoint)

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

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

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

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

Для многократных жестов (двойное нажатие, тройное нажатие и т. д.) перемещение должно не превышать QStyleHints::mouseDoubleClickDistance() для мыши и QStyleHints::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")
   }
}

Если вы установите 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 : флаги

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

По умолчанию это свойство устанавливается в 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 (если таковой имеется).

enabled : bool

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

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

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

grabPermissions : flags

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

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

longPressThreshold : real

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

margin : real

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

[только для чтения] timeHeld : real

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

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

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

canceled(point)

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

doubleTapped(eventPoint)

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

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

grabChanged(transition, EventPoint point)

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

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

longPressed()

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

singleTapped(eventPoint)

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

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

tapCountChanged()

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

tapped(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)
    }
}