En esta página

Eventos del ratón

Una forma más moderna de gestionar los eventos procedentes de todos los dispositivos señaladores, incluidos el ratón y la pantalla táctil, es mediante los «Input Handlers». Esta página describe el tipo original « Qt Quick » MouseArea, que se diseñó inicialmente para gestionar la entrada del ratón y que, posteriormente, comenzó a gestionar eventos de un solo toque (en forma de eventos sintéticos del ratón) en interfaces de usuario sencillas orientadas al tacto.

Tipos de ratón

Gestión de eventos del ratón

QML utiliza señales y controladores para gestionar las interacciones del ratón. En concreto, Qt Quick proporciona los tipos MouseArea y MouseEvent, que permiten a los desarrolladores definir funciones de devolución de llamada de JavaScript (también denominadas controladores de señales), las cuales aceptan eventos del ratón dentro de un área definida.

Definición de un área del ratón

El tipo « MouseArea » recibe eventos dentro de un área definida. Una forma rápida de definir esta área es anclar el « MouseArea » al área de su elemento padre mediante la propiedad « anchors.fill ». Si el elemento padre es un « Rectangle » (o cualquier componente « Item »), el « MouseArea » ocupará el área definida por las dimensiones del elemento padre. También es posible definir un área más pequeña o más grande que la del elemento padre.

Rectangle {
    id: button
    width: 100; height: 100

    MouseArea {
        anchors.fill: parent
        onClicked: console.log("button clicked")
    }
    MouseArea {
        width:150; height: 75
        onClicked: console.log("irregular area clicked")
    }
}

Recepción de eventos

El tipo « MouseArea » emite señales en respuesta a diferentes eventos del ratón. La documentación del tipo « MouseArea » describe estos gestos con mayor detalle:

  • cancelado
  • clicked
  • doubleClicked
  • entered
  • exited
  • cambio de posición
  • pulsado y mantenido
  • pulsado
  • soltado

Estas señales pueden tener funciones de devolución de llamada que se invocan cuando se emiten las señales.

    MouseArea {
        anchors.fill: parent
        onClicked: console.log("area clicked")
        onDoubleClicked: console.log("area double clicked")
        onEntered: console.log("mouse entered the area")
        onExited: console.log("mouse left the area")
    }

Activación de gestos

Algunos gestos del ratón y clics de botón deben habilitarse antes de que puedan enviar o recibir eventos. Ciertas propiedades de MouseArea y MouseEvent habilitan estos gestos.

Para escuchar (o ignorar explícitamente) un botón concreto del ratón, configura el botón correspondiente en la propiedad acceptedButtons.

Naturalmente, los eventos del ratón, como las pulsaciones de botones y las posiciones del ratón, se envían durante un clic del ratón. Por ejemplo, la propiedad containsMouse solo recuperará su valor correcto durante una pulsación del ratón. La propiedad hoverEnabled habilitará los eventos y el posicionamiento del ratón incluso cuando no haya pulsaciones de botones del ratón. Al establecer la propiedad hoverEnabled en true, se habilitarán a su vez las señales entered, exited y positionChanged, así como sus respectivos controladores de señales.

    MouseArea {
        hoverEnabled: true
        acceptedButtons: Qt.LeftButton | Qt.RightButton
        onEntered: console.log("mouse entered the area")
        onExited: console.log("mouse left the area")
    }

Además, para desactivar toda el área del ratón, establece la propiedad « MouseArea » enabled en « false ».

Objeto MouseEvent

Las señales y sus funciones de devolución de llamada reciben un objeto MouseEvent como parámetro. El objeto mouse contiene información sobre el evento del ratón. Por ejemplo, el botón del ratón que ha iniciado el evento se consulta a través de la propiedad mouse.button.

El objeto ` MouseEvent ` también puede ignorar un evento del ratón utilizando su propiedad ` accepted `.

Aceptación de señales adicionales

Muchas de las señales se envían varias veces para reflejar distintos eventos del ratón, como el doble clic. Para facilitar la clasificación de los clics del ratón, el objeto ` MouseEvent ` dispone de una propiedad ` accepted ` que permite desactivar la propagación del evento.

Para obtener más información sobre el sistema de eventos de QML, consulta el documento sobre señales y controladores, y el sistema de eventos.

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