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 は、Item をインタラクティブに移動するためのハンドラです。他の入力ハンドラと同様に、デフォルトでは完全に機能し、target を操作します。
import QtQuick Rectangle { width: 100 height: 100 color: "lightsteelblue" DragHandler { } }
ドラッグの範囲を制限するプロパティを持っています。
もしそれが1つの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 を保持する。これは、この入力ハンドラが、それらのイベントポイントの動きに応じてその プロパティを最新に保ち、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.SplitVCursor
- Qt.SplitHCursor
- Qt.PointingHandCursor
- Qt.ForbiddenCursor
- Qt.WhatsThisCursor
- Qt.BusyCursor
- Qt.OpenHandCursor
- Qt.ClosedHandCursor
- Qt.DragCopyCursor
- 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 | このハンドラは、どのタイプのItemからも排他的グラブを取ることができます。 |
PointerHandler.CanTakeOverFromAnything | このハンドラは、どのタイプのアイテムまたはハンドラからも排他的グラブを取ることができます。 |
PointerHandler.ApprovesTakeOverByHandlersOfSameType | このハンドラーは、同じクラスの他のハンドラーがグラブを取ることを許可します。 |
PointerHandler.ApprovesTakeOverByHandlersOfDifferentType | このハンドラーは、あらゆる種類のハンドラーがグラブを取ることを許可します。 |
PointerHandler.ApprovesTakeOverByItems | このハンドラーは、あらゆる種類のItemがグラブを取ることを許可します。 |
PointerHandler.ApprovesCancellation | このハンドラは、そのグラブが null に設定されることを許可します。 |
PointerHandler.ApprovesTakeOverByAnything | このハンドラはどんな種類のItemやハンドラにもグラブを取る許可を与えます。 |
デフォルトはPointerHandler.CanTakeOverFromItems | PointerHandler.CanTakeOverFromHandlersOfDifferentType | PointerHandler.ApprovesTakeOverByAnything で、ほとんどの引き継ぎシナリオを許可しますが、例えば2つのPinchHandlerが同じタッチポイントを取り合うことを避けます。
margin : real
eventPoint がこのハンドラをアクティブにできる、parent アイテムの境界を超えたマージン。例えば、ユーザーが近くの位置からドラッグできるようにすることで、小さなアイテムをドラッグしやすくすることができます:
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
null でない場合、target に適用される翻訳。そうでない場合は、バインディングを使用してこの値で任意のことができます。ドラッグジェスチャが実行されている間、activeTranslation は継続的に追加されます。ジェスチャが終了した後も、この値は変わりません。
snapMode : enumeration
このプロパティはスナップモードを保持する。
スナップ・モードは、eventPoint に対するtarget アイテムの中心のスナップを設定する。
設定可能な値
| 定数 | 説明 |
|---|---|
DragHandler.NoSnap | スナップしない |
DragHandler.SnapAuto | eventPoint がtarget アイテムの外側で押され、 target がparent アイテムの子孫である場合、target はスナップします(デフォルト)。 |
DragHandler.SnapWhenPressedOutsideTarget | eventPoint が、target の項目の外側で押された場合、 はスナップします。target |
DragHandler.SnapAlways | 常にスナップする |
target : Item
このハンドラが操作するItem。
デフォルトでは、ハンドラが宣言されているItem(parent )と同じである。しかし、あるItem内のイベントを処理しながら別のItemを操作するために、ターゲットを別のItemに設定したり、null 、デフォルトの動作を無効にして、代わりに別の動作を行うために、ターゲットを別のItemに設定すると便利な場合がある。
xAxis group
xAxis 水平ドラッグの制約を制御する。
minimum は、target に適用されるx の許容可能な最小値である。maximum は、target に適用されるx の許容可能な最大値である。enabled が真の場合、水平ドラッグが許可される。activeValue は、activeTranslation.x と同じである。
activeValue が変更されるとactiveValueChanged シグナルが発せられ、変更されたインクリメントを提供する。これは、1つのプロパティを複数のハンドラでインクリメンタルに調整するためのものです。
yAxis group
yAxis は垂直ドラッグの制約を制御する。
minimum は、target に適用されるy の許容可能な最小値である。maximum は、target に適用されるy の許容可能な最大値である。enabled が真の場合、垂直ドラッグが許可される。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.