MouseArea QML Type

簡単なマウス操作を可能にします。詳細...

• 継承されたメンバーを含む、すべてのメンバーの一覧

プロパティ

• acceptedButtons : Qt::MouseButtons
• containsMouse : bool
• containsPress : bool
• cursorShape : Qt::CursorShape
• drag
  • drag.active : bool
  • drag.axis : enumeration
  • drag.filterChildren : bool
  • drag.maximumX : real
  • drag.maximumY : real
  • drag.minimumX : real
  • drag.minimumY : real
  • drag.smoothed : bool
  • drag.target : Item
  • drag.threshold : real
• enabled : bool
• hoverEnabled : bool
• mouseX : real
• mouseY : real
• pressAndHoldInterval : int
• pressed : bool
• pressedButtons : MouseButtons
• preventStealing : bool
• propagateComposedEvents : bool
• scrollGestureEnabled : bool

信号

• canceled()
• clicked(MouseEvent mouse)
• doubleClicked(MouseEvent mouse)
• entered()
• exited()
• positionChanged(MouseEvent mouse)
• pressAndHold(MouseEvent mouse)
• pressed(MouseEvent mouse)
• released(MouseEvent mouse)
• wheel(WheelEvent wheel)

詳細説明

MouseArea は、通常、表示されているアイテムと組み合わせて使用され、そのアイテムに対するマウス処理を提供する、目に見えないアイテムです。MouseArea アイテムは、事実上プロキシとして機能することで、マウス処理のロジックをその内部に収めることができます。

enabled プロパティは、プロキシ対象のアイテムに対するマウス処理を有効または無効にするために使用されます。無効にすると、マウスエリアはマウスイベントに対して透過状態になります。

MouseAreaは非表示のアイテムですが、visibleプロパティを持っています。これをfalseに設定すると、マウスエリアはマウスイベントに対して透過状態になります。

pressed という読み取り専用プロパティは、ユーザーがマウスエリア上でマウスボタンを押したままにしているかどうかを示します。このプロパティは、ユーザーインターフェース内のプロパティ間のバインディングでよく使用されます。containsMouse という読み取り専用プロパティは、マウスエリア上にマウスカーソルが存在するかどうかを示しますが、デフォルトではマウスボタンが押された状態でのみ有効です。詳細については、containsMouse のドキュメントを参照してください。

マウスの位置やボタンのクリックに関する情報は、イベントハンドラプロパティが定義されているシグナルを介して提供されます。最も一般的に使用されるのは、マウスの押下やクリックを処理する onClicked、onDoubleClicked、onPressed、onReleased、および onPressAndHold です。また、onWheel シグナルを介してマウスホイールイベントを処理することも可能です。

MouseAreaが他のMouseAreaアイテムの領域と重なっている場合、propagateComposedEvents をtrueに設定し、伝播すべきイベントを拒否することで、clicked 、doubleClicked 、およびpressAndHold イベントをこれらの他のアイテムに伝播させるように選択できます。詳細については、propagateComposedEvents のドキュメントを参照してください。

デフォルトでは、MouseArea アイテムはマウスクリックのみを報告し、マウスカーソルの位置の変更は報告しません。hoverEnabled プロパティを設定すると、マウスボタンが押されていない場合でも、onPositionChanged、onEntered、onExited に対して定義されたハンドラが使用され、containsMouse プロパティが更新されるようになります。

使用例

次の例では、クリック時に `Rectangle ` の色を赤に変更する `Rectangle ` 内で `MouseArea` を使用しています：

import QtQuick

Rectangle {
    width: 100; height: 100
    color: "green"

    MouseArea {
        anchors.fill: parent
        onClicked: { parent.color = 'red' }
    }
}

多くのMouseAreaシグナルは、位置、ボタン、キー修飾子など、マウスイベントに関する追加情報を含むmouse パラメータを渡します。

以下は、前の例を拡張したもので、領域を右クリックしたときに別の色を表示します：

Rectangle {
    width: 100; height: 100
    color: "green"

    MouseArea {
        anchors.fill: parent
        acceptedButtons: Qt.LeftButton | Qt.RightButton
        onClicked: (mouse)=> {
            if (mouse.button == Qt.RightButton)
                parent.color = 'blue';
            else
                parent.color = 'red';
        }
    }
}

「 MouseEvent」 、「MouseArea」の例、および『Qt Quick - ユーザー入力』の「重要な概念」も参照してください 。

プロパティのドキュメント

acceptedButtons : Qt::MouseButtons

このプロパティには、マウス領域が反応するマウスボタンが格納されます。

MouseArea が複数のボタンに反応するように指定するには、Qt::MouseButtons のフラグ値を「|」（または）演算子を用いて組み合わせます:

MouseArea { acceptedButtons: Qt.LeftButton | Qt.RightButton }

利用可能なすべてのマウスボタンを受け入れることを示すには、特別な値「Qt.AllButtons」を使用できます:

MouseArea { acceptedButtons: Qt.AllButtons }

デフォルト値は `Qt.LeftButton` です。

containsMouse : bool [read-only]

このプロパティは、マウスが現在マウス領域内にあるかどうかを示します。

containsPress : bool [read-only]

これは、pressed && containsMouse と同等の便宜上のプロパティであり、つまり、acceptedButtons のいずれかが現在押されているか、かつマウスが現在MouseArea 内にある場合に成立します。

このプロパティは、マウスが項目の境界内で押されている間にその項目をハイライト表示する際に特に有用です。

pressed およびcontainsMouseも参照してください 。

cursorShape : Qt::CursorShape

このプロパティは、このマウス領域のカーソル形状を指定します。マウスカーソルを表示しないプラットフォームでは、この設定が反映されない場合があることに注意してください。

利用可能なカーソルの形状は以下の通りです：

• 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.PointingHandCursor
• Qt.禁止カーソル
• Qt.WhatIsThisカーソル
• Qt.BusyCursor
• Qt.開いた手のカーソル
• Qt.閉じた手のカーソル
• Qt.ドラッグコピーカーソル
• Qt.DragMoveCursor
• Qt.DragLinkCursor

マウスイベントに反応せずに、特定の領域に対してマウスカーソルの形状のみを設定するには、acceptedButtons をnoneに設定します。

MouseArea { cursorShape: Qt.IBeamCursor; acceptedButtons: Qt.NoButton }

デフォルト値はQt.ArrowCursor です。

「Qt::CursorShape」も参照してください 。

drag group

drag アイテムをドラッグ可能にする便利な方法を提供します。

• drag.target ドラッグする項目の ID を指定します。
• drag.active ターゲットアイテムが現在ドラッグされているかどうかを指定します。
• drag.axis 水平方向（Drag.XAxis ）、垂直方向（Drag.YAxis ）、またはその両方（Drag.XAndYAxis ）でドラッグが可能かどうかを指定します。
• drag.minimum また、drag.maximum は、対象が対応する軸に沿ってドラッグできる距離を制限します。

次の例は、X 軸に沿ってドラッグできるRectangle を表示します。長方形を右にドラッグすると、その不透明度が低下します。

Rectangle {
    id: container
    width: 600; height: 200

    Rectangle {
        id: rect
        width: 50; height: 50
        color: "red"
        opacity: (600.0 - rect.x) / 600

        MouseArea {
            anchors.fill: parent
            drag.target: rect
            drag.axis: Drag.XAxis
            drag.minimumX: 0
            drag.maximumX: container.width - rect.width
        }
    }
}

drag.filterChildren がtrueに設定されている場合、ドラッグ操作は子要素のMouseAreasをオーバーライドできます。これにより、たとえば親要素のMouseArea がドラッグ操作を処理し、子要素がクリック処理を行うといったことが可能になります：

import QtQuick

Rectangle {
    width: 480
    height: 320
    Rectangle {
        x: 30; y: 30
        width: 300; height: 240
        color: "lightsteelblue"

        MouseArea {
            anchors.fill: parent
            drag.target: parent;
            drag.axis: "XAxis"
            drag.minimumX: 30
            drag.maximumX: 150
            drag.filterChildren: true

            Rectangle {
                color: "yellow"
                x: 50; y : 50
                width: 100; height: 100
                MouseArea {
                    anchors.fill: parent
                    onClicked: console.log("Clicked")
                }
            }
        }
    }
}

drag.threshold ドラッグ操作が開始される閾値をピクセル単位で指定します。デフォルトでは、これはプラットフォーム依存の値に紐付けられています。このプロパティはQt Quick 2.2で追加されました。

drag.smoothed がtrue の場合、ターゲットはドラッグ操作が開始されてから移動します。false に設定された場合、ターゲットは直ちに現在のマウス位置へ移動します。デフォルトでは、このプロパティはtrue です。このプロパティはQt Quick 2.4で追加されました。

ドロップ処理を実装する場合は、Drag の添付プロパティおよびDropArea を参照してください。

enabled : bool

このプロパティは、そのアイテムがマウスイベントを受け付けるかどうかを示します。

デフォルトでは、このプロパティの値は true です。

hoverEnabled : bool

このプロパティは、ホバーイベントを処理するかどうかを指定します。

デフォルトでは、マウスイベントはボタンイベントへの応答時、またはボタンが押されたときにのみ処理されます。「hover」を有効にすると、マウスボタンが押されていない場合でも、すべてのマウスイベントを処理できるようになります。

このプロパティは、containsMouse プロパティおよびonEntered、onExited、onPositionChangedシグナルに影響を与えます。

これらのプロパティには、マウスカーソルの座標が格納されます。

hoverEnabled プロパティがfalseの場合、これらのプロパティはボタンが押されている間のみ有効となり、マウスカーソルが領域の外に移動しても、ボタンが押し続けられている限り有効なままとなります。

デフォルトでは、このプロパティは false に設定されています。

hoverEnabled が true の場合、これらのプロパティは次の場合に有効になります。

• ボタンが押されていないが、マウスがMouseArea の範囲内にある場合（containsMouse がtrueの場合）。
• ボタンが押されたままの状態である場合（その後、マウスが領域外に移動したとしても）。

座標はMouseArea を基準としています。

pressAndHoldInterval : int

このプロパティは、pressAndHold が発行されるまでの経過時間（ミリ秒単位）を上書きします。

明示的に設定されていない場合、またはリセット後は、この値は `QStyleHints::mousePressAndHoldInterval` に従います。

通常、アプリケーションスタイルヒントを使用してこのプロパティをグローバルに設定すれば十分です。このプロパティは、特定の MouseAreas に対して異なる間隔が必要な場合に使用してください。

「pressAndHold」も参照してください 。

pressed : bool [read-only]

このプロパティは、acceptedButtons のいずれかが現在押されているかどうかを表します。

pressedButtons : MouseButtons [read-only]

このプロパティには、現在押されているマウスボタンが格納されます。

このプロパティには、以下のビット単位の組み合わせが含まれます：

• Qt.LeftButton
• Qt.RightButton
• Qt.MiddleButton

以下のコードは、マウスの右ボタンが押されたときに「right」と表示します:

Text {
    text: mouseArea.pressedButtons & Qt.RightButton ? "right" : ""
    horizontalAlignment: Text.AlignHCenter
    verticalAlignment: Text.AlignVCenter

    MouseArea {
        id: mouseArea
        anchors.fill: parent
        acceptedButtons: Qt.LeftButton | Qt.RightButton
    }
}

「acceptedButtons」も参照してください 。

preventStealing : bool

このプロパティは、このMouseArea からマウスイベントをスティールできるかどうかを指定します。

MouseArea が、Flickableなど子要素のマウスイベントをフィルタリングするアイテム内に配置されている場合、親アイテムによってジェスチャー（例：フリックジェスチャー）が認識されると、MouseArea からマウスイベントが奪われる可能性があります。preventStealingがtrueに設定されている場合、どのアイテムもマウスイベントを奪うことはありません。

なお、アイテムがイベントの横取りを開始した後に preventStealing を true に設定しても、次の press イベントが発生するまでは効果がありません。

デフォルトでは、このプロパティの値は false です。

propagateComposedEvents : bool

このプロパティは、合成されたマウスイベントが、このMouseArea と重なるが、視覚的なスタック順が下にある他のMouseAreasに自動的に伝播するかどうかを指定します。デフォルトでは、このプロパティの値はfalseです。

MouseArea clicked には、 、 、 といったいくつかの合成イベントが含まれています。これらは などの基本的なマウスイベントで構成されており、基本的なイベントとは異なる方法で伝播される可能性があります。doubleClicked pressAndHold pressed

propagateComposedEvents が true に設定されている場合、複合イベントはシーン内の同じ位置にある他の MouseArea へ自動的に伝播されます。 各イベントは、スタック順でその下にある次のenabled （MouseArea ）に伝播され、MouseArea がイベントを受け入れるまで、このビジュアルヒエラルキーを下に向かって伝播していきます。pressed イベントとは異なり、コンポーズされたイベントは、ハンドラが存在しない場合、自動的に受け入れられることはありません。

たとえば、以下は青いRectangle を含む黄色のRectangle です。青い矩形は視覚的な積み重ね順序の階層において最上位のアイテムであり、黄色の矩形の上に視覚的にレンダリングされます。 青い矩形は、propagateComposedEvents を true に設定し、受信したすべてのclicked イベントに対してMouseEvent::accepted を false に設定しているため、受信したclicked イベントはすべて、その下にある黄色い矩形のMouseArea に伝播されます。

import QtQuick 2.0

Rectangle {
    color: "yellow"
    width: 100; height: 100

    MouseArea {
        anchors.fill: parent
        onClicked: console.log("clicked yellow")
    }

    Rectangle {
        color: "blue"
        width: 50; height: 50

        MouseArea {
            anchors.fill: parent
            propagateComposedEvents: true
            onClicked: (mouse)=> {
                console.log("clicked blue")
                mouse.accepted = false
            }
        }
    }
}

青い長方形をクリックすると、その子要素であるMouseArea のonClicked ハンドラが呼び出されます。その後、イベントは黄色い長方形のMouseArea に伝播され、その結果、黄色い長方形自身のonClicked ハンドラが呼び出されます。

このプロパティにより、重なり合うMouseAreasが複合イベントを共同で処理するというユースケースが大幅に簡素化されます。例えば、あるMouseArea にclicked シグナルを処理させ、もう一方にpressAndHold を処理させたい場合や、あるMouseArea に通常はclicked を処理させつつ、特定の条件が満たされた際にはそれを透過させたい場合などが挙げられます。

scrollGestureEnabled : bool

このプロパティは、このMouseArea が、トラックパッドでの2本指フリックジェスチャなど、マウス以外のデバイスからのスクロールジェスチャに応答するかどうかを制御します。falseに設定した場合、wheel シグナルは、ホイールを備えた実際のマウスからのホイールイベントが発生した場合にのみ発火し、スクロールジェスチャイベントは、それらを処理する他のItemにそのまま渡されます。 たとえば、ユーザーがカーソルをMouseArea を含むアイテムの上に置いた状態でフリックジェスチャを実行し、その下にあるFlickableとインタラクションしようとする場合があります。このプロパティをfalseに設定すると、PinchArea がマウスホイールやピンチジェスチャを処理し、Flickableがフリックジェスチャを処理できるようになります。

デフォルトでは、このプロパティは true です。

Signal ドキュメント

canceled()

このシグナルは、別のアイテムがマウスイベントの処理を横取りしたために、マウスイベントがキャンセルされた際に発せられます。

このシグナルは高度な用途向けです。複数のMouseArea が入力を処理している場合や、Flickable 内にMouseArea が存在する場合に役立ちます。 後者の場合、onPressed シグナルハンドラで何らかのロジックを実行してからドラッグを開始すると、Flickable がMouseArea からマウス処理を奪います。このような場合、MouseArea がFlickable にマウス処理を奪われた際にロジックをリセットするには、released に加えてcanceled も処理する必要があります。

clicked(MouseEvent mouse)

このシグナルは、クリックが発生したときに発信されます。クリックとは、MouseArea 内で押下と離下が連続して行われることを指します（押下してMouseArea の外側に移動し、その後再び内部に戻って離す場合もクリックとみなされます）。

mouse パラメータは、クリックの解除位置の x 座標と y 座標、およびクリックが長押しされたかどうかなど、クリックに関する情報を提供します。

このシグナルを処理する際、propagateComposedEvents プロパティがtrue に設定されていない限り、mouse パラメータのaccepted プロパティを変更しても何の効果もありません。

doubleClicked(MouseEvent mouse)

このシグナルは、ダブルクリック（クリック、指を離し、再びクリック）が行われたときに発生します。mouse パラメータは、クリックが押された位置のx座標とy座標、およびクリックが長押しされていたかどうかなど、クリックに関する情報を提供します。

このシグナルを処理する際、mouse パラメータのaccepted プロパティがfalseに設定されている場合、2回目のクリックに対してpressed/released/clickedシグナルが発行されます。そうでない場合は、これらのシグナルは抑制されます。accepted プロパティのデフォルト値はtrueです。

entered()

このシグナルは、マウスがマウスエリアに入ったときに発せられます。

デフォルトでは、このシグナルはボタンが押されている場合にのみ発火します。hoverEnabled をtrueに設定すると、マウスボタンが押されていない場合でもこのシグナルが発火します。

「hoverEnabled」も参照してください 。

exited()

このシグナルは、マウスがマウス領域から出たときに発せられます。

デフォルトでは、このシグナルはボタンが押されている場合にのみ発火します。hoverEnabled をtrueに設定すると、マウスボタンが押されていない場合でもこのシグナルが発火します。

以下の例は、2つのMouseArea間のかなり典型的な関係を示しており、mouseArea2 がmouseArea1 の上に配置されています。mouseArea1 からmouseArea2 へマウスを移動させると、mouseArea1 がexited シグナルを発火します。

Rectangle {
    width: 400; height: 400
    MouseArea {
        id: mouseArea1
        anchors.fill: parent
        hoverEnabled: true
    }
    MouseArea {
        id: mouseArea2
        width: 100; height: 100
        anchors.centerIn: parent
        hoverEnabled: true
    }
}

一方、2つのMouseAreaを親子関係にした場合、mouseArea1 からmouseArea2 にマウスを移動させても、mouseArea1 はexited を発火しません。その代わりに、両方が同時にホバー状態にあるとみなされます。

hoverEnabledも参照してください 。

positionChanged(MouseEvent mouse)

このシグナルは、マウスの位置が変化したときに発生します。

mouse パラメータは、x座標やy座標、現在押されているボタンなど、マウスに関する情報を提供します。

デフォルトでは、このシグナルは、ボタンが押されている場合にのみ発火します。hoverEnabled を true に設定すると、マウスボタンが押されていない場合でもこのシグナルが発火します。

このシグナルを処理する場合、mouse パラメータのaccepted プロパティを変更しても何の影響もありません。

pressAndHold(MouseEvent mouse)

このシグナルは、長押し（現在は800ms）が行われた際に発生します。mouse パラメータは、押された位置（x座標およびy座標）や押されたボタンなど、長押しに関する情報を提供します。

このシグナルを処理する際、propagateComposedEvents プロパティがtrue に設定されていない限り、mouse パラメータのaccepted プロパティを変更しても効果はありません。

pressed(MouseEvent mouse)

この信号は、ボタンが押された際に発生します。mouse パラメータは、x座標、y座標、およびどのボタンが押されたかといった、ボタン操作に関する情報を提供します。

このシグナルを処理する際は、mouse パラメータのaccepted プロパティを使用して、このMouseArea が押下イベントおよびボタンが離されるまでの今後のすべてのマウスイベントを処理するかどうかを制御します。デフォルトでは、イベントを受け入れ、この の下にある他のMouseAreasがイベントを処理できないようにします。acceptedがfalseに設定されている場合、ボタンが次に押されるまで、このMouseArea にはそれ以上のイベントは送信されません。

released(MouseEvent mouse)

この信号は、クリックが解放されたときに発信されます。mouse パラメータは、クリックの解放位置（x座標とy座標）や、クリックが長押しされていたかどうかなど、クリックに関する情報を提供します。

このシグナルを処理する際、mouse パラメータのaccepted プロパティを変更しても何の効果もありません。

「canceled」も参照してください 。

wheel(WheelEvent wheel)

このシグナルは、マウスホイールおよびトラックパッドのスクロールジェスチャーの両方に対して発生します。

wheel パラメータは、x座標とy座標、現在押されているボタン、およびangleDeltaやpixelDeltaを含むホイールの動きに関する情報など、イベントに関する情報を提供します。