QML Mouse EventsMouse Elements
Mouse Event HandlingQML uses signals and handlers to deliver mouse interactions. Specifically, the MouseArea and MouseEvent elements provide QML components with signal handlers to accept mouse events within a defined area. Defining a Mouse AreaThe MouseArea element receives events within a defined area. One quick way to define this area is to anchor the MouseArea to its parent's area using the anchors.fill property. If the parent is a Rectangle (or any Item component), then the MouseArea will fill the area defined by the parent's dimensions. Alternatively, an area smaller or larger than the parent is definable. Rectangle { id: button width: 100; height: 100 MouseArea { anchors.fill: parent onClicked: console.log("button clicked") } MouseArea { width:150; height: 75 onClicked: console.log("irregular area clicked") } } Receiving EventsThe MouseArea element provides signals and handlers to detect different mouse events. The MouseArea element documentation describes these gestures in greater detail:
These signals have signal handlers that are invoked when the signals are emitted. MouseArea { anchors.fill: parent onClicked: console.log("area clicked") onDoubleClicked: console.log("area double clicked") onEntered: console.log("mouse entered the area") onExited: console.log("mouse left the area") } Enabling GesturesSome mouse gestures and button clicks need to be enabled before they send or receive events. Certain MouseArea and MouseEvent properties enable these gestures. To listen to (or explicitly ignore) a certain mouse button, set the appropriate mouse button to the acceptedButtons property. Naturally, the mouse events, such as button presses and mouse positions, are sent during a mouse click. For example, the containsMouse property will only retrieve its correct value during a mouse press. The hoverEnabled will enable mouse events and positioning even when there are no mouse button presses. Setting the hoverEnabled property to true, in turn will enable the entered, exited, and positionChanged signal and their respective signal handlers. MouseArea { hoverEnabled: true acceptedButtons: Qt.LeftButton | Qt.RightButton onEntered: console.log("mouse entered the area") onExited: console.log("mouse left the area") } Additionally, to disable the whole mouse area, set the MouseArea element's enabled property to false. MouseEvent ObjectSignals and their handlers receive a MouseEvent object as a parameter. The mouse object contain information about the mouse event. For example, the mouse button that started the event is queried through the mouse.button property. The MouseEvent object can also ignore a mouse event using its accepted property. Accepting Further SignalsMany of the signals are sent multiple times to reflect various mouse events such as double clicking. To facilitate the classification of mouse clicks, the MouseEvent object has an accepted property to disable the event propagation. To learn more about QML's event system, please read the QML Signal and Handler Event System document. [Previous: Layouts using Anchors] [Next: Text Handling and Validators] © 2008-2011 Nokia Corporation and/or its subsidiaries. Nokia, Qt and their respective logos are trademarks of Nokia Corporation in Finland and/or other countries worldwide. All other trademarks are property of their respective owners. Privacy Policy Licensees holding valid Qt Commercial licenses may use this document in accordance with the Qt Commercial License Agreement provided with the Software or, alternatively, in accordance with the terms contained in a written agreement between you and Nokia. Alternatively, this document may be used under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. |