Тип QML TapHandler

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

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

Свойства

• acceptedButtons : флаги
• acceptedDevices : флаги
• acceptedModifiers : флаги
• acceptedPointerTypes : флаги
• active : bool
• enabled : bool
• gesturePolicy : перечисление
• grabPermissions : флаги
• longPressThreshold : вещественное число
• margin : вещественное число
• parent : Item
• point : HandlerPoint
• pressed : bool
• tapCount : целое число
• 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.

Для жестов с несколькими нажатиями (двойное нажатие, тройное нажатие и т. д.) перемещение должно быть не более 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

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

enabled : bool

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

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

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

grabPermissions : флаги

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

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

longPressThreshold : real

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

margin : real

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

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

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

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

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

canceled(point)

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

doubleTapped(eventPoint)

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

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

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

grabChanged(transition, EventPoint point)

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

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

longPressed()

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

singleTapped(eventPoint)

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

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

Этот сигнал был представлен в 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)
    }
}

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