Тип QML TapHandler

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

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

Свойства

• acceptedButtons : флаги
• acceptedDevices : флаги
• acceptedModifiers : флаги
• acceptedPointerTypes : флаги
• active : bool
• cursorShape : Qt::CursorShape
• dragThreshold : int
• enabled : bool
• gesturePolicy : перечисление
• grabPermissions : флаги
• 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 : флаги

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

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

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

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.

[только для чтения] 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 : вещественное

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

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

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

canceled(EventPoint point)

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

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

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.

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: console.log("tapped", eventPoint.event.device.name,
                              "button", eventPoint.event.button,
                              "@", eventPoint.scenePosition)
    }
}

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