Тип QML WheelHandler

Обработчик колеса мыши. Подробнее...

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

Свойства

• acceptedButtons : flags
• acceptedDevices : flags
• acceptedModifiers : flags
• acceptedPointerTypes : flags
• active : bool
• activeTimeout : real
• cursorShape : Qt::CursorShape
• dragThreshold : int
• enabled : bool
• grabPermissions : flags
• invertible : bool
• margin : real
• orientation : перечисление
• parent : Item
• point : HandlerPoint
• property : string
• rotation : real
• rotationScale : real
• target : Item
• targetScaleMultiplier : real
• targetTransformAroundCursor : bool

Сигналы

• canceled(EventPoint point)
• grabChanged(GrabTransition transition, EventPoint point)
• wheel(PointerScrollEvent event)

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

WheelHandler — это обработчик, используемый для интерактивного изменения числового свойства Item по мере вращения пользователем колеса мыши. Как и другие обработчики ввода, по умолчанию он управляет своим target. Объявите property, чтобы указать, какое свойство целевого объекта будет изменяться:

import QtQuick 2.14

Rectangle {
    width: 170; height: 120
    color: "green"; antialiasing: true

    WheelHandler {
        property: "rotation"
        onWheel: (event)=> console.log("rotation", event.angleDelta.y,
                                       "scaled", rotation, "@", point.position,
                                       "=>", parent.rotation)
    }
}

BoundaryRule очень полезен в сочетании с WheelHandler (а также с другими обработчиками ввода) для объявления допустимого диапазона значений, которые может принимать свойство целевого объекта. Например, можно реализовать прокрутку, используя комбинацию WheelHandler и DragHandler для управления свойством y прокручиваемого Item при вращении колеса или перетаскивании элемента на сенсорном экране, а также BoundaryRule для ограничения диапазона перемещения сверху вниз:

import QtQuick 2.14
import Qt.labs.animation 1.0

Item {
    width: 320; height: 480
    Flow {
        id: content
        width: parent.width
        spacing: 2; padding: 2

        WheelHandler {
            orientation: Qt.Vertical
            property: "y"
            rotationScale: 15
            acceptedDevices: PointerDevice.Mouse | PointerDevice.TouchPad
            onActiveChanged: if (!active) ybr.returnToBounds()
        }

        DragHandler {
            xAxis.enabled: false
            onActiveChanged: if (!active) ybr.returnToBounds()
        }

        BoundaryRule on y {
            id: ybr
            minimum: content.parent.height - content.height
            maximum: 0
            minimumOvershoot: 400; maximumOvershoot: 400
            overshootFilter: BoundaryRule.Peak
        }

        Repeater {
            model: 1000
            Rectangle { color: "gray"; width: 10 + Math.random() * 100; height: 15 }
        }
    }
}

В противном случае, если property не установлен или target равен null, WheelHandler не будет автоматически ничего изменять; но свойство rotation может использоваться в привязке для изменения другого свойства, или вы можете реализовать onWheel и обработать событие колеса напрямую.

WheelHandler по умолчанию обрабатывает только вращающееся колесо мыши; это можно изменить, установив acceptedDevices.

См. также MouseArea и Flickable.

Документация по свойствам

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.Mouse, поэтому он реагирует только на события от физического колеса мыши.

WheelHandler может реагировать как на колесо мыши, так и на прокрутку тачпада, установив acceptedDevices в PointerDevice.Mouse | PointerDevice.TouchPad.

Примечание: Некоторые устройства без мыши (например, сенсорный планшет Wacom или тачпад ноутбука Linux) генерируют реальные события колеса от жестов. WheelHandler будет реагировать на эти события как на события колеса, даже если acceptedDevices остается установленным в значение по умолчанию.

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

activeTimeout : real

Время в секундах, после которого свойство active вернется к false , если больше событий колеса не поступает. По умолчанию 0.1 (100 мс).

Когда WheelHandler обрабатывает события, содержащие информацию о фазе прокрутки, такие как события от некоторых тачпадов, свойство active станет false как только будет получено событие с фазой Qt::ScrollEnd; в этом случае таймаут не нужен. Но обычная мышь с колесом не предоставляет фазу прокрутки: мышь не может определить, когда пользователь решил прекратить прокрутку, поэтому свойство active переходит в false по истечении этого времени.

См. также QWheelEvent::phase().

[с 5.15] 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.

[с 5.15] dragThreshold : int

Расстояние в пикселях, которое пользователь должен переместить точку события, чтобы оно обрабатывалось как жести жест перетаскивания.

Значение по умолчанию зависит от платформы и разрешения экрана. Его можно сбросить до значения по умолчанию, установив его в undefined. Поведение при начале жеста перетаскивания различается в разных обработчиках.

Это свойство было введено в Qt 5.15.

enabled : bool

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

grabPermissions : flags

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

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

invertible : bool

Обратить ли направление изменения свойства, если QQuickPointerScrollEvent::inverted имеет значение true. Значение по умолчанию — true.

Если операционная система имеет настройку «естественное прокручивание», которая приводит к прокрутке в том же направлении, что и движение пальца, то если это свойство установлено в true, а WheelHandler непосредственно задает свойство для target, направление движения будет соответствовать настройкам системы. Если это свойство установлено в false, он инвертирует rotation, так что направление движения всегда соответствует направлению движения пальца.

margin : real

Отступ за пределами границ элемента родитель, внутри которого точка события может активировать этот обработчик. Например, в PinchHandler, где target также является parent, полезно установить это значение как расстояние, по крайней мере, равное половине ширины типичного пальца пользователя, чтобы если parent был уменьшен до очень малого размера, жест pinch всё ещё был возможен. Или, если кнопка на основе TapHandler расположена около края экрана, ее можно использовать для соответствия закону Фиттса: реагировать на щелчки мыши на краю экрана, даже если кнопка визуально смещена от края на несколько пикселей.

Значение по умолчанию равно 0.

orientation : enum

Какое колесо реагировать. Значение по умолчанию — Qt.Vertical.

Не у каждой мыши есть колесо Horizontal; иногда оно эмулируется наклоном колеса вбок. Планшет обычно может генерировать вертикальные и горизонтальные события колеса.

[только для чтения] parent : Item

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

См. также target и QObject::parent().

[только для чтения] point : HandlerPoint

Точка события, которая в настоящее время обрабатывается. Когда никакая точка не обрабатывается, этот объект сбрасывается до значений по умолчанию (все координаты равны 0).

property : string

Свойство, которое должно быть изменено у target при повороте колеса мыши.

Значение по умолчанию — отсутствие свойства (пустая строка). Если свойство целевого объекта не изменяется автоматически, вы можете использовать привязки для реагирования на поворот колеса мыши произвольными способами.

Вы можете использовать колесо мыши для изменения любого числового свойства. Например, если property установлено в x, target будет перемещаться по горизонтали при повороте колеса. Следующие свойства имеют специальное поведение:

Изменение указанного свойства target всегда масштабируется с помощью rotationScale.

rotation : real

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

Положительное значение указывает, что колесо повернулось вверх/вправо; отрицательное значение указывает, что колесо повернулось вниз/влево.

Базовое колесо мыши работает шагами по 15 градусов.

Значение по умолчанию — 0 при запуске. Его можно программно изменить на любое значение в любое время. Значение будет корректироваться по мере поворота пользователем колеса мыши.

См. также orientation.

rotationScale : real

Масштабирование, применяемое к свойству rotation и к свойству property элемента target, если таковое имеется. Значение по умолчанию — 1, так что rotation будет измеряться в градусах поворота. Его можно задать отрицательным числом, чтобы инвертировать эффект направления поворота колеса мыши.

target : Item

Элемент, который будет изменять этот обработчик.

По умолчанию, он совпадает с parent, элементом, в котором объявлен обработчик. Однако, иногда может быть полезно установить цель на другой элемент, чтобы обрабатывать события внутри одного элемента, но изменять другой; или null, чтобы отключить стандартное поведение и сделать что-то другое вместо этого.

targetScaleMultiplier : real

Значение, на которое умножается масштаб целевого масштаба всякий раз, когда поворот изменяется на 15 градусов. Это актуально только при условии, что свойство равно "scale".

Значение scale будет умножено на targetScaleMultiplier ^{angleDelta * rotationScale / 15}. По умолчанию это 2 ^1/3, что означает, что если rotationScale остаётся по умолчанию, а колесо мыши вращается на один «клик» (15 градусов), целевой элемент будет масштабироваться приблизительно на 1.25; после трех «кликов» его размер удвоится или уменьшится в два раза, в зависимости от направления вращения колеса. Если вы хотите удваивать или уменьшать размер с каждым 2 щелчками колеса, установите это значение в 2 ^1/2 (1.4142). Если вы хотите, чтобы масштабирование происходило в обратном направлении по отношению к вращению колеса, установите rotationScale со значением меньше нуля.

targetTransformAroundCursor : bool

Определяет, должен ли целевой элемент автоматически перемещаться таким образом, чтобы он трансформировался вокруг позиции курсора мыши, в то время как свойство регулируется. По умолчанию, это true.

Если свойство установлено на "rotation" и targetTransformAroundCursor имеет значение true, то при вращении колеса целевой элемент будет вращаться на месте вокруг позиции курсора мыши. Если targetTransformAroundCursor имеет значение false, он будет вращаться вокруг transformOrigin вместо этого.

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

canceled(EventPoint point)

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

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

grabChanged(GrabTransition transition, EventPoint point)

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

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

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

wheel(PointerScrollEvent event)

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

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