Тип 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(mouse)
• doubleClicked(mouse)
• entered()
• exited()
• positionChanged(mouse)
• pressAndHold(mouse)
• pressed(mouse)
• released(mouse)
• wheel(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 - Ввод данных.

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

mouseX : вещественное

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

Если свойство 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.target : Элемент

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, если родительский элемент распознаёт жест, например, жест «флип». Если 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: {
                console.log("clicked blue")
                mouse.accepted = false
            }
        }
    }
}

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

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

scrollGestureEnabled : bool

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

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

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

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

canceled()

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

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

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

clicked(mouse)

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

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

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

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

doubleClicked(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 вызовет испускание сигнала exited в mouseArea1.

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

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

См. также hoverEnabled.

positionChanged(mouse)

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

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

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

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

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

pressAndHold(mouse)

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

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

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

pressed(mouse)

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

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

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

released(mouse)

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

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

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

См. также canceled.

wheel(wheel)

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

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

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