Тип QML MouseArea

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

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

Свойства

• acceptedButtons : Qt::MouseButtons
• containsMouse : bool
• containsPress : bool
• cursorShape : Qt::CursorShape
• drag
  • drag.target : Item
  • drag.active : bool
  • drag.axis : перечисление
  • drag.minimumX : вещественное
  • drag.maximumX : вещественное
  • drag.minimumY : вещественное
  • drag.maximumY : вещественное
  • drag.filterChildren : bool
  • 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: {
            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

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

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

containsPress : bool

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

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

Это свойство QML было добавлено в 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.target : Item

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

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

Если drag.filterChildren установлено в значение true, перетаскивание может переопределить дочерние MouseArea. Это позволяет родительскому элементу 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

Это свойство определяет, обрабатываются ли события наведения.

По умолчанию события мыши обрабатываются только в ответ на событие нажатия кнопки или при нажатии кнопки. Свойство hoverEnabled позволяет обрабатывать все события мыши даже при отсутствии нажатой кнопки мыши.

Это свойство влияет на свойство containsMouse и сигналы onEntered, onExited и onPositionChanged.

mouseX : real

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

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

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

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

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

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

mouseY : real

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

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

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

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

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

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

pressAndHoldInterval : int

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

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

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

Это свойство QML было введено в 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, если родительский элемент распознает жест, например, жест flick. Если preventStealing установлено в true, ни один элемент не будет красть события мыши.

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

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

propagateComposedEvents : bool

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

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

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

Например, ниже изображен желтый прямоугольник, содержащий синий прямоугольник. Синий прямоугольник — самый верхний элемент в иерархии порядка визуального расположения; он будет визуально отображаться поверх желтого прямоугольника. Поскольку синий прямоугольник устанавливает 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: {
                console.log("clicked blue")
                mouse.accepted = false
            }
        }
    }
}

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

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

scrollGestureEnabled : bool

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

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

Это свойство QML было введено в 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()

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

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

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

См. также hoverEnabled.

exited()

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

По умолчанию этот сигнал генерируется только если нажата кнопка мыши. Установите 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.