DragHandler QML Type
ドラッグ操作のハンドラ。詳細...
| Import Statement: | import QtQuick |
| Inherits: |
プロパティ
- acceptedButtons : flags
- acceptedDevices : flags
- acceptedModifiers : flags
- acceptedPointerTypes : flags
- active : bool
- activeTranslation : vector2d
- cursorShape : Qt::CursorShape
- dragThreshold : int
- enabled : bool
- grabPermissions : flags
- margin : real
- parent : Item
- persistentTranslation : vector2d
- snapMode : enumeration
- target : Item
- xAxis
- xAxis.activeValue : real
- xAxis.enabled : bool
- xAxis.maximum : real
- xAxis.minimum : real
- yAxis
- yAxis.activeValue : real
- yAxis.enabled : bool
- yAxis.maximum : real
- yAxis.minimum : real
信号
- canceled(eventPoint point)
- grabChanged(PointerDevice::GrabTransition transition, eventPoint point)
詳細な説明
DragHandlerは、アイテムをインタラクティブに移動させるために使用されるハンドラです。他の入力ハンドラと同様に、デフォルトでは完全に機能しており、target を操作します。
import QtQuick
Rectangle {
width: 100
height: 100
color: "lightsteelblue"
DragHandler { }
}ドラッグの範囲を制限するためのプロパティを備えています。
あるItem内で宣言され、別のtarget が割り当てられている場合、parent のItemの範囲内でイベントを処理しますが、代わりにtarget のItemを操作します:
import QtQuick
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
}
}3つ目の使用方法は、target をnull に設定し、プロパティの変更に対して別の方法で反応させることです:
import QtQuick
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 とは独立して検出できるため、通常のピンチ動作とは別に、他の機能を調整するために使用できます。例えば、target が null に設定されている場合、チルト変換を調整したり、その他の数値を調整したりすることが可能です。 ただし、target がItemである場合、centroid は、ドラッグが開始される地点であり、target が(制約に従って)移動される地点となります。
DragHandlerは、Drag アタッチドプロパティと組み合わせて使用することで、ドラッグアンドドロップを実装できます。
「 Drag 」、「MouseArea 」、および「Qt Quick Examples - Pointer Handlers」も参照してください 。
プロパティのドキュメント
acceptedButtons : flags
このDragHandler を起動できるマウスボタン。
デフォルトでは、このプロパティは `Qt.LeftButton` に設定されています。マウスボタンの「または(OR)」組み合わせに設定することができ、それ以外のボタンからのイベントは無視されます。
たとえば、あるコンポーネント(TextEdit など)がすでに独自の方法で左ボタンによるドラッグを処理している場合、右ボタンでドラッグされた際に別の動作を行うDragHandler を追加することで、その機能を拡張することができます:
Rectangle {
id: canvas
width: 640
height: 480
color: "#333"
property int highestZ: 0
Repeater {
model: FolderListModel { nameFilters: ["*.qml"] }
delegate: Rectangle {
required property string fileName
required property url fileUrl
required property int index
id: frame
x: index * 30; y: index * 30
width: 320; height: 240
property bool dragging: ldh.active || rdh.active
onDraggingChanged: if (dragging) z = ++canvas.highestZ
border { width: 2; color: dragging ? "red" : "steelblue" }
color: "beige"
clip: true
TextEdit {
// drag to select text
id: textEdit
textDocument.source: frame.fileUrl
x: 3; y: 3
BoundaryRule on y {
id: ybr
minimum: textEdit.parent.height - textEdit.height; maximum: 0
minimumOvershoot: 200; maximumOvershoot: 200
overshootFilter: BoundaryRule.Peak
}
}
DragHandler {
id: rdh
// right-drag to position the "window"
acceptedButtons: Qt.RightButton
}
WheelHandler {
target: textEdit
property: "y"
onActiveChanged: if (!active) ybr.returnToBounds()
}
Rectangle {
anchors.right: parent.right
width: titleText.implicitWidth + 12
height: titleText.implicitHeight + 6
border { width: 2; color: parent.border.color }
bottomLeftRadius: 6
Text {
id: titleText
color: "saddlebrown"
anchors.centerIn: parent
text: frame.fileName
textFormat: Text.PlainText
}
DragHandler {
id: ldh
// left-drag to position the "window"
target: frame
}
}
}
}
}acceptedDevices : flags
このDragHandler を起動できるポインティングデバイスの種類。
デフォルトでは、このプロパティは `PointerDevice.AllDevices` に設定されています。デバイスタイプの「OR」組み合わせに設定した場合、条件に一致しないデバイスからのイベントは無視されます。
注: 現時点では、すべてのプラットフォームがマウスとタッチパッドを区別できるわけではありません 。また、区別できるプラットフォームであっても、マウスとタッチパッドの挙動を同じにしたい場合がよくあります。
acceptedModifiers : flags
このプロパティが設定されている場合、ポインタイベントに反応するには、指定されたキーボード修飾キーが押されている必要があり、そうでない場合はそれらのイベントを無視します。
たとえば、2つのDragHandlerは、Control 修飾キーが押されているかどうかに応じて、2つの異なるドラッグ&ドロップ操作を実行できます。
GridView {
id: root
width: 320
height: 480
cellWidth: 80
cellHeight: 80
interactive: false
displaced: Transition {
NumberAnimation {
properties: "x,y"
easing.type: Easing.OutQuad
}
}
model: DelegateModel {
id: visualModel
model: 24
property var dropTarget: undefined
property bool copy: false
delegate: DropArea {
id: delegateRoot
width: 80
height: 80
onEntered: drag => {
if (visualModel.copy) {
if (drag.source !== icon)
visualModel.dropTarget = icon
} else {
visualModel.items.move(drag.source.DelegateModel.itemsIndex, icon.DelegateModel.itemsIndex)
}
}
Rectangle {
id: icon
objectName: DelegateModel.itemsIndex
property string text
Component.onCompleted: {
color = Qt.rgba(0.2 + (48 - DelegateModel.itemsIndex) * Math.random() / 48,
0.3 + DelegateModel.itemsIndex * Math.random() / 48,
0.4 * Math.random(),
1.0)
text = DelegateModel.itemsIndex
}
border.color: visualModel.dropTarget === this ? "black" : "transparent"
border.width: 2
radius: 3
width: 72
height: 72
anchors {
horizontalCenter: parent.horizontalCenter
verticalCenter: parent.verticalCenter
}
states: [
State {
when: dragHandler.active || controlDragHandler.active
ParentChange {
target: icon
parent: root
}
AnchorChanges {
target: icon
anchors {
horizontalCenter: undefined
verticalCenter: undefined
}
}
}
]
Text {
anchors.centerIn: parent
color: "white"
font.pointSize: 14
text: controlDragHandler.active ? "+" : icon.text
}
DragHandler {
id: dragHandler
acceptedModifiers: Qt.NoModifier
onActiveChanged: if (!active) visualModel.dropTarget = undefined
}
DragHandler {
id: controlDragHandler
acceptedModifiers: Qt.ControlModifier
onActiveChanged: {
visualModel.copy = active
if (!active) {
visualModel.dropTarget.text = icon.text
visualModel.dropTarget.color = icon.color
visualModel.dropTarget = undefined
}
}
}
Drag.active: dragHandler.active || controlDragHandler.active
Drag.source: icon
Drag.hotSpot.x: 36
Drag.hotSpot.y: 36
}
}
}
}このプロパティがQt.KeyboardModifierMask (デフォルト値)に設定されている場合、DragHandler は修飾キーを無視します。
acceptedModifiers を修飾キーの「OR」組み合わせに設定した場合、そのハンドラを有効にするには、それらの修飾キーがすべて押されている必要があります。
使用可能な修飾キーは以下の通りです:
| 定数 | 説明 |
|---|---|
NoModifier | 修飾キーは使用できません。 |
ShiftModifier | キーボードの Shift キーを押す必要があります。 |
ControlModifier | キーボードの Ctrl キーを押す必要があります。 |
AltModifier | キーボードの Alt キーを押す必要があります。 |
MetaModifier | キーボードの Meta キーを押す必要があります。 |
KeypadModifier | テンキーのボタンを押す必要があります。 |
GroupSwitchModifier | X11 のみ(Windows でコマンドライン引数によって有効化されていない場合)。キーボードの Mode_switch キーを押す必要があります。 |
KeyboardModifierMask | ハンドラは、どの修飾キーが押されたかについては関知しません。 |
Qt::KeyboardModifierも参照してください 。
acceptedPointerTypes : flags
このDragHandler を起動できるポインティングデバイスの種類(指、スタイラス、消しゴムなど)。
デフォルトでは、このプロパティはPointerDevice.AllPointerTypes に設定されています。デバイスタイプの「OR」組み合わせに設定した場合、条件に一致しないdevices からのイベントは無視されます。
active : bool [read-only]
この変数には、この入力ハンドラが1つ以上のeventPoints を排他的に取得することに成功し、それらの処理を単独で担当している間、true が格納されます。これは、この入力ハンドラが、それらのeventPointsの動きに応じて自身のプロパティを最新の状態に保ち、target (存在する場合)を能動的に操作していることを意味します。
activeTranslation : vector2d [read-only]
ドラッグジェスチャーが実行されている間の移動量です。ジェスチャーが開始された時点では0, 0 ですが、イベントポイントが下方向および右方向へドラッグされるにつれて増加します。ジェスチャーが終了した後はその値のまま維持され、次のドラッグジェスチャーが開始されると、再び0, 0 にリセットされます。
cursorShape : Qt::CursorShape
このプロパティは、active がtrue に設定されている間、parent アイテムにマウスをホバーさせた際に表示されるカーソルの形状を保持します。
利用可能なカーソル形状は以下の通りです:
- Qt.ArrowCursor
- Qt.UpArrowCursor
- Qt.CrossCursor
- Qt.WaitCursor
- Qt.IBeamCursor
- Qt.SizeVerCursor
- Qt.SizeHorCursor
- Qt.SizeBDiagCursor
- Qt.SizeFDiagCursor
- Qt.SizeAllCursor
- Qt.BlankCursor
- Qt.SplitVカーソル
- Qt.SplitHCursor
- Qt.指差しカーソル
- Qt.ForbiddenCursor
- Qt.WhatIsThisカーソル
- Qt.BusyCursor
- Qt.開いた手のカーソル
- Qt.閉じた手のカーソル
- Qt.ドラッグコピーカーソル
- Qt.DragMoveCursor
- Qt.DragLinkCursor
デフォルト値は設定されておらず、これによりparent 項目のcursor が表示されます。このプロパティは、undefinedに設定することで、初期状態と同じ状態にリセットできます。
注: このプロパティが設定されていない場合 、または `undefined` に設定されている場合、その値を読み取ると `Qt.ArrowCursor` が返されます。
関連項目: Qt::CursorShape 、QQuickItem::cursor()、およびHoverHandler::cursorShape 。
dragThreshold : int
eventPoint をドラッグジェスチャーとして認識させるために、ユーザーがドラッグしなければならないピクセル単位の距離。
デフォルト値はプラットフォームや画面解像度によって異なります。これを `undefined` に設定することで、デフォルト値にリセットできます。ドラッグジェスチャーの開始時の動作は、ハンドラによって異なります。
enabled : bool
PointerHandler が無効になっている場合、すべてのイベントが拒否され、シグナルは一切発信されません。
PointerHandler のparent がdisabled に設定されている場合、enabled プロパティがtrue のままであっても、ハンドラは事実上無効化されます。
注: HoverHandler の動作は異なります。詳細については、そのenabled プロパティのドキュメントを参照してください。
grabPermissions : flags
このプロパティは、このハンドラのロジックが排他的なグラブを引き継ぐことを決定した場合、または別のハンドラからグラブの引き継ぎや取り消しの承認を求められた場合の権限を指定します。
| 定数 | 説明 |
|---|---|
PointerHandler.TakeOverForbidden | このハンドラは、いかなるタイプの Item や Handler に対しても、グラブ権限を取得したり付与したりすることはありません。 |
PointerHandler.CanTakeOverFromHandlersOfSameType | 定数説明このハンドラは、いかなる種類のアイテムやハンドラからもグラブ権限を取得したり、付与したりすることはありません。 |
PointerHandler.CanTakeOverFromHandlersOfDifferentType | このハンドラは、あらゆる種類のハンドラから排他グラブを取得することができます。このハンドラは、あらゆる種類のアイテムから排他グラブを取得することができます。 |
PointerHandler.CanTakeOverFromItems | このハンドラは、あらゆるタイプのアイテムから排他的なグラブを取得できます。 |
PointerHandler.CanTakeOverFromAnything | このハンドラは、あらゆる種類のアイテムやハンドラから排他的なグラブを取得できます。 |
PointerHandler.ApprovesTakeOverByHandlersOfSameType | このハンドラは、同じクラスの別のハンドラがグラブを取得することを許可します。 |
PointerHandler.ApprovesTakeOverByHandlersOfDifferentType | このハンドラは、あらゆる種類のハンドラにグラブを許可します。 |
PointerHandler.ApprovesTakeOverByItems | このハンドラは、あらゆる種類のアイテムがグラブを取得することを許可します。 |
PointerHandler.ApprovesCancellation | このハンドラは、自身のグラブが null に設定されることを許可します。 |
PointerHandler.ApprovesTakeOverByAnything | このハンドラは、あらゆるタイプのアイテムまたはハンドラがグラブを取得することを許可します。 |
デフォルトは `PointerHandler.CanTakeOverFromItems | PointerHandler.CanTakeOverFromHandlersOfDifferentType | PointerHandler.ApprovesTakeOverByAnything ` であり、ほとんどの引き継ぎシナリオを許可しますが、例えば 2 つの `PinchHandler` が同じタッチポイントを奪い合うような事態は回避します。
margin : real
parent 項目の境界線の外側にある余白で、eventPoint がこのハンドラを起動できる範囲です。たとえば、ユーザーが近くの位置からドラッグできるようにすることで、小さな項目のドラッグ操作を容易にすることができます:
Rectangle {
width: 24
height: 24
border.color: "steelblue"
Text {
text: "it's\ntiny"
font.pixelSize: 7
rotation: -45
anchors.centerIn: parent
}
DragHandler {
margin: 12
}
}parent : Item
Item は、ハンドラの適用範囲であり、それが宣言されたItemです。ハンドラはこのItemに代わってイベントを処理します。つまり、ポインタイベントは、そのeventPoints のうち少なくとも1つがItemの内部で発生する場合にのみ関連付けられます。初期状態ではtarget() は同一ですが、再代入が可能です。
target およびQObject::parent()も参照してください 。
persistentTranslation : vector2d
target がnull でない場合に適用される変換です。そうでない場合、バインディングを使用してこの値に対して任意の処理を行うことができます。ドラッグジェスチャーが実行されている間は、activeTranslation が継続的に追加されますが、ジェスチャーが終了した後は、その値は変わりません。
snapMode : enumeration
このプロパティはスナップモードを保持します。
スナップモードは、target 項目の中心をeventPoint にスナップさせる設定を行います。
指定可能な値:
| 定数 | 説明 |
|---|---|
DragHandler.NoSnap | スナップしない |
DragHandler.SnapAuto | 「target 」アイテムの外側で「eventPoint 」が押された場合、かつ「target 」が「parent 」アイテムの子要素である場合に、「target 」がスナップします(既定値) |
DragHandler.SnapWhenPressedOutsideTarget | 「target 」は、eventPoint がtarget |
DragHandler.SnapAlways | 常にスナップ |
target : Item
このハンドラが操作するアイテム。
デフォルトでは、これはparent 、つまりハンドラが宣言されているItemと同じになります。ただし、あるアイテム内のイベントを処理しつつ別のアイテムを操作する場合や、null に設定してデフォルトの動作を無効にし、代わりに別の処理を行う場合など、ターゲットを別のItemに設定すると便利な場合があります。
xAxis group
xAxis 水平方向のドラッグに関する制約を制御します。
minimum は、target に適用されるx の最小許容値です。maximum は、target に適用されるx の最大許容値です。enabled がtrueの場合、水平方向のドラッグが許可されます。activeValue はactiveTranslation.x と同じです。
activeValueChanged シグナルは、activeValue が変更された際に発火し、変更された増分値を提供します。これは、複数のハンドラを介して1つのプロパティを増分的に調整することを目的としています。
yAxis group
yAxis 垂直方向のドラッグに関する制約を制御します。
minimum は、target に適用されるy の最小許容値です。maximum は、target に適用されるy の最大許容値です。enabled がtrueの場合、垂直方向のドラッグが許可されます。activeValue はactiveTranslation.y と同じです。
activeValueChanged シグナルは、activeValue が変更された際に発火し、変更された増分値を提供します。これは、複数のハンドラを通じて1つのプロパティを段階的に調整することを目的としています:
import QtQuick
Rectangle {
width: 50; height: 200
Rectangle {
id: knob
width: parent.width; height: width; radius: width / 2
anchors.centerIn: parent
color: "lightsteelblue"
Rectangle {
antialiasing: true
width: 4; height: 20
x: parent.width / 2 - 2
}
WheelHandler {
property: "rotation"
}
}
DragHandler {
target: null
dragThreshold: 0
yAxis.onActiveValueChanged: (delta)=> { knob.rotation -= delta }
}
}シグナルのドキュメント
canceled(eventPoint point)
このハンドラーがすでに指定されたpoint を取得している場合、別のポインタハンドラーまたはアイテムによってその取得が奪われたときに、このシグナルが発信されます。
注: 対応するハンドラは onCanceled です。
grabChanged(PointerDevice::GrabTransition transition, eventPoint point)
このシグナルは、グラブにこのハンドラに関連する何らかの変化が生じたときに発せられます。
transition (動詞)は、何が起こったかを示します。point (目的語)は、グラブされた、またはグラブが解除されたポイントです。
transition の有効な値は以下の通りです:
| 定数 | 説明 |
|---|---|
PointerDevice.GrabExclusive | このハンドラは、point の処理について主たる責任を引き受けました。 |
PointerDevice.UngrabExclusive | このハンドラは、以前の排他的なグラブを放棄しました。 |
PointerDevice.CancelGrabExclusive | このハンドラの排他的なグラブが引き継がれたか、またはキャンセルされました。 |
PointerDevice.GrabPassive | このハンドラは、point を監視するために、パッシブ・グラブを取得しました。 |
PointerDevice.UngrabPassive | このハンドラは、以前のパッシブ・グラブを解放しました。 |
PointerDevice.CancelGrabPassive | このハンドラの以前のパッシブグラブが異常終了しました。 |
注: 対応するハンドラは onGrabChanged です。
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.