Тип QML MouseArea

Включает простую обработку мыши. Подробнее...

• Список всех членов, включая унаследованные

Свойства

• acceptedButtons : Qt::MouseButtons
• containsMouse : bool
• containsPress : bool
• cursorShape : Qt::CursorShape
• drag
  • drag.active : bool
  • drag.axis : перечисление
  • drag.filterChildren : bool
  • drag.maximumX : вещественное число
  • drag.maximumY : вещественное число
  • drag.minimumX : вещественное число
  • drag.minimumY : вещественное число
  • drag.smoothed : bool
  • drag.target : Item
  • drag.threshold : вещественное число
• enabled : bool
• hoverEnabled : bool
• mouseX : вещественное число
• mouseY : вещественное число
• 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 — это невидимый Item, но он имеет свойство visible. Когда оно установлено в false, область мыши становится прозрачной для событий мыши.

Чтение-только свойство pressed указывает, удерживает ли пользователь кнопку мыши над областью мыши. Это свойство часто используется в привязках между свойствами в пользовательском интерфейсе. Чтение-только свойство containsMouse указывает на наличие курсора мыши над областью мыши, но по умолчанию только когда удерживается кнопка мыши; см. документацию по containsMouse для получения дополнительной информации.

Информация о позиции мыши и нажатиях кнопок предоставляется через сигналы, для которых определены свойства обработчика событий. Наиболее часто используется обработка нажатий и щелчков мыши: onClicked, onDoubleClicked, onPressed, onReleased и onPressAndHold. Также возможно обрабатывать события колесика мыши с помощью сигнала onWheel.

Если область MouseArea перекрывает области других элементов MouseArea, можно выбрать распространение clicked, doubleClicked и pressAndHold событий на эти другие элементы, установив propagateComposedEvents в true и отклоняя события, которые должны быть распространены. См. документацию propagateComposedEvents для получения дополнительной информации.

По умолчанию элементы MouseArea сообщают только о нажатиях мыши, а не о перемещении курсора мыши. Установка свойства hoverEnabled гарантирует, что будут использоваться обработчики, определенные для onPositionChanged, onEntered и onExited, и что свойство containsMouse будет обновляться даже при отсутствии нажатия кнопок мыши.

Пример использования

В следующем примере используется MouseArea в Rectangle, который изменяет цвет Rectangle на красный при щелчке:

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: (mouse)=> {
            if (mouse.button == Qt.RightButton)
                parent.color = 'blue';
            else
                parent.color = 'red';
        }
    }
}

См. также MouseEvent, Пример MouseArea и Важные концепции в Qt Quick - Ввод пользователя.

Документация свойств

Эти свойства содержат координаты курсора мыши.

Если свойство hoverEnabled равно false, эти свойства будут действительны только при нажатии кнопки, и останутся действительными до тех пор, пока кнопка удерживается, даже если курсор мыши перемещен за пределы области.

По умолчанию это свойство равно false.

Если hoverEnabled равно true, эти свойства будут действительны, когда:

• ни одна кнопка не нажата, но курсор находится внутри MouseArea (containsMouse равно true).
• кнопка нажата и удерживается, даже если она перемещена за пределы области.

Координаты относительны к MouseArea.

acceptedButtons : Qt::MouseButtons

Это свойство содержит кнопки мыши, на которые реагирует область мыши.

Для указания того, что MouseArea будет реагировать на несколько кнопок, значения флагов Qt::MouseButtons объединяются с помощью оператора "|" (или):

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

Для указания того, что будут приняты все возможные кнопки мыши, может использоваться специальное значение 'Qt.AllButtons':

MouseArea { acceptedButtons: Qt.AllButtons }

Значение по умолчанию — Qt.LeftButton.

containsMouse : bool

Это свойство содержит значение, указывающее, находится ли курсор мыши в данный момент внутри области мыши.

Предупреждение: Если hoverEnabled равно false, containsMouse будет действителен только при нажатии кнопки мыши, когда курсор находится внутри MouseArea.

[since 5.4] containsPress : bool

Это свойство-удобство, эквивалентное pressed && containsMouse, т. е. оно содержит значение, указывающее, нажата ли какая-либо из кнопок acceptedButtons, и находится ли курсор мыши в данный момент внутри MouseArea.

Это свойство особенно полезно для выделения элемента, когда кнопка мыши удерживается внутри его границ.

Это свойство было добавлено в Qt 5.4.

См. также 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.SplitVCursor
• Qt.SplitHCursor
• Qt.PointingHandCursor
• Qt.ForbiddenCursor
• Qt.WhatsThisCursor
• Qt.BusyCursor
• Qt.OpenHandCursor
• Qt.ClosedHandCursor
• Qt.DragCopyCursor
• Qt.DragMoveCursor
• Qt.DragLinkCursor

Для того, чтобы установить форму курсора мыши только для области без реакции на события мыши, установите acceptedButtons в значение none:

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

Значение по умолчанию — Qt.ArrowCursor.

См. также Qt::CursorShape.

drag.active : bool

drag предоставляет удобный способ сделать элемент перетаскиваемым.

• drag.target задаёт идентификатор элемента, который нужно перетащить.
• drag.active указывает, в настоящее время ли целевой элемент перетаскивается.
• drag.axis определяет, можно ли выполнять перетаскивание по горизонтали (Drag.XAxis), по вертикали (Drag.YAxis) или по обеим осям (Drag.XAndYAxis)
• drag.minimum и drag.maximum ограничивают, насколько далеко можно перетащить целевой элемент вдоль соответствующих осей.

В следующем примере показан Rectangle, который можно перетаскивать по оси 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. Например, если anchors.left или anchors.right были установлены для rect в приведённом выше примере, его нельзя перетаскивать по оси X. Этому можно избежать, установив значение закрепления в undefined в обработчике onPressed.

Если drag.filterChildren установлено в true, перетаскивание может переопределить дочерние MouseAreas. Это позволяет родительскому MouseArea обрабатывать перетаскивания, например, в то время как дочерние элементы обрабатывают щелчки:

drag.threshold определяет порог в пикселях, при котором должна начаться операция перетаскивания. По умолчанию он связан со значением, зависящим от платформы. Этот свойство было добавлено в Qt Quick 2.2.

Если drag.smoothed равно true, целевой элемент будет перемещён только после начала операции перетаскивания. Если оно равно false, целевой элемент будет сразу перемещён в текущую позицию курсора мыши. По умолчанию это свойство равно true. Это свойство было добавлено в Qt Quick 2.4

См. присоединённое свойство 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.

[since 5.9] pressAndHoldInterval : int

Это свойство переопределяет время в миллисекундах, которое должно пройти до того, как будет отправлен сигнал pressAndHold.

Если явно не задано — или после сброса — значение соответствует QStyleHints::mousePressAndHoldInterval.

Обычно достаточно установить это свойство глобально с помощью подсказки стиля приложения. Это свойство следует использовать, когда требуются различные интервалы для определённых MouseAreas.

Это свойство было введено в Qt 5.9.

См. также pressAndHold.

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
    }
}

Примечание: это свойство обрабатывает только кнопки, указанные в acceptedButtons.

См. также acceptedButtons.

preventStealing : bool

Это свойство определяет, могут ли события мыши быть украдены у этого MouseArea.

Если MouseArea размещён внутри элемента, который фильтрует дочерние события мыши, например, Flickable, события мыши могут быть украдены у MouseArea, если родительский элемент распознаёт жест, например, жест фликера. Если preventStealing установлено в true, ни один элемент не украдёт события мыши.

Обратите внимание, что установка preventStealing в значение true после того, как элемент начал воровать события, не повлияет до следующего события нажатия.

По умолчанию это свойство равно false.

propagateComposedEvents : bool

Это свойство определяет, будут ли составные события мыши автоматически передаваться другим MouseAreas, которые перекрываются с этим MouseArea, но имеют более низкий порядок визуального расположения. По умолчанию это свойство равно false.

MouseArea содержит несколько составных событий: clicked, doubleClicked и pressAndHold. Они состоят из базовых событий мыши, таких как pressed, и могут быть переданы иначе по сравнению с базовыми событиями.

Если propagateComposedEvents установлено в true, составные события будут автоматически передаваться другим MouseAreas в том же месте сцены. Каждое событие передаётся следующему enabled MouseArea под ним в порядке стека, продвигаясь вниз по этой визуальной иерархии, пока MouseArea не примет событие. В отличие от pressed событий, составные события не будут автоматически приняты, если обработчик отсутствует.

Например, ниже представлен жёлтый Rectangle, который содержит синий Rectangle. Синий прямоугольник — это самый верхний элемент в иерархии визуального порядка расположения; он будет визуализирован поверх жёлтого прямоугольника. Поскольку синий прямоугольник устанавливает propagateComposedEvents в true, а также устанавливает MouseEvent::accepted в false для всех полученных clicked событий, любые 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
            }
        }
    }
}

Нажатие на синий прямоугольник вызовет обработчик onClicked его дочернего MouseArea; затем событие будет передано MouseArea жёлтого прямоугольника, вызвав его собственный обработчик onClicked.

Это свойство значительно упрощает использование случаев, когда вы хотите, чтобы перекрывающиеся MouseAreas обрабатывали составные события вместе. Например, если вы хотите, чтобы один MouseArea обрабатывал clicked сигналы, а другой — pressAndHold, или если вы хотите, чтобы один MouseArea обрабатывал clicked большую часть времени, но передавал его, когда выполняются определённые условия.

[since 5.5] scrollGestureEnabled : bool

Это свойство управляет тем, отвечает ли этот MouseArea на жесты прокрутки с устройств, не использующих мышь, таких как 2-пальцевый жест прокрутки на трекпаде. Если установлено в false, сигнал wheel будет испускаться только при поступлении события колёсика от физической мыши, в то время как события жестов прокрутки будут передаваться любому другому элементу, который будет их обрабатывать. Например, пользователь может выполнить жест прокрутки, пока курсор находится над элементом, содержащим MouseArea, намереваясь взаимодействовать с Flickable, который находится под ним. Установка этого свойства в false позволит PinchArea обрабатывать колесо мыши или жест масштабирования, в то время как Flickable обрабатывает жест прокрутки.

По умолчанию это свойство равно true.

Это свойство было введено в Qt 5.5.

Документация по сигналам

canceled()

Этот сигнал испускается, когда события мыши были отменены, потому что другой элемент забрал обработку события мыши.

Этот сигнал предназначен для расширенного использования: он полезен, когда существует более одного MouseArea, обрабатывающего ввод, или когда имеется MouseArea внутри Flickable. В последнем случае, если вы выполняете некоторый код в обработчике сигнала onPressed и затем начинаете перетаскивание, Flickable украдёт обработку мыши у MouseArea. В таких случаях для сброса кода, когда MouseArea потерял обработку мыши в пользу Flickable, следует обрабатывать canceled в дополнение к released.

Примечание: Соответствующий обработчик — onCanceled.

clicked(MouseEvent mouse)

Этот сигнал испускается при щелчке. Щелчок определяется как нажатие, за которым следует отпускание, оба внутри MouseArea (нажатие, перемещение за пределами MouseArea и затем возврат внутрь и отпускание также считаются щелчком).

Параметр mouse содержит информацию о щелчке, включая координаты x и y отпускания щелчка и то, удерживался ли щелчок.

При обработке этого сигнала изменение свойства accepted параметра mouse не оказывает никакого влияния, если свойство propagateComposedEvents не равно true.

Примечание: Соответствующий обработчик — onClicked.

doubleClicked(MouseEvent mouse)

Этот сигнал излучается при двойном щелчке (нажатие, отпускание, повторное нажатие). Параметр mouse предоставляет информацию о щелчке, включая координаты x и y отпускания щелчка и информацию о том, удерживалась ли кнопка.

При обработке этого сигнала, если свойство accepted параметра mouse установлено в false, сигналы pressed/released/clicked будут излучаться для второго щелчка; в противном случае они подавляются. Свойство accepted по умолчанию равно true.

Примечание: Соответствующий обработчик — onDoubleClicked.

entered()

Этот сигнал излучается, когда указатель мыши входит в область MouseArea.

По умолчанию этот сигнал излучается только если кнопка мыши нажата. Установите hoverEnabled в true, чтобы этот сигнал излучался даже когда ни одна кнопка мыши не нажата.

Примечание: Соответствующий обработчик — onEntered.

См. также hoverEnabled.

exited()

Этот сигнал излучается, когда указатель мыши выходит из области MouseArea.

По умолчанию этот сигнал излучается только если кнопка мыши нажата. Установите hoverEnabled в true, чтобы этот сигнал излучался даже когда ни одна кнопка мыши не нажата.

В примере ниже показаны типичные отношения между двумя объектами MouseArea, где mouseArea2 расположен над mouseArea1. Перемещение указателя мыши в mouseArea2 из mouseArea1 приведет к тому, что 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, перемещение указателя мыши в mouseArea2 из mouseArea1 не приведет к тому, что mouseArea1 излучит сигнал exited. Вместо этого оба объекта будут считаться одновременно находящимися под указателем.

Примечание: Соответствующий обработчик — onExited.

См. также hoverEnabled.

positionChanged(MouseEvent mouse)

Этот сигнал излучается при изменении позиции указателя мыши.

Параметр mouse предоставляет информацию о мыши, включая координаты x и y, и какие кнопки в данный момент нажаты.

По умолчанию этот сигнал излучается только если кнопка мыши нажата. Установите hoverEnabled в true, чтобы этот сигнал излучался даже когда ни одна кнопка мыши не нажата.

При обработке этого сигнала изменение свойства accepted параметра mouse не оказывает никакого влияния.

Примечание: Соответствующий обработчик — onPositionChanged.

pressAndHold(MouseEvent mouse)

Этот сигнал излучается при удержании нажатой кнопки мыши в течение определенного времени (в данный момент 800 мс). Параметр mouse предоставляет информацию о нажатии, включая координаты x и y нажатия и нажатую кнопку.

При обработке этого сигнала изменение свойства accepted параметра mouse не оказывает никакого влияния, если свойство propagateComposedEvents равно true.

Примечание: Соответствующий обработчик — onPressAndHold.

pressed(MouseEvent mouse)

Этот сигнал излучается при нажатии кнопки мыши. Параметр mouse предоставляет информацию о нажатии, включая координаты x и y и нажатую кнопку.

При обработке этого сигнала используйте свойство accepted параметра mouse, чтобы контролировать, обрабатывает ли данная область MouseArea нажатие и все последующие события мыши до отпускания. По умолчанию событие принимается, и другие MouseArea под ним не обрабатывают его. Если accepted установлено в false, никакие дальнейшие события не будут отправлены в эту MouseArea до следующего нажатия кнопки.

Примечание: Соответствующий обработчик — onPressed.

released(MouseEvent mouse)

Этот сигнал излучается при отпускании кнопки мыши. Параметр mouse предоставляет информацию о щелчке, включая координаты x и y отпускания щелчка и информацию о том, удерживалась ли кнопка.

При обработке этого сигнала изменение свойства accepted параметра mouse не оказывает никакого влияния.

Примечание: Соответствующий обработчик — onReleased.

См. также canceled.

wheel(WheelEvent wheel)

Этот сигнал излучается в ответ на жесты прокрутки колесом мыши или трекпада.

Параметр wheel предоставляет информацию о событии, включая координаты x и y, любые нажатые кнопки и информацию о перемещении колеса, включая angleDelta и pixelDelta.

Примечание: Соответствующий обработчик — onWheel.