Тип QML WheelHandler

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

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

Свойства

• acceptedButtons : flags
• acceptedDevices : flags
• acceptedModifiers : flags
• acceptedPointerTypes : flags
• active : bool
• activeTimeout : real
• 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(point)
• grabChanged(transition, EventPoint point)
• wheel(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

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

activeTimeout : real

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

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

enabled : bool

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

grabPermissions : флаги

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

По умолчанию 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 : перечисление

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

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

[только для чтения] parent : 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, в котором объявлен обработчик. Однако иногда бывает полезно установить целевой элемент на другой элемент, чтобы обрабатывать события в одном элементе, но манипулировать другим; или для 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(point)

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

grabChanged(transition, EventPoint point)

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

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

wheel(event)

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