Тип QML DragHandler

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

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

Свойства

• acceptedButtons : flags
• acceptedDevices : flags
• acceptedModifiers : flags
• acceptedPointerTypes : flags
• active : bool
• cursorShape : Qt::CursorShape
• dragThreshold : int
• enabled : bool
• grabPermissions : flags
• 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, и таким образом можно использовать его для настройки какой-либо другой функции независимо от обычного поведения pinch: например, настроить трансформирование наклона или настроить какое-то другое числовое значение, если target установлено в null. Но если target является элементом Item, centroid — это точка, в которой начинается перетаскивание, и в которую будет перемещен target (с учетом ограничений).

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

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

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

acceptedButtons : flags

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

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

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

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

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

acceptedDevices : flags

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

По умолчанию это свойство установлено в 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

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

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

[с 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.

[с 5.15] dragThreshold : int

Расстояние в пикселях, на которое пользователь должен перетащить точку события, чтобы оно обрабатывалось как жестом перетаскивания.

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

Это свойство было введено в Qt 5.15.

enabled : bool

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

grabPermissions : flags

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

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

margin : real

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

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

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

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

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

target : Item

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

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

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

grabChanged(GrabTransition transition, EventPoint point)

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

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

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