Тип QML DragHandler

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

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

Свойства

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

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

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

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

acceptedButtons : flags

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

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

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

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

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

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

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

Перемещение во время выполнения жеста перетаскивания. Оно равно 0, 0 в начале жеста и увеличивается по мере перетаскивания точки (или точек) события вниз и вправо. После завершения жеста оно остается неизменным; и при начале следующего жеста перетаскивания оно сбрасывается до значения 0, 0 снова.

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

margin : real

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

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

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

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

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

persistentTranslation : QVector2D

Перевод, который будет применён к target, если он не null. В противном случае для работы с этим значением можно использовать привязки. Во время выполнения жестикуляции перетаскивания к нему постоянно добавляется activeTranslation; после завершения жестикуляции он остаётся неизменным.

target : Item

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

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

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.