Тип 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: 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 в PointerDevice.Mouse | PointerDevice.TouchPad.

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

activeTimeout : real

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

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

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 отключен, он отклонит все события, и никакие сигналы не будут отправлены.

grabPermissions : flags

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

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

invertible : bool

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

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

margin : real

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

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

rotation : real

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

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

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

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

См. также orientation.

rotationScale : real

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

target : Item

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

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

targetScaleMultiplier : real

Величина, на которую масштаб scale элемента target умножается всякий раз, когда свойство rotation изменяется на 15 градусов. Это актуально только тогда, когда свойство property равно "scale".

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

targetTransformAroundCursor : bool

Указывает, следует ли автоматически перемещать элемент target таким образом, чтобы он преобразовывался вокруг позиции курсора мыши, пока свойство property изменяется. Значение по умолчанию — true.

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

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

canceled(EventPoint point)

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

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

grabChanged(GrabTransition transition, EventPoint point)

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

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

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

wheel(PointerScrollEvent event)

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

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