HoverHandler QML Type
Controlador para el desplazamiento del ratón y la tableta. Más...
| Import Statement: | import QtQuick |
| Inherits: |
Propiedades
- acceptedDevices : flags
- acceptedModifiers : flags
- acceptedPointerTypes : flags
- active : bool
- blocking : bool
(since 6.3) - cursorShape : Qt::CursorShape
- enabled : bool
- grabPermissions : flags
- hovered : bool
- margin : real
- parent : Item
- point : handlerPoint
- target : Item
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:
| Constante | Descripción |
|---|---|
PointerDevice.Mouse | Un ratón. |
PointerDevice.TouchScreen | Una pantalla táctil. |
PointerDevice.TouchPad | Un panel táctil o trackpad. |
PointerDevice.Stylus | Un lápiz óptico en una tableta gráfica. |
PointerDevice.Airbrush | Un aerógrafo en una tableta gráfica. |
PointerDevice.Puck | Un digitalizador con retículo en una tableta gráfica. |
PointerDevice.AllDevices | Cualquier 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:
| Constante | Descripción |
|---|---|
Qt.NoModifier | No se permite ninguna tecla modificadora. |
Qt.ShiftModifier | Se debe pulsar la tecla Mayús del teclado. |
Qt.ControlModifier | Se debe pulsar la tecla Ctrl del teclado. |
Qt.AltModifier | Se debe pulsar la tecla Alt del teclado. |
Qt.MetaModifier | Se debe pulsar la tecla Meta del teclado. |
Qt.KeypadModifier | Se debe pulsar una tecla del teclado numérico. |
Qt.GroupSwitchModifier | Se 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.KeyboardModifierMask | El 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:
| Constante | Descripción |
|---|---|
PointerDevice.Generic | Un ratón o un dispositivo que emula un ratón. |
PointerDevice.Finger | Un dedo sobre una pantalla táctil (es poco probable que se detecte la presencia del dedo). |
PointerDevice.Pen | Un lápiz óptico sobre una tableta gráfica. |
PointerDevice.Eraser | Un borrador en una tableta gráfica. |
PointerDevice.Cursor | Un digitalizador con retícula en una tableta gráfica. |
PointerDevice.AllPointerTypes | Cualquier 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.
| Constante | Descripción |
|---|---|
PointerHandler.TakeOverForbidden | Este controlador no toma ni concede permisos de control a ningún tipo de elemento o controlador. |
PointerHandler.CanTakeOverFromHandlersOfSameType | Este controlador puede tomar el control exclusivo de otro controlador de la misma clase. |
PointerHandler.CanTakeOverFromHandlersOfDifferentType | Este controlador puede tomar el control exclusivo de cualquier tipo de controlador. |
PointerHandler.CanTakeOverFromItems | Este controlador puede tomar el control exclusivo de cualquier tipo de elemento. |
PointerHandler.CanTakeOverFromAnything | Este controlador puede tomar el control exclusivo de cualquier tipo de elemento o controlador. |
PointerHandler.ApprovesTakeOverByHandlersOfSameType | Este controlador concede permiso a otro controlador de la misma clase para que adquiera el control. |
PointerHandler.ApprovesTakeOverByHandlersOfDifferentType | Este controlador concede permiso a cualquier tipo de controlador para que adquiera el control. |
PointerHandler.ApprovesTakeOverByItems | Este controlador permite que cualquier tipo de elemento adquiera el control. |
PointerHandler.ApprovesCancellation | Este controlador permitirá que su control se establezca en nulo. |
PointerHandler.ApprovesTakeOverByAnything | Este 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.

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:
| Constante | Descripción |
|---|---|
PointerDevice.GrabExclusive | Este controlador ha asumido la responsabilidad principal de gestionar el point. |
PointerDevice.UngrabExclusive | Este controlador ha renunciado a su control exclusivo anterior. |
PointerDevice.CancelGrabExclusive | El control exclusivo de este controlador ha sido asumido o cancelado. |
PointerDevice.GrabPassive | Este controlador ha adquirido una retención pasiva para supervisar el point. |
PointerDevice.UngrabPassive | Este controlador ha renunciado a su control pasivo anterior. |
PointerDevice.CancelGrabPassive | El 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.