Тип QML MouseArea

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

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

Свойства

• acceptedButtons : Qt::MouseButtons
• containsMouse : bool
• containsPress : bool
• cursorShape : Qt::CursorShape
• drag
  • drag.target : Item
  • drag.active : bool
  • drag.axis : перечисление
  • drag.minimumX : real
  • drag.maximumX : real
  • drag.minimumY : real
  • drag.maximumY : real
  • drag.filterChildren : bool
  • drag.threshold : real
• enabled : bool
• hoverEnabled : bool
• mouseX : real
• mouseY : real
• 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 используется для включения и отключения обработки мыши для проксируемого элемента. При отключении область мыши становится прозрачной для событий мыши.

Чтение только свойство 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

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

Предупреждение: Это свойство не обновляется, если область перемещается под мышью: containsMouse не изменится. Кроме того, если hoverEnabled ложь, 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. Этого можно избежать, установив значение закрепления на undefined в обработчике 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

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

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

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 в том же месте в сцене. Каждое событие распространяется на следующий активированный 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 на жесты прокрутки от устройств, не являющихся мышью, таких как жест прокрутки двумя пальцами на трекпаде. Если установлено в false, сигнал wheel будет генерироваться только при событии прокрутки от физической мыши с колесиком, в то время как события жестов прокрутки будут проходить к любому другому элементу, который их обработает. Например, пользователь может выполнить жест прокрутки, когда курсор находится над элементом, содержащим MouseArea, чтобы взаимодействовать с Flickable, который находится ниже. Установка этого свойства в false позволит PinchArea обработать событие колесика или жест pinch, в то время как Flickable обработает жест flick.

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

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

doubleClicked(MouseEvent 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(MouseEvent mouse)

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

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

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

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

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

pressAndHold(MouseEvent mouse)

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

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

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

pressed(MouseEvent mouse)

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

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

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

released(MouseEvent mouse)

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

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

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

См. также canceled.

wheel(WheelEvent wheel)

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

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

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