Тип 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(WheelEvent 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 : flags

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

По умолчанию это свойство установлено в PointerDevice.Mouse, чтобы реагировать только на события от реального колеса мыши.

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

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 Point и активно изменяет 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.

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

invertible : bool

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

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

margin : real

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

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

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

targetScaleMultiplier : вещественное

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

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

targetTransformAroundCursor : булево

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

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

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

canceled(EventPoint point)

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

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

grabChanged(GrabTransition transition, EventPoint point)

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

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

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

wheel(WheelEvent event)

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

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