Тип 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: {
            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.

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

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

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

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

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

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

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

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

propagateComposedEvents : bool

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

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

Если propagateComposedEvents установлено в значение true, составные события будут автоматически распространяться на другие MouseAreas в том же месте в сцене. Каждое событие распространяется на следующий enabled 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.

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

scrollGestureEnabled : bool

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

По умолчанию это свойство имеет значение 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.