MapMouseArea
The MapMouseArea item enables simple mouse handling. More...
Import Statement: | import QtLocation 5.0 |
Properties
- acceptedButtons : Qt::MouseButtons
- containsMouse : bool
- enabled : bool
- mouseX : real
- mouseY : real
- pressed : bool
- pressedButtons : MouseButton
Signals
- onClicked(MapMouseEvent mouse)
- onDoubleClicked(MapMouseEvent mouse)
- onEntered()
- onExited()
- onPositionChanged(MapMouseEvent mouse)
- onPressAndHold(MapMouseEvent mouse)
- onPressed(MapMouseEvent mouse)
- onReleased(MapMouseEvent mouse)
Methods
- coordinate mouseToCoordinate(MouseEvent event)
Detailed Description
Like a standard Qt Quick MouseArea, the MapMouseArea provides mouse handling for an item. Creating a normal Qt Quick MouseArea inside a map object type (for example MapPolygon) will result in undefined behavior due to the way in which Map objects are rendered, so MapMouseArea exists to provide this functionality instead.
The only exception to this is the MapQuickItem, which can have normal MouseArea objects defined within the sourceItem. See the documentation for MapQuickItem for more details.
MapMouseArea objects should only ever be used within a map object, such as a MapPolygon or MapQuickItem, and never within another Qt Quick component.
The enabled property of the MapMouseArea is used to enable and disable mouse handling for the proxied item. When disabled, the mouse area becomes transparent to mouse events.
The pressed read-only property indicates whether or not the user is holding down a mouse button over the mouse area. This property is often used in bindings between properties in a user interface.
Information about the mouse position and button clicks are provided via signals for which event handler properties are defined. The most commonly used handlers involve handling mouse presses and clicks: onClicked, onDoubleClicked, onPressed and onReleased.
Example Usage
The following example shows a map containing a MapCircle object. When the user clicks the MapCircle, a message is printed to the console.
Map { MapCircle { center { latitude: -27.5 longitude: 153 } radius: 100 MapMouseArea { anchors.fill: parent onClicked: { console.log("You clicked the circle!"); } } } }
Limitations
Some important limitations apply to the use of a MapMouseArea:
- The mouse event is guaranteed only to be valid for the duration of the signal handler (for example onPositionChanged, onClicked). Consequently the mouse event itself should not be stored. The main reason for this is to optimize memory usage; we do not want to allocate heap memory every time the mouse moves.
- Nested mouse areas are not supported (MapMouseArea { MapMouseArea {} }.
- If two or more MapMouseAreas overlap, the declaration order is significant (not for example 'z' value).
- Only one MapMouseArea per MapItem is supported, and it always fills the whole MapItem.
See also MapMouseEvent.
Property Documentation
This property holds the mouse buttons that the mouse area reacts to.
The available buttons are:
- Qt.LeftButton
- Qt.RightButton
- Qt.MiddleButton
To accept more than one button the flags can be combined with the "|" (or) operator:
MapMouseArea { acceptedButtons: Qt.LeftButton | Qt.RightButton }
The default value is Qt.LeftButton.
This property holds whether the mouse is currently inside the mouse area.
Warning: This property is not updated if the area moves under the mouse: containsMouse will not change. In addition, containsMouse will only be valid when the mouse is pressed.
This property holds whether the item accepts mouse events.
By default, this property is true.
These properties hold the screen coordinates of the mouse cursor.
These properties will only be valid while a button is pressed, and will remain valid as long as the button is held down even if the mouse is moved outside the area.
The screen coordinates are relative to the MapMouseArea.
These properties hold the screen coordinates of the mouse cursor.
These properties will only be valid while a button is pressed, and will remain valid as long as the button is held down even if the mouse is moved outside the area.
The screen coordinates are relative to the MapMouseArea.
This property holds the mouse buttons currently pressed.
It contains a bitwise combination of:
- Qt.LeftButton
- Qt.RightButton
- Qt.MiddleButton
See also acceptedButtons.
Signal Documentation
onClicked(MapMouseEvent mouse) |
This handler is called when there is a click. A click is defined as a press followed by a release, both inside the MapMouseArea (pressing, moving outside the MapMouseArea, and then moving back inside and releasing is also considered a click).
The mouse parameter provides information about the click, including the x and y position of the release of the click.
The accepted property of the MapMouseEvent parameter is ignored in this handler.
onDoubleClicked(MapMouseEvent mouse) |
This handler is called when there is a double-click (a press followed by a release followed by a press).
The mouse parameter provides information about the click, including the x and y position of the release of the click.
If the accepted property of the mouse parameter is set to false in the handler, the onPressed/onReleased/onClicked handlers will be called for the second click; otherwise they are suppressed. The accepted property defaults to true.
This handler is called when the mouse enters the mouse area.
The onEntered handler is only called while a button is pressed.
See also onExited.
This handler is called when the mouse exits the mouse area.
The onExited handler is only called while a button is pressed.
See also onEntered.
onPositionChanged(MapMouseEvent mouse) |
This handler is called when the mouse position changes.
The mouse parameter provides information about the mouse, including the x and y position, and any buttons currently pressed.
The accepted property of the MapMouseEvent parameter is ignored in this handler.
The onPositionChanged handler is only called while a button is pressed.
onPressAndHold(MapMouseEvent mouse) |
This handler is called when there is a long press (currently 800ms). The mouse parameter provides information about the press, including the x and y position of the press, and which button is pressed.
The accepted property of the MapMouseEvent parameter is ignored in this handler.
onPressed(MapMouseEvent mouse) |
This handler is called when there is a press.
The mouse parameter provides information about the press, including the x and y position and which button was pressed.
The accepted property of the MapMouseEvent parameter determines whether this MapMouseArea will handle the press and all future mouse events until release. The default is to accept the event and not allow other MapMouseArea beneath this one to handle the event. If accepted is set to false, no further events will be sent to this MapMouseArea until the button is next pressed.
onReleased(MapMouseEvent mouse) |
This handler is called when there is a release. The mouse parameter provides information about the click, including the x and y position of the release of the click.
The accepted property of the MapMouseEvent parameter is ignored in this handler.