Тип 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.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(мышь)
• doubleClicked(мышь)
• entered()
• exited()
• positionChanged(мышь)
• pressAndHold(мышь)
• pressed(мышь)
• released(мышь)
• 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 передают параметр мышь, содержащий дополнительную информацию об событии мыши, такую как позиция, кнопка и любые модификаторы клавиш.

Вот расширение предыдущего примера, который создает другой цвет при нажатии правой кнопкой мыши:

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. Этого можно избежать, установив значение привязки к undefined в обработчике 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.

pressAndHoldInterval : int

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

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

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

Этот параметр был введён в 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 будет испускаться только при получении события колеса от физической мыши, а события жестов прокрутки будут передаваться в любой другой Item, который их обрабатывает. Например, пользователь может выполнить жест "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(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, чтобы излучать этот сигнал даже когда ни одна кнопка мыши не нажата.

Приведенный ниже пример демонстрирует типичное взаимодействие двух MouseAreas, где 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
    }
}

Если вместо этого установить для двух MouseAreas родительско-дочерние отношения, то перемещение курсора мыши в mouseArea2 из mouseArea1 не заставит mouseArea1 излучить сигнал exited. Вместо этого они оба будут считаться одновременно наведёнными.

Соответствующий обработчик — 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.