Тип QML DragHandler

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

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

Свойства

• acceptedButtons : флаги
• acceptedDevices : флаги
• acceptedModifiers : флаги
• acceptedPointerTypes : флаги
• active : bool
• cursorShape : Qt::CursorShape
• dragThreshold : int
• enabled : bool
• grabPermissions : флаги
• margin : вещественное число
• parent : Элемент
• target : Элемент
• translation : QVector2D
• xAxis
  • xAxis.enabled : bool
  • xAxis.maximum : вещественное число
  • xAxis.minimum : вещественное число
• yAxis
  • yAxis.enabled : bool
  • yAxis.maximum : вещественное число
  • yAxis.minimum : вещественное число

Сигналы

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

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

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

import QtQuick 2.12

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

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

Если он объявлен внутри одного элемента, но ему назначен другой 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 на одном элементе, и, таким образом, может быть использован для изменения какой-либо другой функции независимо от обычного поведения pinch: например, для изменения преобразования наклона или изменения некоторого другого числового значения, если target установлено в null. Но если target является элементом, centroid является точкой, в которой начинается перетаскивание, и к которой будет перемещён target (с учётом ограничений).

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

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

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

acceptedButtons : флаги

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

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

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

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

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

acceptedDevices : флаги

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

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

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

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