Тип 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
• 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 — Ввод данных.

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

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

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

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

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

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

См. также hoverEnabled.

exited()

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

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