Тип 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 : строка
• 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 в %%%CODE_BLOCK_3%%.

Примечание: Некоторые устройства, не являющиеся мышами (например, сенсорный планшет 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

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

activeTimeout : real

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

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

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

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

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

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

orientation : перечисление

Которое колесо обрабатывать. По умолчанию Qt.Vertical.

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

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

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

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

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

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

property : строка

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

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

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

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

rotation : real

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

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

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

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

См. также orientation.

rotationScale : real

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

target : Item

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

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

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

grabChanged(GrabTransition transition, EventPoint point)

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

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

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

wheel(PointerScrollEvent event)

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

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