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

你可能感兴趣的:(QML,qml)