Тип 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

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

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

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

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