2.03

Mouse Handling (P0 | 2h)

Explanation of the contents of a topic page @ Topic reference page

Back to Week 2

Objective: Mouse handling with MouseArea

Comment: Mouse handling with MouseArea (later we'll discuss more interesting mouse handling)

Beginner

• What kind of GUI events does a mouse device provide?

Intermediate

• How do you capture mouse events?
• How do you use nested MouseAreas?
• How do you handle mouse buttons beyond the left mouse button?
• How do you drag items?
• How to visualize the mouse hover?

Expert

• How do you create a MouseArea with other than rectangular shapes?

Omitted

---

Course material content

http://doc.qt.io/qt-5/qml-qtquick-mousearea.html#details https://qmlbook.github.io/en/ch04/index.html#mousearea-element

To enable mouse interaction with elements, MouseArea can be used. It's an invisible rectangular item that can capture mouse events and can be nested into an element like so:

Comment: mouseArea nlooks different, which is good, but you should unify the use of inline code. Fix a invisible => an invisible. E: what does inline mean, the onClicked inline code or the whole code snippets? Tino: I mean code, which is in the text, not a separate example like below. For example, Keys is an attached property, where Keys is inline code. In some cases, you have used single quotes, but I think in some cases you have not.

 Rectangle {
     width: 100; height: 100
     color: "green"
 
     MouseArea {
         anchors.fill: parent
         onClicked: parent.color = 'red'
     }
 }

Now the logic of mouse handling is contained within the MouseArea item. This distinction is an important aspect of Qt Quick UIs, as this separates the input handling from visual presentations. This enables the visual items to be what ever the size they may be, but the input is only accepted within constraints defined in the input elements.

Generic mouse events using the left mouse button

By default MouseArea reacts to the left mouse button and signals onClicked. To set MouseArea react to other types of buttons, set the acceptedButtons property with desired Qt::MouseButton flag. Multiple flags can be combined with the | (or) operator. To access the currently pressed buttons, the & (and) operator can be used with the property pressedButtons.

In addition to the convenient onClicked handler, there are other handlers such as onPressed, onWheel or onPositionChanged that make it possible to handle more specific mouse events.

When emitted, many MouseArea signals pass in a mouse parameter that contains information about the mouse event, such as the position, button type and any key modifiers.

In this example we enable the left and right button of the mouse, and change the Rectangle color accordingly:

 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';
     }
 }

Visualizing the mouse hover

By default, MouseArea has handled mouse events when it has been clicked or buttons are held down, but it can also handle events when the mouse is currently hovering inside the area.

To enable hover event handling, the property hoverEnabled must be set to true. This affects the handlers onEntered, onExited and onPositionChanged. Handlers onEntered and onExited are signaled when the mouse enters or exits the area, and can be used to highlight or activate items. The onPositionChanged handler is signaled whenever the mouse moves inside the area.

This example demonstrates text following the cursor whenever the mouse enters the MouseArea:

 Text {
     id: cursorText
     text: "hover"
 }
 
 MouseArea {
     anchors.fill: parent
     hoverEnabled: true
     onPositionChanged: {
         cursorText.x = mouse.x
         cursorText.y = mouse.y
     } 
 }

Dragging items

In some UIs, it is beneficial to make some elements draggable, like volume sliders or images. MouseArea contains property drag that makes this possible.

drag itself has properties that are used to specify how the dragging is done.

1. drag.target specifies the id of the item to drag.
2. drag.active specifies if the target item is currently being dragged.
3. drag.axis specifies whether dragging can be done horizontally (Drag.XAxis), vertically (Drag.YAxis), or both (Drag.XAndYAxis)
4. drag.minimum and drag.maximum: how far the target can be dragged along the specified axes.

Instructions and description for the exercise of the topic

---

Exhaustive reference material mentioned in this topic

Further reading topics/links: