En esta página

HoverHandler QML Type

Controlador para el desplazamiento del ratón y la tableta. Más...

Import Statement: import QtQuick
Inherits:

SinglePointHandler

Propiedades

Señales

  • canceled(eventPoint point)
  • grabChanged(PointerDevice::GrabTransition transition, eventPoint point)

Descripción detallada

HoverHandler detecta cuando el cursor del ratón o el lápiz óptico de una tableta se sitúa sobre un elemento.

Una vinculación a la propiedad ` hovered ` es la forma más sencilla de reaccionar cuando el cursor entra o sale del elemento ` parent `. La propiedad ` point ` proporciona más detalles, incluida la posición del cursor. Las propiedades ` acceptedDevices`, ` acceptedPointerTypes` y ` acceptedModifiers ` pueden utilizarse para limitar el comportamiento a la detección de la posición del cursor sobre determinados tipos de dispositivos o mientras se mantiene pulsada una tecla modificadora.

La propiedad ` cursorShape ` permite cambiar el cursor siempre que ` hovered ` cambie a ` true`.

Véanse también los ejemplosde « MouseArea », « PointHandler » y «Qt Quick » - Gestores de puntero.

Documentación de la propiedad

acceptedDevices : flags

Los tipos de dispositivos de señalización que pueden activar el controlador del puntero.

Por defecto, esta propiedad está establecida en « PointerDevice.AllDevices ». Si se establece en una combinación «OR» de tipos de dispositivos, ignorará los eventos del puntero procedentes de los dispositivos que no coincidan.

Por ejemplo, se podría hacer que un elemento respondiera de una forma al pasar el ratón por encima y de otra al pasar el lápiz óptico por encima, con dos controladores:

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 | PointerDevice.TouchPad
        cursorShape: Qt.PointingHandCursor
    }
}

Los tipos de dispositivos disponibles son los siguientes:

ConstanteDescripción
PointerDevice.MouseUn ratón.
PointerDevice.TouchScreenUna pantalla táctil.
PointerDevice.TouchPadUn panel táctil o trackpad.
PointerDevice.StylusUn lápiz óptico en una tableta gráfica.
PointerDevice.AirbrushUn aerógrafo en una tableta gráfica.
PointerDevice.PuckUn digitalizador con retículo en una tableta gráfica.
PointerDevice.AllDevicesCualquier tipo de dispositivo señalador.

Nota: Todavíano todas las plataformas son capaces de distinguir entre el ratón y el panel táctil; y en aquellas que sí lo hacen, a menudo se desea que el comportamiento del ratón y del panel táctil sea el mismo.

Véase también QInputDevice::DeviceType.

acceptedModifiers : flags

Si se establece esta propiedad, el evento de paso del cursor solo se gestiona si se pulsan los modificadores de teclado especificados. El evento se ignora si no se pulsan dichos modificadores.

Esta propiedad está establecida de forma predeterminada en « Qt.KeyboardModifierMask », lo que hace que se gestionen los eventos de desplazamiento del cursor independientemente de las teclas modificadoras.

Por ejemplo, un « Item » podría tener dos controladores del mismo tipo, uno de los cuales solo se activaría si se pulsan los modificadores de teclado requeridos:

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

Los modificadores disponibles son los siguientes:

ConstanteDescripción
Qt.NoModifierNo se permite ninguna tecla modificadora.
Qt.ShiftModifierSe debe pulsar la tecla Mayús del teclado.
Qt.ControlModifierSe debe pulsar la tecla Ctrl del teclado.
Qt.AltModifierSe debe pulsar la tecla Alt del teclado.
Qt.MetaModifierSe debe pulsar la tecla Meta del teclado.
Qt.KeypadModifierSe debe pulsar una tecla del teclado numérico.
Qt.GroupSwitchModifierSe debe pulsar una tecla Mode_switch del teclado. Solo en X11 (a menos que se active en Windows mediante un argumento de línea de comandos).
Qt.KeyboardModifierMaskEl controlador ignora las teclas modificadoras.

Véase también Qt::KeyboardModifier.

acceptedPointerTypes : flags

Los tipos de dispositivos de señalación (genéricos, lápiz óptico, borrador, etc.) que pueden activar el controlador del puntero.

De forma predeterminada, esta propiedad está establecida en « PointerDevice.AllPointerTypes ». Si se establece en una combinación «OR» de tipos de dispositivos, se ignorarán los eventos que no coincidan con los tipos seleccionados.

Por ejemplo, se podría proporcionar retroalimentación cambiando el cursor en función de si un lápiz óptico o un borrador se encuentra sobre una tableta gráfica:

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

Los tipos de puntero disponibles son los siguientes:

ConstanteDescripción
PointerDevice.GenericUn ratón o un dispositivo que emula un ratón.
PointerDevice.FingerUn dedo sobre una pantalla táctil (es poco probable que se detecte la presencia del dedo).
PointerDevice.PenUn lápiz óptico sobre una tableta gráfica.
PointerDevice.EraserUn borrador en una tableta gráfica.
PointerDevice.CursorUn digitalizador con retícula en una tableta gráfica.
PointerDevice.AllPointerTypesCualquier tipo de dispositivo señalador.

Véase también QPointingDevice::PointerType.

active : bool [read-only]

Esto se cumple true siempre que este gestor de entrada haya asumido la responsabilidad exclusiva de gestionar uno o varios « eventPoints », al haber conseguido una «captura exclusiva» de dichos puntos. Esto significa que mantiene sus propiedades actualizadas en función de los movimientos de esos «eventPoints» y que manipula activamente sus « target » (si los hay).

blocking : bool [since 6.3]

Indica si este controlador impide que se pase el cursor al mismo tiempo sobre otros elementos o controladores situados detrás de él. Esta propiedad está des false ada de forma predeterminada.

Esta propiedad se introdujo en Qt 6.3.

cursorShape : Qt::CursorShape

Esta propiedad contiene la forma del cursor que aparecerá siempre que ` hovered ` tenga el valor ` true ` y ningún otro controlador la anule.

Las formas de cursor disponibles son:

  • Qt.ArrowCursor
  • Qt.UpArrowCursor
  • Qt.CrossCursor
  • Qt.WaitCursor
  • Qt.IBeamCursor
  • Qt.CursorVerticalDeTamaño
  • Qt.CursorDeTamañoHorizontal
  • Qt.SizeBDiagCursor
  • Qt.SizeFDiagCursor
  • Qt.SizeAllCursor
  • Qt.Cursor en blanco
  • Qt.CursorDivisiónVertical
  • Qt.CursorDivisiónHorizontal
  • Qt.CursorManoQueSeñala
  • Qt.CursorProhibido
  • Qt.Cursor «¿Qué es esto?»
  • Qt.CursorOcupado
  • Qt.Cursor de mano abierta
  • Qt.Cursor de mano cerrada
  • Qt.CursorDeArrastrarYCopiar
  • Qt.CursorArrastrarMover
  • Qt.DragLinkCursor

El valor por defecto de esta propiedad no está establecido, lo que permite que cualquier controlador activo en el mismo elemento padre determine la forma del cursor. Esta propiedad se puede restablecer a su estado inicial estableciéndola en ` undefined`.

Si algún controlador con « cursorShape » definido es « active », aparecerá ese cursor. De lo contrario, si el « HoverHandler » tiene definido « cursorShape », aparecerá ese cursor. En caso contrario, aparecerá el « cursor » del elemento padre.

Nota: Cuando esta propiedad no se ha establecido, o se ha establecido en undefined, si se lee el valor, devolverá Qt.ArrowCursor.

Véase también Qt::CursorShape y QQuickItem::cursor().

enabled : bool

Si se desactiva un « HoverHandler », rechazará todos los eventos y no se emitirá ninguna señal.

Si la propiedad « parent » de un « HoverHandler » tiene el valor « disabled », el « HoverHandler » seguirá reaccionando a los eventos de desplazamiento del cursor por defecto. Esto se debe a que los efectos de retroalimentación al pasar el cursor y las descripciones emergentes pueden resultar útiles incluso cuando un control está desactivado. Si deseas desactivar el « HoverHandler » cuando su elemento padre esté desactivado, puedes añadir un enlace:

Item {
    HoverHandler {
        enabled: parent.enabled
    }
}

grabPermissions : flags

Esta propiedad especifica los permisos cuando la lógica de este controlador decide hacerse cargo del control exclusivo, o cuando otro controlador le solicita que apruebe la toma de control o la cancelación del mismo.

ConstanteDescripción
PointerHandler.TakeOverForbiddenEste controlador no toma ni concede permisos de control a ningún tipo de elemento o controlador.
PointerHandler.CanTakeOverFromHandlersOfSameTypeEste controlador puede tomar el control exclusivo de otro controlador de la misma clase.
PointerHandler.CanTakeOverFromHandlersOfDifferentTypeEste controlador puede tomar el control exclusivo de cualquier tipo de controlador.
PointerHandler.CanTakeOverFromItemsEste controlador puede tomar el control exclusivo de cualquier tipo de elemento.
PointerHandler.CanTakeOverFromAnythingEste controlador puede tomar el control exclusivo de cualquier tipo de elemento o controlador.
PointerHandler.ApprovesTakeOverByHandlersOfSameTypeEste controlador concede permiso a otro controlador de la misma clase para que adquiera el control.
PointerHandler.ApprovesTakeOverByHandlersOfDifferentTypeEste controlador concede permiso a cualquier tipo de controlador para que adquiera el control.
PointerHandler.ApprovesTakeOverByItemsEste controlador permite que cualquier tipo de elemento adquiera el control.
PointerHandler.ApprovesCancellationEste controlador permitirá que su control se establezca en nulo.
PointerHandler.ApprovesTakeOverByAnythingEste controlador permite que cualquier tipo de elemento o controlador tome el control.

El valor por defecto es « PointerHandler.CanTakeOverFromItems | PointerHandler.CanTakeOverFromHandlersOfDifferentType | PointerHandler.ApprovesTakeOverByAnything », lo que permite la mayoría de los casos de toma de control, pero evita, por ejemplo, que dos «PinchHandlers» compitan por los mismos puntos táctiles.

hovered : bool [read-only]

Se cumple siempre que el cursor de cualquier dispositivo señalador (ratón o tableta) se encuentre dentro de los límites del elemento « parent », ampliados por el elemento « margin », si lo hubiera.

margin : real

El margen más allá de los límites del elemento « parent », dentro del cual un « eventPoint » puede activar este controlador. Por ejemplo, en un « PinchHandler » en el que el « target » es también el « parent », resulta útil establecer este valor en una distancia equivalente, como mínimo, a la mitad del ancho del dedo de un usuario típico, de modo que, si el « parent » se ha reducido a un tamaño muy pequeño, el gesto de pellizco siga siendo posible. O bien, si se coloca un botón basado en « TapHandler » cerca del borde de la pantalla, puede utilizarse para cumplir con la Ley de Fitts: reaccionar a los clics del ratón en el borde de la pantalla aunque el botón esté visualmente separado del borde por unos pocos píxeles.

El valor por defecto es 0.

Rectángulo con un área de margen alrededor para una detección táctil ampliada

parent : Item

El ` Item `, que es el ámbito del controlador; el `Item` en el que se declaró. El controlador gestionará los eventos en nombre de este `Item`, lo que significa que un evento de puntero es relevante si al menos uno de sus ` eventPoints ` tiene lugar dentro del interior del `Item`. Inicialmente, ` target() ` es el mismo, pero se puede reasignar.

Véase también target y QObject::parent().

point : handlerPoint [read-only]

El objeto « eventPoint » que se está gestionando actualmente. Cuando no hay ningún punto en proceso, este objeto se restablece a sus valores por defecto (todas las coordenadas son 0).

target : Item

El elemento que manipulará este controlador.

Por defecto, es el mismo que el « parent », es decir, el «Item» en el que se declara el controlador. Sin embargo, a veces puede resultar útil establecer el objetivo en un «Item» diferente, con el fin de gestionar eventos dentro de un «Item» pero manipular otro; o en « null », para desactivar el comportamiento por defecto y realizar otra acción en su lugar.

Documentación sobre señales

canceled(eventPoint point)

Si este gestor ya ha capturado el point indicado, esta señal se emite cuando otro gestor de punteros o elemento le arrebata la captura.

Nota: El controlador correspondiente es onCanceled.

grabChanged(PointerDevice::GrabTransition transition, eventPoint point)

Esta señal se emite cuando el «grab» ha sufrido algún cambio relevante para este controlador.

El verbo « transition » indica lo que ha ocurrido. El objeto « point » es el punto que se ha seleccionado o deseleccionado.

Los valores válidos para « transition » son:

ConstanteDescripción
PointerDevice.GrabExclusiveEste controlador ha asumido la responsabilidad principal de gestionar el point.
PointerDevice.UngrabExclusiveEste controlador ha renunciado a su control exclusivo anterior.
PointerDevice.CancelGrabExclusiveEl control exclusivo de este controlador ha sido asumido o cancelado.
PointerDevice.GrabPassiveEste controlador ha adquirido una retención pasiva para supervisar el point.
PointerDevice.UngrabPassiveEste controlador ha renunciado a su control pasivo anterior.
PointerDevice.CancelGrabPassiveEl control pasivo anterior de este gestor ha finalizado de forma anómala.

Nota: El controlador correspondiente es onGrabChanged.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.