QML类型——MouseArea
正文
MouseArea鼠标事件处理区域。
详细介绍
MouseArea是不可见的对象，通常与可见对象结合使用，以便为该项目提供鼠标事件处理。
enabled属性用于开启和禁用鼠标操作，禁用时，鼠标区域无法响应所有鼠标事件。
虽然MouseArea是不可见的对象，但是具有visible属性，设置为false时，鼠标区域无法响应所有鼠标事件。
pressed只读属性标识着当前鼠标是否有按下操作。此属性通常用于用户界面中属性之间的绑定。
containsMouse只读属性标识着鼠标光标是否在鼠标区域内；默认情况下，只有在按住鼠标时才会有效。
最常用的是涉及到鼠标点击的事件：onClicked,onDoubleClicked,onPressed,onReleased和onPressAndHold。还有onWheel获取鼠标滚轮事件。
当鼠标区域与其他鼠标区域重叠，可以通过将propertyComposedEvents设置为true，将鼠标的基本事件自动传递给相同位置的其他MouseArea对象。
示例：（在一个Rectangle中使用MouseArea，单击矩形使其变成红色）
import QtQuick 2.0
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: {
if (mouse.button == Qt.RightButton)
parent.color = 'blue';
else
parent.color = 'red';
}
}
}
属性介绍
- mouseX: real
- mouseY: real
两个属性为鼠标光标的坐标。
如果hoverEnabled属性为false，则这些属性仅在按下按钮时才有效，并且即使将鼠标移动到该区域外，只要按住该按钮，这些属性将一直有效。（默认情况下为false）
如果hoverEnabled为true，则两个属性将在以下情况下有效：
1.没有按钮按下，但是鼠标在MouseArea区域内（containsMouse为true）。
2.即使按钮移出该区域，也一直按住按钮。
注意：坐标是相对于MouseArea的 - acceptedButtons: Qt::MouseButtons
指定MouseArea接受响应的鼠标按钮类型。
如果要对多个按钮做出响应，使用“|”组合Qt::MouseButtons。
MouseArea { acceptedButtons: Qt.LeftButton | Qt.RightButton }
如果要对所有鼠标按钮做出响应，则使用特殊值“Qt.AllButtons”。
MouseArea { acceptedButtons: Qt.AllButtons }
默认值为Qt.LeftButton。
- containsMouse: bool
此属性判断当前鼠标是否在MouseArea区域内。
警告：如果hoverEnabled为false，则只有当鼠标光标在MouseArea内按下鼠标按钮时，containsMouse才有效。 - containsPress: bool
此属性相当于组合属性（pressed && containsMouse），即判断当前按下鼠标按钮且鼠标光标位于MouseArea中。
此属性对于鼠标在MouseArea范围内按下时突出显示一个项目特别有用。 - cursorShape: Qt::CursorShape
此属性指定鼠标光标在MouseArea内的形状。
可用的光标形状有：
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
样式图：
[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-GV60wEwG-1594801841141)(leanote://file/getImage?fileId=5f0d1d4450f7571d32000005)]
如果只为MouseArea设置鼠标光标形状，而不响应鼠标事件，则将acceptedButtons设置为none。
MouseArea { cursorShape: Qt.IBeamCursor; acceptedButtons: Qt.NoButton }
默认值为Qt.ArrowCursor。
- drag group
- drag.active: bool
- drag.axis: enumeration
- drag.filterChildren: bool
- drag.maximumX: real
- drag.maximumY: real
- drag.minimumX: real
- drag.minimumY: real
- drag.target: Item
- drag.threshold: real
drag提供了一种使元素对象可拖动的方法。
drag.target 指定了要拖动的对象ID
drag.active 指定当前是否拖动目标。
drag.axis 指定是否可以水平（Drag.XAxis），垂直（Drag.YAxis）或任意方向（Drag.XAndYAxis）进行拖动。
drag.minimum和drag.maximum 限制可以沿着相应方向拖动目标的距离。
下面示例显示一个可以沿着X轴拖动的矩形，当矩形向右拖动时，其不透明度会降低：
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.axis方向拖动。例如，如果在上例中将rect设置为anchors.left或anchors.right，则该对象无法沿着X轴拖动。通过在onPressed处理程序中将anchor值设置为undefined可以避免此情况。
如果drag.filterChildren设置为true，则拖动可以覆盖后面的MouseArea。如下示例，使父MouseArea可以拖动，而子MouseArea处理点击。
drag.threshold指定了确定开始拖动操作的阈值（以像素为单位）。默认情况下，这和平台相关。
如果drag.smoothed为true，则只有在拖动操作结束后，才会移动目标。如果设置为false，则目标将直接移动到当前鼠标的位置。默认值为true。
如果要处理放置操作，可以参考Drag和DropArea
import QtQuick 2.0
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")
}
}
}
}
}
-
enabled: bool
此属性指定当前对象是否接受鼠标事件。
注意：由于历史原因，此属性不等同于Item.enabled。它仅影响鼠标事件，并且不会影响到子项。
默认值为true。 -
hoverEnabled: bool
此属性指定对于是否处理鼠标悬停事件。
默认情况下，仅响应于按钮事件或按下按钮时处理鼠标事件。悬停可以处理所有鼠标事件，即使没有按下鼠标按钮。
此属性影响containsMouse属性以及onEntered,onExited和onPositionChanged信号。 -
pressAndHoldInterval: int
此属性会覆盖在发出pressAndHold之前经过的时间（以毫秒为单位）。
如果没有明确的设置（或者后续重置），则该值会和QStyleHints::mousePressAndHoldInterval保持一致。
通常，利用应用程序样式来全局设置此属性就够了。当某些MouseArea需要不同的时间间隔时，应设置此属性。 -
pressed: bool
此属性判断当前是否按下了任何按钮（acceptedButtons）。 -
pressedButtons:MouseButtons
此属性指定当前按下的鼠标按钮类型：
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
}
}
- preventStealing: bool
此属性指定了是否可以从MouseArea截取鼠标事件。
如果在MouseArea中加入过滤子级的鼠标事件（例如Flickable），则鼠标事件可能会被截取。
如果父对象识别到任意动作（事件），将preventStealing设置为true，则不会截取鼠标事件。
注意：当某对象开始截取事件时，将preventStealing设置为true，直到下一次按下事件才会生效。
默认值为false。 - propagateComposedEvents: bool
此属性指定在MouseArea对象出现重叠的情况下，鼠标事件是否可以传递到下层。默认为false。
MouseArea包含多个组合事件：clicked,doubleClicked和pressAndHold，它们由基本的鼠标事件（如pressed）组成，并且与基本事件相比可以，传播方式有所不同。
如果此属性设置为true，则组合事件将自动传递到场景中相同位置的其他MouseArea。每个事件将按照堆栈顺序传递到下一个有效MouseArea，并向下传递此可视层次结构，直到最后一个MouseArea接受该事件为止。与pressed事件不同，如果没有处理程序，组合事件将不会被自动接受。
例如，下面是黄色的矩形包含一个蓝色的矩形。蓝色矩形是视觉堆栈层次中最顶层的对象，它将在黄色矩形上方直观的呈现。由于蓝色矩形将propagateComposedEvents设置为true，并且将所有接收到单击事件的对象MouseEvent::accepted设置为false，因此它将接收到的所有单击事件都传递到下方黄色矩形中。
MouseEvent::accepted为true时表示鼠标事件不会往下传递。
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: {
console.log("clicked blue")
mouse.accepted = false
}
}
}
}
单击蓝色矩形将导致其子MouseArea对象的onClicked处理函数被调用；然后该事件传递到黄色矩形的MouseArea，触发onClicked处理程序。
此属性大大简化了处理重叠MouseArea的组合事件。例如，如果要一个MouseArea处理clicked信号，而另一个处理pressAndHold信号，或者是一个MouseArea正常情况下处理clicked信号，但是在特殊条件下将其传递出去。
- scrollGestureEnabled: bool
此属性指定了当前MouseArea是否响应非鼠标设备的滚动事件，例如触控板上的2指轻弹手势。
信号
- canceled()
取消鼠标事件后发送的信号，因为另一个对象截取了鼠标事件。
该信号的用途：当有多个处理输入的MouseArea或Flickable内部有一个MouseArea时，该信号很有用。在后者情况下，如果您在onPressed信号处理程序中执行一些逻辑然后开始拖动，则Flickable将从MouseArea中截取鼠标事件。在此情况下，要在MouseArea对Flickable失去鼠标事件时重置逻辑，canceled需要另外处理released信号。 - clicked(mouse)
鼠标点击时发送该信号。只有在同一个MouseArea内响应pressed和released才算一次点击（鼠标按下，移动到MouseArea外，然后移动进来，再释放也被认可为一次点击）。
参数mouse提供了有关点击的信息，包含了点击释放的X和Y位置等。
处理此信号时，更改mouse参数的accepted属性是无效的，除非propagateComposedEvents属性设置为true。 - doubleClicked(mouse)
双击鼠标时发送该信号。
处理此信号时，如果将mouse参数的accepted属性设置为false，则第二次单击时将发送pressed/released/clicked信号。 - entered()
当鼠标进入MouseArea区域时，发送该信号。
默认为false，仅在当前按下按钮时才会发送该信号。设置为true时，鼠标进入即可发送信号。 - exited()
当鼠标离开MouseArea区域时，发送该信号。
默认为false，仅在按下鼠标按钮且移出MouseArea区域或者在MouseArea区域内点击时会发送信号。设置为true时，即使没有点击，只要鼠标移出MouseArea区域也会发送信号。
下面示例中显示两个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
}
}
相反，如果将两个MouseArea改为父子关系，将鼠标从mouseArea1移动到mouseArea2不会使mouseArea1发送exited信号。相反，它们将被视为同事hovered。
- positionChanged(mouse)
鼠标位置改变时发送该信号。
默认情况下，仅在按下按钮时才会发送该信号；将hoverEnabled设置为true才会发送该信号，即使没有按钮鼠标按钮。
处理该信号时，更改mouse参数的accepted属性无效。 - pressAndHold(mouse)
长按（默认为800毫秒）时发送该信号。
处理该信号，改变mouse参数的accepted属性是无效的，除非propagateComposedEvents属性为true。 - pressed(mouse)
按下时发送该信号。
处理该信号时，通过设置mouse参数的accepted属性来控制当前MouseArea是否处理pressed以及所有后续的鼠标事件，直到释放为止。
accepted默认为true，无法处理该MouseArea的其他事件。如果设置accepted为false，则在下次按下按钮之前，不会响应该MouseArea对象的任何事件。
处理函数：onPressed - released(mouse)
鼠标释放时发送信号。
处理此信号时，更改mouse的accepted属性无效。
处理函数：onReleased - wheel(wheel)
响应鼠标滚轮或触控板的滚动手势时发送信号。
处理函数：onWheel