HoverHandler QML Type

Handler for mouse and tablet hover. More...

Properties

Detailed Description

\inheritsSinglePointHandler \inqmlmodule QtQuick \ingroup qtquick-input-handlers

HoverHandler detects a hovering mouse or tablet stylus cursor.

A binding to the hovered property is the easiest way to react when the cursor enters or leaves the parent Item. The point property provides more detail, including the cursor position. The acceptedDevices, acceptedPointerTypes, and acceptedModifiers properties can be used to narrow the behavior to detect hovering of specific kinds of devices or while holding a modifier key.

The cursorShape property allows changing the cursor whenever hovered changes to true.

See also MouseArea, PointHandler, and Qt Quick Examples - Pointer Handlers.

Property Documentation

acceptedButtons : flags

\internal

This property is not used in HoverHandler.


acceptedDevices : flags

The types of pointing devices that can activate the pointer handler.

By default, this property is set to PointerDevice.AllDevices. If you set it to an OR combination of device types, it will ignore pointer events from the non-matching devices.

For example, an item could be made to respond to mouse hover in one way, and stylus hover in another way, with two handlers:

 import QtQuick

 Rectangle {
     width: 150; height: 50; radius: 3
     color: mouse.hovered ? "goldenrod" : stylus.hovered ? "tomato" : "wheat"

     HoverHandler {
         id: stylus
         acceptedDevices: PointerDevice.Stylus
         cursorShape: Qt.CrossCursor
     }

     HoverHandler {
         id: mouse
         acceptedDevices: PointerDevice.Mouse
         cursorShape: Qt.PointingHandCursor
     }
 }

The available device types are as follows:

ConstantDescription
PointerDevice.MouseA mouse.
PointerDevice.TouchScreenA touchscreen.
PointerDevice.TouchPadA touchpad or trackpad.
PointerDevice.StylusA stylus on a graphics tablet.
PointerDevice.AirbrushAn airbrush on a graphics tablet.
PointerDevice.PuckA digitizer with crosshairs, on a graphics tablet.
PointerDevice.AllDevicesAny type of pointing device.

See also QInputDevice::DeviceType.


acceptedModifiers : flags

If this property is set, a hover event is handled only if the given keyboard modifiers are pressed. The event is ignored without the modifiers.

This property is set to Qt.KeyboardModifierMask by default, resulting in handling hover events regardless of any modifier keys.

For example, an Item could have two handlers of the same type, one of which is enabled only if the required keyboard modifiers are pressed:

 import QtQuick

 Rectangle {
     width: 150; height: 50; radius: 3
     color: control.hovered ? "goldenrod" : shift.hovered ? "wheat" : "beige"

     HoverHandler {
         id: control
         acceptedModifiers: Qt.ControlModifier
         cursorShape: Qt.PointingHandCursor
     }

     HoverHandler {
         id: shift
         acceptedModifiers: Qt.ShiftModifier
         cursorShape: Qt.CrossCursor
     }
 }

The available modifiers are as follows:

ConstantDescription
Qt.NoModifierNo modifier key is allowed.
Qt.ShiftModifierA Shift key on the keyboard must be pressed.
Qt.ControlModifierA Ctrl key on the keyboard must be pressed.
Qt.AltModifierAn Alt key on the keyboard must be pressed.
Qt.MetaModifierA Meta key on the keyboard must be pressed.
Qt.KeypadModifierA keypad button must be pressed.
Qt.GroupSwitchModifierA Mode_switch key on the keyboard must be pressed. X11 only (unless activated on Windows by a command line argument).
Qt.KeyboardModifierMaskThe handler ignores modifier keys.

See also Qt::KeyboardModifier.


acceptedPointerTypes : flags

The types of pointing instruments (generic, stylus, eraser, and so on) that can activate the pointer handler.

By default, this property is set to PointerDevice.AllPointerTypes. If you set it to an OR combination of device types, it will ignore events from non-matching events.

For example, you could provide feedback by changing the cursor depending on whether a stylus or eraser is hovering over a graphics tablet:

 import QtQuick

 Rectangle {
     id: rect
     width: 150; height: 150

     HoverHandler {
         id: stylus
         acceptedPointerTypes: PointerDevice.Pen
         cursorShape: Qt.CrossCursor
     }

     HoverHandler {
         id: eraser
         acceptedPointerTypes: PointerDevice.Eraser
         cursorShape: Qt.BlankCursor
         target: Image {
             parent: rect
             source: "images/cursor-eraser.png"
             visible: eraser.hovered
             x: eraser.point.position.x
             y: eraser.point.position.y - 32
         }
     }
 }

The available pointer types are as follows:

ConstantDescription
PointerDevice.GenericA mouse or a device that emulates a mouse.
PointerDevice.FingerA finger on a touchscreen (hover detection is unlikely).
PointerDevice.PenA stylus on a graphics tablet.
PointerDevice.EraserAn eraser on a graphics tablet.
PointerDevice.CursorA digitizer with crosshairs, on a graphics tablet.
PointerDevice.AllPointerTypesAny type of pointing device.

See also QPointingDevice::PointerType.


blocking : bool

\since6.3

Whether this handler prevents other items or handlers behind it from being hovered at the same time. This property is false by default.


cursorShape : Qt::CursorShape

\since5.15 This property holds the cursor shape that will appear whenever hovered is true and no other handler is overriding it.

The available cursor shapes are:

  • 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

The default value of this property is not set, which allows any active handler on the same parent item to determine the cursor shape. This property can be reset to the initial condition by setting it to undefined.

If any handler with defined cursorShape is active, that cursor will appear. Else if the HoverHandler has a defined cursorShape, that cursor will appear. Otherwise, the cursor of parent item will appear.

Note: When this property has not been set, or has been set to undefined, if you read the value it will return Qt.ArrowCursor.

See also Qt::CursorShape and QQuickItem::cursor().


dragThreshold : flags

\internal

This property is not used in HoverHandler.


[read-only] hovered : bool

\readonly

Holds true whenever any pointing device cursor (mouse or tablet) is within the bounds of the parent Item, extended by the margin, if any.