En esta página

MouseArea QML Type

Permite un manejo sencillo del ratón. Más...

Import Statement: import QtQuick
Inherits:

Item

Propiedades

Señales

Descripción detallada

Un MouseArea es un elemento invisible que suele utilizarse junto con un elemento visible para gestionar los eventos del ratón de dicho elemento. Al actuar, en la práctica, como un proxy, la lógica de gestión del ratón puede contenerse dentro de un elemento MouseArea.

La propiedad « enabled » se utiliza para activar y desactivar el manejo del ratón para el elemento proxy. Cuando está desactivada, el área del ratón se vuelve transparente a los eventos del ratón.

MouseArea es un elemento invisible, pero tiene una propiedad visible. Cuando se establece en «false», el área del ratón se vuelve transparente a los eventos del ratón.

La propiedad de solo lectura ` pressed ` indica si el usuario mantiene pulsado un botón del ratón sobre el área del ratón. Esta propiedad se utiliza a menudo en enlaces entre propiedades de una interfaz de usuario. La propiedad de solo lectura ` containsMouse ` indica la presencia del cursor del ratón sobre el área del ratón, pero, por defecto, solo cuando se mantiene pulsado un botón del ratón; consulta la documentación de ` containsMouse ` para obtener más detalles.

La información sobre la posición del ratón y los clics de los botones se proporciona a través de señales para las que se definen propiedades de controlador de eventos. Las más utilizadas se refieren al manejo de pulsaciones y clics del ratón: onClicked, onDoubleClicked, onPressed, onReleased y onPressAndHold. También es posible gestionar eventos de la rueda del ratón mediante la señal onWheel.

Si un MouseArea se superpone con el área de otros elementos MouseArea, puedes optar por propagar los eventos « clicked », « doubleClicked » y « pressAndHold » a estos otros elementos estableciendo « propagateComposedEvents » en «true» y rechazando los eventos que no deban propagarse. Consulta la documentación de propagateComposedEvents para obtener más detalles.

Por defecto, los elementos MouseArea solo informan de los clics del ratón y no de los cambios en la posición del cursor del ratón. Al establecer la propiedad hoverEnabled se garantiza que se utilicen los controladores definidos para onPositionChanged, onEntered y onExited, y que la propiedad containsMouse se actualice incluso cuando no se pulse ningún botón del ratón.

Ejemplo de uso

Rectángulos rojos y verdes que muestran los estados de clic y al pasar el cursor por encima

El siguiente ejemplo utiliza un MouseArea en un ` Rectangle ` que cambia el color de ` Rectangle ` a rojo al hacer clic:

import QtQuick

Rectangle {
    width: 100; height: 100
    color: "green"

    MouseArea {
        anchors.fill: parent
        onClicked: { parent.color = 'red' }
    }
}

Muchas señales de MouseArea pasan un parámetro ` mouse ` que contiene información adicional sobre el evento del ratón, como la posición, el botón y cualquier modificador de teclado.

A continuación se muestra una ampliación del ejemplo anterior que genera un color diferente al hacer clic con el botón derecho en el área:

Rectangle {
    width: 100; height: 100
    color: "green"

    MouseArea {
        anchors.fill: parent
        acceptedButtons: Qt.LeftButton | Qt.RightButton
        onClicked: (mouse)=> {
            if (mouse.button == Qt.RightButton)
                parent.color = 'blue';
            else
                parent.color = 'red';
        }
    }
}

Véase también MouseEvent, el ejemplo de MouseArea y «Conceptos importantes en Qt Quick: Entrada del usuario».

Documentación de propiedades

acceptedButtons : Qt::MouseButtons

Esta propiedad indica los botones del ratón a los que reacciona el área del ratón.

Para especificar que la propiedad « MouseArea » reaccione a varios botones, los valores de los indicadores de « Qt::MouseButtons » se combinan utilizando el operador «|» (o):

MouseArea { acceptedButtons: Qt.LeftButton | Qt.RightButton }

Para indicar que se deben aceptar todos los botones posibles del ratón, se puede utilizar el valor especial «Qt.AllButtons»:

MouseArea { acceptedButtons: Qt.AllButtons }

El valor por defecto es Qt.LeftButton.

containsMouse : bool [read-only]

Esta propiedad indica si el ratón se encuentra actualmente dentro del área del ratón.

Advertencia: Si hoverEnabled es false, containsMouse será true cuando se pulse el botón del ratón mientras el cursor se encuentre dentro de MouseArea. Sin embargo, si se establece mouse.accepted = false en un controlador onPressed, containsMouse seguirá siendo false, ya que la pulsación fue rechazada.

containsPress : bool [read-only]

Se trata de una propiedad de conveniencia equivalente a ` pressed && containsMouse`, es decir, se cumple si alguna de las teclas ` acceptedButtons ` está pulsada en ese momento y el ratón se encuentra dentro de la zona ` MouseArea`.

Esta propiedad resulta especialmente útil para resaltar un elemento mientras se mantiene pulsado el ratón dentro de sus límites.

Véanse también « pressed » y « containsMouse ».

cursorShape : Qt::CursorShape

Esta propiedad define la forma del cursor para esta zona del ratón. Ten en cuenta que, en plataformas que no muestran el cursor del ratón, es posible que esto no tenga ningún efecto.

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.Cursor de división horizontal
  • Qt.CursorManoSeñalando
  • Qt.CursorProhibido
  • Qt.CursorDeInformación
  • Qt.CursorOcupado
  • Qt.Cursor de mano abierta
  • Qt.Cursor de mano cerrada
  • Qt.CursorArrastrarCopiar
  • Qt.CursorArrastrarMover
  • Qt.DragLinkCursor

Para establecer únicamente la forma del cursor del ratón en una región sin que este reaccione a los eventos del ratón, configura ` acceptedButtons ` en «none»:

MouseArea { cursorShape: Qt.IBeamCursor; acceptedButtons: Qt.NoButton }

El valor por defecto es ` Qt.ArrowCursor`.

Nota: Si la propiedad « cursorShape » se establece en « undefined », el « MouseArea » no modificará la forma existente al entrar en ella.

Véase también Qt::CursorShape.

drag group

drag.active : bool [read-only]

drag.axis : enumeration

drag.filterChildren : bool

drag.maximumX : real

drag.maximumY : real

drag.minimumX : real

drag.minimumY : real

drag.smoothed : bool

drag.target : Item

drag.threshold : real

drag ofrece una forma práctica de hacer que un elemento se pueda arrastrar.

  • drag.target Especifica el identificador del elemento que se va a arrastrar.
  • drag.active Especifica si el elemento de destino se está arrastrando en ese momento.
  • drag.axis especifica si el arrastre puede realizarse horizontalmente (Drag.XAxis), verticalmente (Drag.YAxis) o en ambos sentidos (Drag.XAndYAxis)
  • drag.minimum y ` drag.maximum ` limitan la distancia a la que se puede arrastrar el elemento de destino a lo largo de los ejes correspondientes.

El siguiente ejemplo muestra un Rectangle que se puede arrastrar a lo largo del eje X. La opacidad del rectángulo se reduce cuando se arrastra hacia la derecha.

Rectangle {
    id: container
    width: 600; height: 200

    Rectangle {
        id: rect
        width: 50; height: 50
        color: "red"
        opacity: (600.0 - rect.x) / 600

        MouseArea {
            anchors.fill: parent
            drag.target: rect
            drag.axis: Drag.XAxis
            drag.minimumX: 0
            drag.maximumX: container.width - rect.width
        }
    }
}

Nota: Los elementos no se pueden arrastrar si están anclados para el « drag.axis » solicitado. Por ejemplo, si se ha establecido « anchors.left » o « anchors.right » para « rect » en el ejemplo anterior, no se podrá arrastrar a lo largo del eje X. Esto se puede evitar estableciendo el valor de anclaje en « undefined » en un controlador « onPressed ».

Si drag.filterChildren se establece en true, un arrastre puede anular las MouseAreas descendientes. Esto permite que una MouseArea padre gestione los arrastres, por ejemplo, mientras que las descendientes gestionan los clics:

import QtQuick

Rectangle {
    width: 480
    height: 320
    Rectangle {
        x: 30; y: 30
        width: 300; height: 240
        color: "lightsteelblue"

        MouseArea {
            anchors.fill: parent
            drag.target: parent;
            drag.axis: "XAxis"
            drag.minimumX: 30
            drag.maximumX: 150
            drag.filterChildren: true

            Rectangle {
                color: "yellow"
                x: 50; y : 50
                width: 100; height: 100
                MouseArea {
                    anchors.fill: parent
                    onClicked: console.log("Clicked")
                }
            }
        }
    }
}

drag.threshold determina el umbral en píxeles a partir del cual debe iniciarse la operación de arrastre. Por defecto, está vinculado a un valor dependiente de la plataforma. Esta propiedad se añadió en Qt Quick 2.2.

Si drag.smoothed es true, el elemento de destino solo se moverá una vez que haya comenzado la operación de arrastre. Si se establece en false, el elemento de destino se moverá directamente a la posición actual del ratón. De forma predeterminada, esta propiedad es true. Esta propiedad se añadió en Qt Quick 2.4

Consulta la propiedad adjunta « Drag » y DropArea si deseas realizar una acción de soltar.

enabled : bool

Esta propiedad indica si el elemento acepta eventos del ratón.

Nota: Por motivos históricos, esta propiedad no es equivalente a Item.enabled. Solo afecta a los eventos del ratón y su efecto no se propaga a los elementos secundarios.

Por defecto, esta propiedad tiene el valor «true».

hoverEnabled : bool

Esta propiedad determina si se gestionan los eventos al pasar el cursor.

Por defecto, los eventos del ratón solo se gestionan en respuesta a un evento de botón o cuando se pulsa un botón. La opción «Hover» permite gestionar todos los eventos del ratón, incluso cuando no se pulsa ningún botón.

Esta propiedad afecta a la propiedad « containsMouse » y a las señales «onEntered», «onExited» y «onPositionChanged».

mouseX : real [read-only]

mouseY : real [read-only]

Estas propiedades contienen las coordenadas del cursor del ratón.

Si la propiedad « hoverEnabled » es «false», estas propiedades solo serán válidas mientras se mantenga pulsado un botón, y seguirán siendo válidas mientras se mantenga pulsado el botón, incluso si se mueve el ratón fuera del área.

Por defecto, esta propiedad es «false».

Si « hoverEnabled » es «true», estas propiedades serán válidas cuando:

  • no se pulse ningún botón, pero el ratón se encuentre dentro de la zona « MouseArea » (containsMouse » es «true»).
  • se mantenga pulsado un botón, incluso si desde entonces se ha movido fuera del área.

Las coordenadas son relativas al área « MouseArea ».

pressAndHoldInterval : int

Esta propiedad anula el tiempo transcurrido en milisegundos antes de que se emita « pressAndHold ».

Si no se establece explícitamente —o tras un reinicio—, el valor sigue el de QStyleHints::mousePressAndHoldInterval.

Normalmente basta con configurar esta propiedad de forma global utilizando la sugerencia de estilo de la aplicación. Esta propiedad debe utilizarse cuando se necesiten intervalos variables para determinadas MouseAreas.

Véase también pressAndHold.

pressed : bool [read-only]

Esta propiedad indica si alguno de los botones « acceptedButtons » está pulsado en ese momento.

pressedButtons : MouseButtons [read-only]

Esta propiedad almacena los botones del ratón que están pulsados en ese momento.

Contiene una combinación binaria de:

  • Qt.LeftButton
  • Qt.RightButton
  • Qt.MiddleButton

El código siguiente muestra «right» cuando se pulsa el botón derecho del ratón:

Text {
    text: mouseArea.pressedButtons & Qt.RightButton ? "right" : ""
    horizontalAlignment: Text.AlignHCenter
    verticalAlignment: Text.AlignVCenter

    MouseArea {
        id: mouseArea
        anchors.fill: parent
        acceptedButtons: Qt.LeftButton | Qt.RightButton
    }
}

Nota: esta propiedad solo gestiona los botones especificados en acceptedButtons.

Véase también acceptedButtons.

preventStealing : bool

Esta propiedad determina si los eventos del ratón pueden ser interceptados desde este MouseArea.

Si se coloca un « MouseArea » dentro de un elemento que filtra los eventos del ratón de sus elementos secundarios, como «Flickable», los eventos del ratón pueden ser «robados» del « MouseArea » si el elemento padre reconoce un gesto, por ejemplo, un gesto de deslizamiento. Si «preventStealing» se establece en «true», ningún elemento «robará» los eventos del ratón.

Ten en cuenta que establecer preventStealing en «true» una vez que un elemento haya comenzado a «robar» eventos no tendrá ningún efecto hasta el siguiente evento de pulsación.

Por defecto, esta propiedad está establecida en «false».

propagateComposedEvents : bool

Esta propiedad determina si los eventos de ratón compuestos se propagarán automáticamente a otras «MouseAreas» que se superpongan a esta « MouseArea », pero que se encuentren en una posición inferior en el orden de superposición visual. Por defecto, esta propiedad tiene el valor «false».

MouseArea Contiene varios eventos compuestos: « clicked », « doubleClicked » y « pressAndHold ». Estos se componen de eventos básicos del ratón, como « pressed », y pueden propagarse de forma diferente en comparación con los eventos básicos.

Si propagateComposedEvents se establece en «true», los eventos compuestos se propagarán automáticamente a otras MouseAreas situadas en la misma ubicación de la escena. Cada evento se propaga a la siguiente « enabled » MouseArea situada debajo de ella en el orden de apilamiento, descendiendo por esta jerarquía visual hasta que una « MouseArea » acepte el evento. A diferencia de los eventos « pressed », los eventos compuestos no se aceptarán automáticamente si no hay ningún controlador presente.

Por ejemplo, a continuación se muestra un Rectangle amarillo que contiene un Rectangle azul. El rectángulo azul es el elemento situado más arriba en la jerarquía del orden de apilamiento visual; se representará visualmente por encima del rectángulo amarillo. Dado que el rectángulo azul establece `propagateComposedEvents` en `true` y también establece ` MouseEvent::accepted ` en `false` para todos los eventos ` clicked ` recibidos, cualquier evento ` clicked ` que reciba se propaga al ` MouseArea ` del rectángulo amarillo situado debajo de él.

import QtQuick 2.0

Rectangle {
    color: "yellow"
    width: 100; height: 100

    MouseArea {
        anchors.fill: parent
        onClicked: console.log("clicked yellow")
    }

    Rectangle {
        color: "blue"
        width: 50; height: 50

        MouseArea {
            anchors.fill: parent
            propagateComposedEvents: true
            onClicked: (mouse)=> {
                console.log("clicked blue")
                mouse.accepted = false
            }
        }
    }
}

Al hacer clic en el rectángulo azul, se invocará el controlador onClicked de su elemento secundario MouseArea; a continuación, el evento se propagará a la propiedad MouseArea del rectángulo amarillo, lo que provocará que se invoque su propio controlador onClicked.

Esta propiedad simplifica enormemente los casos de uso en los que se desea que varias «MouseAreas» superpuestas gestionen conjuntamente los eventos compuestos. Por ejemplo: si se desea que una « MouseArea » gestione las señales « clicked » y la otra las de « pressAndHold », o si se desea que una « MouseArea » gestione « clicked » la mayor parte del tiempo, pero lo reenvíe cuando se cumplan determinadas condiciones.

scrollGestureEnabled : bool

Esta propiedad controla si este « MouseArea » responde a los gestos de desplazamiento de dispositivos que no sean ratones, como el gesto de deslizamiento con dos dedos en un trackpad. Si se establece en «false», la señal « wheel » solo se emitirá cuando el evento de la rueda provenga de un ratón real con rueda, mientras que los eventos de gestos de desplazamiento se transmitirán a cualquier otro «Item» que los gestione. Por ejemplo, el usuario podría realizar un gesto de deslizamiento rápido mientras el cursor se encuentra sobre un elemento que contiene un ` MouseArea`, con la intención de interactuar con un `Flickable` que se encuentra debajo. Establecer esta propiedad en «false» permitirá que el ` PinchArea ` gestione la rueda del ratón o el gesto de pellizco, mientras que el `Flickable` se encarga del gesto de deslizamiento rápido.

Por defecto, esta propiedad tiene el valor «true».

Documentación de Signal

canceled()

Esta señal se emite cuando se han cancelado los eventos del ratón, porque otro elemento se ha apropiado del manejo de dichos eventos.

Esta señal está destinada a un uso avanzado: resulta útil cuando hay más de un « MouseArea » gestionando la entrada, o cuando hay un « MouseArea » dentro de un « Flickable ». En este último caso, si se ejecuta alguna lógica en el controlador de la señal « onPressed » y luego se empieza a arrastrar, el « Flickable » se hará cargo del control del ratón en lugar del « MouseArea ». En estos casos, para restablecer la lógica cuando el « MouseArea » haya perdido el control del ratón a favor del « Flickable », se debe gestionar « canceled » además de « released ».

Nota: El controlador correspondiente es onCanceled.

clicked(MouseEvent mouse)

Esta señal se emite cuando se produce un clic. Un clic se define como una pulsación seguida de una liberación, ambas dentro del « MouseArea » (pulsar, salir del « MouseArea » y, a continuación, volver a entrar y soltar también se considera un clic).

El parámetro ` mouse ` proporciona información sobre el clic, incluidas las coordenadas x e y en las que se soltó el clic, y si este se mantuvo pulsado.

Al gestionar esta señal, cambiar la propiedad « accepted » del parámetro « mouse » no tiene ningún efecto, a menos que la propiedad « propagateComposedEvents » esté establecida en « true ».

Nota: El controlador correspondiente es onClicked.

doubleClicked(MouseEvent mouse)

Esta señal se emite cuando se produce un doble clic (una pulsación seguida de una liberación y, a continuación, otra pulsación). El parámetro « mouse » proporciona información sobre el clic, incluidas las coordenadas x e y de la liberación del clic, y si este se mantuvo pulsado.

Al gestionar esta señal, si la propiedad ` accepted ` del parámetro ` mouse ` se establece en `false`, se emitirán las señales `pressed`, `released` y `clicked` para el segundo clic; de lo contrario, se suprimen. La propiedad ` accepted ` tiene por defecto el valor `true`.

Nota: El controlador correspondiente es ` onDoubleClicked`.

entered()

Esta señal se emite cuando el ratón entra en el área del ratón.

Por defecto, esta señal solo se emite si hay algún botón pulsado en ese momento. Establece hoverEnabled en «true» para que se emita esta señal incluso cuando no haya ningún botón del ratón pulsado.

Nota: El controlador correspondiente es onEntered.

Véase también ` hoverEnabled`.

exited()

Esta señal se emite cuando el ratón sale del área de seguimiento.

Por defecto, esta señal solo se emite si hay algún botón pulsado en ese momento. Establece ` hoverEnabled ` en `true` para emitir esta señal incluso cuando no haya ningún botón del ratón pulsado.

El ejemplo siguiente muestra una relación bastante típica entre dos «MouseAreas», con « mouseArea2 » encima de « mouseArea1 ». Al mover el ratón desde « mouseArea1 » hacia « mouseArea2 », « mouseArea1 » emitirá la señal « exited ».

Rectangle {
    width: 400; height: 400
    MouseArea {
        id: mouseArea1
        anchors.fill: parent
        hoverEnabled: true
    }
    MouseArea {
        id: mouseArea2
        width: 100; height: 100
        anchors.centerIn: parent
        hoverEnabled: true
    }
}

Si, por el contrario, estableces una relación padre-hijo entre las dos MouseAreas, al pasar el ratón por encima de mouseArea2 desde mouseArea1, mouseArea1 no emitirá exited. En su lugar, se considerará que el cursor se encuentra simultáneamente sobre ambas.

Nota: El controlador correspondiente es onExited.

Véase también hoverEnabled.

positionChanged(MouseEvent mouse)

Esta señal se emite cuando cambia la posición del ratón.

El parámetro « mouse » proporciona información sobre el ratón, incluidas las coordenadas x e y, así como los botones que estén pulsados en ese momento.

Por defecto, esta señal solo se emite si hay algún botón pulsado en ese momento. Establece « hoverEnabled » en «true» para que se emita esta señal incluso cuando no haya ningún botón del ratón pulsado.

Al gestionar esta señal, cambiar la propiedad « accepted » del parámetro « mouse » no tiene ningún efecto.

Nota: El controlador correspondiente es onPositionChanged.

pressAndHold(MouseEvent mouse)

Esta señal se emite cuando se produce una pulsación prolongada (actualmente, 800 ms). El parámetro « mouse » proporciona información sobre la pulsación, incluidas las coordenadas x e y de la misma y qué botón se ha pulsado.

Al gestionar esta señal, cambiar la propiedad ` accepted ` del parámetro ` mouse ` no tiene ningún efecto, a menos que la propiedad ` propagateComposedEvents ` esté establecida en ` true`.

Nota: El controlador correspondiente es onPressAndHold.

pressed(MouseEvent mouse)

Esta señal se emite cuando se pulsa un botón. El parámetro « mouse » proporciona información sobre la pulsación, incluidas las coordenadas x e y y qué botón se ha pulsado.

Al gestionar esta señal, utiliza la propiedad « accepted » del parámetro « mouse » para controlar si esta « MouseArea » gestiona la pulsación y todos los eventos futuros del ratón hasta que se suelte el botón. Por defecto, se acepta el evento y no se permite que otras «MouseAreas» situadas debajo de esta gestionen el evento. Si «accepted» se establece en «false», no se enviarán más eventos a esta « MouseArea » hasta la próxima pulsación del botón.

Nota: El controlador correspondiente es onPressed.

released(MouseEvent mouse)

Esta señal se emite cuando se suelta el botón. El parámetro « mouse » proporciona información sobre el clic, incluidas las coordenadas x e y del punto en el que se soltó el botón, y si el clic se mantuvo pulsado.

Al gestionar esta señal, cambiar la propiedad « accepted » del parámetro « mouse » no tiene ningún efecto.

Nota: El controlador correspondiente es ` onReleased`.

Véase también canceled.

wheel(WheelEvent wheel)

Esta señal se emite en respuesta tanto a los gestos de desplazamiento con la rueda del ratón como con el trackpad.

El parámetro ` wheel ` proporciona información sobre el evento, incluidas las coordenadas x e y, los botones pulsados en ese momento e información sobre el movimiento de la rueda, como `angleDelta` y `pixelDelta`.

Nota: El controlador correspondiente es onWheel.

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