En esta página

Qt Quick Manejadores de entrada

Qt Quick Los controladores de entrada son un conjunto de tipos QML que se utilizan para gestionar las « events » procedentes del teclado, la pantalla táctil, el ratón y el lápiz óptico devices en una interfaz de usuario. A diferencia de los elementos de gestión de eventos, como MouseArea y Flickable, los controladores de entrada son explícitamente no visuales, requieren menos memoria y están pensados para utilizarse en mayor número: una instancia de controlador por cada aspecto de la interacción. Cada instancia de controlador de entrada gestiona determinados eventos en nombre de su elemento « parent ». De este modo, se separan mejor los aspectos visuales y de comportamiento, y el comportamiento se construye mediante una composición más detallada.

Los «Ejemplos deQt Quick: controladores de puntero» muestran algunos casos de uso de los mismos.

La propiedad adjunta preexistente « Keys » es similar en concepto, por lo que nos referimos a los controladores orientados a dispositivos de puntero, junto con « Keys », como el conjunto de controladores de entrada. Esperamos ofrecer más casos de uso de propiedades adjuntas en futuras versiones de Qt XML.

Manejadores de entrada

DragHandler

Manejador para arrastrar

HoverHandler

Manejador para el paso del cursor del ratón y la tableta

KeyNavigation

Admite la navegación mediante las teclas de flecha

Keys

Proporciona gestión de teclas a los elementos

PinchHandler

Controlador para gestos de pellizco

PointHandler

Controlador para reaccionar ante un único punto de contacto

TapHandler

Controlador para toques y clics

WheelHandler

Manejo de la rueda del ratón

Características principales

Algunas de las características principales son:

  • Gestionar las pulsaciones de teclas dentro del elemento activo
  • Gestión de gestos, como toques o arrastres, independientemente del dispositivo del que procedan
  • Gestiona los gestos de diferentes clases de dispositivos de distintas formas
  • Cada elemento puede tener un número ilimitado de controladores

Manejadores que manipulan elementos

Algunos controladores añaden interactividad con solo declararse dentro de un elemento:

import QtQuick

Rectangle {
    width: 100
    height: 100
    color: "lightsteelblue"
    DragHandler { }
}

Propiedades y señales de los controladores

Todos los controladores tienen propiedades que se pueden utilizar en enlaces, y señales que se pueden gestionar para reaccionar ante las entradas:

import QtQuick

Rectangle {
    id: button
    signal clicked

    width: 150; height: 50; radius: 3
    color: tapHandler.pressed ? "goldenrod" : hoverHandler.hovered ? "wheat" : "beige"
    border.color: activeFocus ? "brown" : "transparent"
    focus: true

    HoverHandler {
        id: hoverHandler
    }

    TapHandler {
        id: tapHandler
        onTapped: button.clicked()
    }

    Keys.onEnterPressed: button.clicked()
}

Captura de puntero

Un concepto importante en relación con los controladores de puntero es el tipo de captura que realizan. El único tipo de captura que puede realizar un elemento es la captura exclusiva: por ejemplo, si se llama a ` QPointerEvent::setExclusiveGrabber()` (), los siguientes movimientos del ratón y el evento de liberación del ratón se enviarán únicamente a ese objeto. (Como solución alternativa a esta exclusividad, véase ` QQuickItem::setFiltersChildMouseEvents()` y ` QQuickItem::childMouseEventFilter()`). Sin embargo, los «Pointer Handlers» disponen de un mecanismo adicional: el « passive grab ». Los eventos de ratón y táctiles press se entregan recorriendo todos los «Items» en orden Z de arriba abajo: primero los «Handlers» hijos de cada «Item» y, a continuación, el propio « Item ». En el momento en que se transmite un evento de pulsación, un controlador puede realizar una captura pasiva o exclusiva, según sus necesidades. Si realiza una captura pasiva, tiene garantizado recibir las actualizaciones y la liberación, incluso si otros elementos o controladores de la escena realizan cualquier tipo de captura, ya sea pasiva o exclusiva. Algunos «Handlers» (como PointHandler) solo pueden funcionar con «grabs» pasivos; otros requieren «grabs» exclusivos; y otros pueden «permanecer a la espera» con «grabs» pasivos hasta que detectan que se está realizando un gesto, para luego pasar de un «grab» pasivo a uno exclusivo. El comportamiento de «grab» de TapHandler es configurable.

Cuando se solicita una transición de captura, PointerHandler::grabPermissions, QQuickItem::keepMouseGrab() y QQuickItem::keepTouchGrab() controlan si se permite dicha transición.

© 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.