Тип QML DragHandler

Обработчик перетаскивания. Подробнее...

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

Свойства

• acceptedButtons : флаги
• acceptedDevices : флаги
• acceptedModifiers : флаги
• acceptedPointerTypes : флаги
• active : bool
• cursorShape : Qt::CursorShape
• dragThreshold : int
• enabled : bool
• grabPermissions : флаги
• margin : real
• parent : Item
• target : Item
• translation : QVector2D
• xAxis
  • xAxis.enabled : bool
  • xAxis.maximum : real
  • xAxis.minimum : real
• yAxis
  • yAxis.enabled : bool
  • yAxis.maximum : real
  • yAxis.minimum : real

Сигналы

• canceled(EventPoint point)
• grabChanged(GrabTransition transition, EventPoint point)

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

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

import QtQuick 2.12

Rectangle {
    width: 100
    height: 100
    color: "lightsteelblue"
    DragHandler { }
}

Он имеет свойства для ограничения диапазона перетаскивания.

Если он объявлен в одном элементе Item, но ему назначен другой target, то он обрабатывает события в пределах границ элемента parent, но управляет элементом target вместо этого:

import QtQuick 2.12

Item {
    width: 640
    height: 480

    Rectangle {
        id: feedback
        border.color: "red"
        width: Math.max(10, handler.centroid.ellipseDiameters.width)
        height: Math.max(10, handler.centroid.ellipseDiameters.height)
        radius: Math.max(width, height) / 2
        visible: handler.active
    }

    DragHandler {
        id: handler
        target: feedback
    }
}

Третий способ использования — установить target на null и реагировать на изменения свойств другим способом:

import QtQuick 2.12

Item {
    width: 640
    height: 480

    DragHandler {
        id: handler
        target: null
    }

    Text {
        color: handler.active ? "darkgreen" : "black"
        text: handler.centroid.position.x.toFixed(1) + "," + handler.centroid.position.y.toFixed(1)
        x: handler.centroid.position.x - width / 2
        y: handler.centroid.position.y - height
    }
}

Если minimumPointCount и maximumPointCount заданы значениями, большими 1, пользователю потребуется перетащить столько пальцев в одном направлении, чтобы начать перетаскивание. Жест перетаскивания с несколькими пальцами можно обнаружить независимо как от (по умолчанию) обработчика DragHandler с одним пальцем, так и от PinchHandler на том же элементе Item, и таким образом можно использовать его для корректировки какой-либо другой функции независимо от обычного поведения при щипании: например, отрегулировать преобразование наклона или отрегулировать какое-либо другое числовое значение, если target установлено в null. Но если target является элементом Item, centroid является точкой, в которой начинается перетаскивание, и в которую target будет перемещен (с учетом ограничений).

В настоящее время перетаскивание и падение не поддерживаются.

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

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

acceptedButtons : флаги

Кнопки мыши, которые могут активировать этот обработчик Pointer.

По умолчанию это свойство установлено в Qt.LeftButton. Его можно установить в логическую комбинацию кнопок мыши, и оно будет игнорировать события от других кнопок.

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

Item {
    TapHandler {
        onTapped: console.log("left clicked")
    }
    TapHandler {
        acceptedButtons: Qt.RightButton
        onTapped: console.log("right clicked")
    }
}

Примечание: Нажатие на сенсорный экран или нажатие стилуса на графическом планшете эмулирует щелчок левой кнопкой мыши. Это поведение можно изменить с помощью acceptedDevices или acceptedPointerTypes.

acceptedDevices : флаги

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

По умолчанию это свойство установлено в PointerDevice.AllDevices. Если вы установите его в логическую комбинацию типов устройств, оно будет игнорировать события от устройств, не соответствующих этому сочетанию.

Например, элемент управления можно сделать реагирующим на щелчки мыши и стилуса одним способом, а на нажатия на сенсорном экране — другим способом, используя два обработчика:

Item {
   TapHandler {
       acceptedDevices: PointerDevice.Mouse | PointerDevice.Stylus
       onTapped: console.log("clicked")
   }
   TapHandler {
       acceptedDevices: PointerDevice.TouchScreen
       onTapped: console.log("tapped")
   }
}

acceptedModifiers : флаги

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

Если это свойство установлено в 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 : флаги

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

По умолчанию это свойство установлено в 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 и активно управляет своим target (если таковой имеется).

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

margin : real

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

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

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

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

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

target : Item

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

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

[только для чтения] translation : QVector2D

Смещение с момента начала жеста.

xAxis.enabled : bool

xAxis управляет ограничениями для горизонтального перетаскивания.

minimum — минимальное приемлемое значение x, которое должно быть применено к target. maximum — максимальное приемлемое значение x, которое должно быть применено к target. Если enabled — true, горизонтальное перетаскивание разрешено.

yAxis.enabled : bool

yAxis управляет ограничениями для вертикального перетаскивания.

minimum — минимальное приемлемое значение y, которое должно быть применено к target. maximum — максимальное приемлемое значение y, которое должно быть применено к target. Если enabled — true, вертикальное перетаскивание разрешено.

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

canceled(EventPoint point)

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

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

grabChanged(GrabTransition transition, EventPoint point)

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

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

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