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

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

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

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

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

import QtQuick

Rectangle {
    id: button
    signal clicked
    property alias text: buttonLabel.text

    height: Math.max(Screen.pixelDensity * 7, buttonLabel.implicitHeight * 1.2)
    width: Math.max(Screen.pixelDensity * 11, buttonLabel.implicitWidth * 1.3)
    radius: 3
    property color dark: Qt.darker(palette.button, 1.3)
    gradient: Gradient {
        GradientStop { position: 0.0; color: tapHandler.pressed ? dark : palette.button }
        GradientStop { position: 1.0; color: dark }
    }

    TapHandler {
        id: tapHandler
        gesturePolicy: TapHandler.ReleaseWithinBounds
        onTapped: button.clicked()
    }

    Text {
        id: buttonLabel
        text: "Click Me"
        color: palette.buttonText
        anchors.centerIn: parent
    }
}

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

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

Это свойство было добавлено в 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, независимо от удерживаемого времени.

gesturePolicy также влияет на поведение захвата, как описано ниже.

grabPermissions : флаги

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

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

longPressThreshold : real

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

margin : real

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

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

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

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

canceled(EventPoint point)

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

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

[since 5.11] doubleTapped(EventPoint eventPoint, Qt::MouseButton button)

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

Примечание: Соответствующий обработчик — 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, Qt::MouseButton button)

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

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

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

tapCountChanged()

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

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

tapped(EventPoint eventPoint, Qt::MouseButton button)

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

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

import QtQuick

Rectangle {
    width: 100
    height: 100

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

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