Тип QML MouseArea

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

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

Свойства

• acceptedButtons : Qt::MouseButtons
• containsMouse : bool
• containsPress : bool
• cursorShape : Qt::CursorShape
• drag
  • drag.active : bool
  • drag.axis : перечисление
  • 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 — это невидимый элемент 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

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

[since 5.4] containsPress : bool

Это вспомогательное свойство, эквивалентное pressed && containsMouse, т. е. оно содержит значение true, если любая из 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 ограничивают, насколько далеко целевой элемент можно перетащить вдоль соответствующих осей.

Следующий пример отображает Прямоугольник, который можно перетаскивать по оси 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.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

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

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

hoverEnabled : bool

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

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

Это свойство влияет на свойство 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.

preventStealing : bool

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

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

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

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

propagateComposedEvents : bool

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

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

Если propagateComposedEvents установлено в значение true, составленные события будут автоматически распространяться на другие MouseAreas в том же месте в сцене. Каждое событие распространяется на следующий активированный 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: (mouse)=> {
                console.log("clicked blue")
                mouse.accepted = false
            }
        }
    }
}

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

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

[since 5.5] scrollGestureEnabled : bool

Это свойство управляет тем, реагирует ли этот MouseArea на жесты прокрутки от устройств, не являющихся мышью, например, на двухпальный жест прокрутки на трекпаде. Если установлено в 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.