MouseArea QML Type

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

• Lista de todos los miembros, incluidos los heredados

Propiedades

• acceptedButtons : Qt::MouseButtons
• containsMouse : bool
• containsPress : bool
• cursorShape : Qt::CursorShape
• drag
  • drag.active : bool
  • 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
• enabled : bool
• hoverEnabled : bool
• mouseX : real
• mouseY : real
• pressAndHoldInterval : int
• pressed : bool
• pressedButtons : MouseButtons
• preventStealing : bool
• propagateComposedEvents : bool
• scrollGestureEnabled : bool

Señales

• canceled()
• clicked(MouseEvent mouse)
• doubleClicked(MouseEvent mouse)
• entered()
• exited()
• positionChanged(MouseEvent mouse)
• pressAndHold(MouseEvent mouse)
• pressed(MouseEvent mouse)
• released(MouseEvent mouse)
• wheel(WheelEvent wheel)

Descripción detallada

Un MouseArea es un elemento invisible que se utiliza normalmente en conjunción con un elemento visible con el fin de proporcionar el manejo del ratón para ese elemento. Al actuar como un proxy, la lógica para el manejo del ratón puede estar contenida 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á deshabilitada, 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 a false, el área del ratón se vuelve transparente a los eventos del ratón.

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

La información sobre la posición del ratón y las pulsaciones de botón se proporciona a través de señales para las que se definen propiedades manejadoras de eventos. Las más utilizadas tienen que ver con el manejo de pulsaciones y clics del ratón: onClicked, onDoubleClicked, onPressed, onReleased y onPressAndHold. También es posible manejar eventos de la rueda del ratón a través de la señal onWheel.

Si un MouseArea se solapa con el área de otros elementos MouseArea, puedes elegir propagar los eventos clicked, doubleClicked y pressAndHold a estos otros elementos estableciendo propagateComposedEvents a true y rechazando los eventos que deberían propagarse. Consulta la documentación de propagateComposedEvents para más detalles.

Por defecto, los elementos MouseArea sólo informan de los clics del ratón y no de los cambios en la posición del cursor del ratón. Establecer la propiedad hoverEnabled garantiza que se utilicen los manejadores 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

El siguiente ejemplo utiliza un MouseArea en un Rectangle que cambia el color de Rectangle a rojo cuando se pulsa:

import QtQuick

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

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

Muchas señales 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 tecla.

He aquí una extensión del ejemplo anterior que produce un color diferente cuando se hace clic con el botón derecho del ratón sobre 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';
        }
    }
}

Ver también MouseEvent, MouseArea ejemplo, y Conceptos Importantes En Qt Quick - Entrada de Usuario.

Documentación de Propiedades

acceptedButtons : Qt::MouseButtons

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

Para especificar que MouseArea reaccionará a varios botones, los valores de la bandera 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 mantiene si el ratón está actualmente dentro del área del ratón.

containsPress : bool [read-only]

Se trata de una propiedad de conveniencia equivalente a pressed && containsMouse, es decir, mantiene si alguno de los acceptedButtons está actualmente pulsado y el ratón se encuentra actualmente dentro de los MouseArea.

Esta propiedad es particularmente útil para resaltar un elemento mientras el ratón está pulsado dentro de sus límites.

Véase también pressed y containsMouse.

cursorShape : Qt::CursorShape

Esta propiedad contiene la forma del cursor para esta área del ratón. Tenga en cuenta que en las plataformas que no muestran un cursor de ratón esto puede no tener ningún efecto.

Las formas de cursor disponibles son:

• Qt.ArrowCursor
• Qt.CursorFlechaArriba
• Qt.CursorCruzado
• Qt.WaitCursor
• Qt.IBeamCursor
• Qt.SizeVerCursor
• Qt.SizeHorCursor
• Qt.SizeBDiagCursor
• Qt.SizeFDiagCursor
• Qt.SizeAllCursor
• Qt.BlankCursor
• Qt.SplitVCursor
• Qt.SplitHCursor
• Qt.PointingHandCursor
• Qt.ForbiddenCursor
• Qt.WhatsThisCursor
• Qt.BusyCursor
• Qt.OpenHandCursor
• Qt.CursorManoCerrada
• Qt.DragCopyCursor
• Qt.DragMoveCursor
• Qt.DragLinkCursor

Para establecer sólo una forma de cursor de ratón para una región sin reaccionar a los eventos del ratón establezca el acceptedButtons a none:

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

El valor por defecto es Qt.ArrowCursor.

Véase también Qt::CursorShape.

drag group

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

• drag.target especifica el id del elemento a arrastrar.
• drag.active especifica si el elemento de destino está siendo arrastrado en ese momento.
• drag.axis especifica si el arrastre puede hacerse horizontalmente (Drag.XAxis), verticalmente (Drag.YAxis), o ambos (Drag.XAndYAxis)
• drag.minimum y drag.maximum limitan la distancia a la que se puede arrastrar el objetivo a lo largo de los ejes correspondientes.

El siguiente ejemplo muestra un Rectangle que puede arrastrarse 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
        }
    }
}

Si drag.filterChildren se establece en true, un arrastre puede anular MouseAreas descendientes. Esto permite a un padre MouseArea manejar los arrastres, por ejemplo, mientras que los descendientes manejan 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 de cuándo debe comenzar la operación de arrastre. Por defecto, este valor depende de la plataforma. Esta propiedad se añadió en Qt Quick 2.2.

Si drag.smoothed es true, el objetivo sólo se moverá una vez iniciada la operación de arrastre. Si se establece en false, el objetivo se moverá directamente a la posición actual del ratón. Por defecto, esta propiedad es true. Esta propiedad fue añadida en Qt Quick 2.4

Vea la propiedad adjunta Drag y DropArea si desea hacer un drop.

enabled : bool

Esta propiedad indica si el ítem acepta eventos de ratón.

Por defecto, esta propiedad es true.

hoverEnabled : bool

Esta propiedad indica si se gestionan los eventos hover.

Por defecto, los eventos de ratón sólo se manejan en respuesta a un evento de botón, o cuando se pulsa un botón. Hover permite manejar todos los eventos de 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.

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

Si la propiedad hoverEnabled es false entonces estas propiedades sólo serán válidas mientras se mantenga pulsado un botón, y seguirán siendo válidas mientras se mantenga pulsado el botón aunque el ratón se mueva fuera del área.

Por defecto, esta propiedad es falsa.

Si hoverEnabled es true entonces estas propiedades serán válidas cuando:

• no se pulsa ningún botón, pero el ratón está dentro de MouseArea (containsMouse es verdadero).
• se mantiene pulsado un botón, aunque se haya movido fuera del área.

Las coordenadas son relativas a MouseArea.

pressAndHoldInterval : int

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

Si no se establece explícitamente - o después de restablecer - el valor sigue QStyleHints::mousePressAndHoldInterval.

Normalmente es suficiente establecer esta propiedad globalmente usando 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 mantiene si alguno de los acceptedButtons está actualmente pulsado.

pressedButtons : MouseButtons [read-only]

Esta propiedad contiene los botones del ratón actualmente pulsados.

Contiene una combinación bit a bit de

• Qt.LeftButton
• Qt.BotónDerecho
• Qt.MiddleButton

El siguiente código muestra "right" cuando el botón derecho del ratón está pulsado:

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

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

Véase también acceptedButtons.

preventStealing : bool

Esta propiedad indica si los eventos de ratón pueden ser robados de este MouseArea.

Si un MouseArea se coloca dentro de un elemento que filtra eventos de ratón hijos, como Flickable, los eventos de ratón pueden ser robados del MouseArea si un gesto es reconocido por el elemento padre, por ejemplo un gesto de flick. Si preventStealing se establece en true, ningún elemento robará los eventos de ratón.

Ten en cuenta que establecer preventStealing a true una vez que un elemento ha empezado a robar eventos no tendrá efecto hasta el siguiente evento de pulsación.

Por defecto esta propiedad es false.

propagateComposedEvents : bool

Esta propiedad mantiene si los eventos de ratón compuestos se propagarán automáticamente a otras MouseAreas que se solapen con esta MouseArea pero que estén más abajo en el orden de apilamiento visual. Por defecto, esta propiedad es false.

MouseArea contiene varios eventos compuestos: clicked doubleClicked y pressAndHold. Estos están compuestos de eventos básicos de ratón, como pressed, y pueden ser propagados de forma diferente en comparación con los eventos básicos.

Si propagateComposedEvents está en true, entonces los eventos compuestos se propagarán automáticamente a otras MouseAreas en la misma ubicación en la escena. Cada evento se propaga al siguiente enabled MouseArea por debajo de él en el orden de apilamiento, propagándose hacia abajo en esta jerarquía visual hasta que un MouseArea acepte el evento. A diferencia de los eventos pressed, los eventos compuestos no serán aceptados automáticamente si no hay un controlador presente.

Por ejemplo, a continuación se muestra un Rectangle amarillo que contiene un Rectangle azul. El rectángulo azul es el elemento superior 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 propagará a MouseArea del rectángulo amarillo situado debajo.

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 manejador onClicked de su hijo MouseArea; el evento se propagará entonces al MouseArea del rectángulo amarillo, provocando que se invoque su propio manejador onClicked.

Esta propiedad simplifica enormemente el caso de uso cuando se desea tener MouseAreas superpuestas manejando conjuntamente los eventos compuestos. Por ejemplo: si quieres que un MouseArea maneje las señales de clicked y el otro las de pressAndHold, o si quieres que un MouseArea maneje clicked la mayor parte del tiempo, pero lo pase cuando se cumplan ciertas condiciones.

scrollGestureEnabled : bool

Esta propiedad controla si MouseArea responde a los gestos de desplazamiento de dispositivos que no son ratones, como el gesto de deslizar 2 dedos en un trackpad. Si se establece en false, la señal wheel sólo se emitirá cuando el evento de rueda proceda de un ratón real con rueda, mientras que los eventos de gesto de desplazamiento pasarán a cualquier otro elemento que los gestione. Por ejemplo, el usuario puede realizar un gesto de desplazamiento mientras el cursor está sobre un elemento que contiene un MouseArea, con la intención de interactuar con un Flickable que está debajo. Establecer esta propiedad a false permitirá a PinchArea manejar la rueda del ratón o el gesto de pellizcar, mientras que el Flickable maneja el gesto de deslizar.

Por defecto, esta propiedad es true.

Documentación sobre señales

canceled()

Esta señal se emite cuando los eventos de ratón han sido cancelados, porque otro elemento ha robado el manejo de eventos de ratón.

Esta señal es de uso avanzado: es útil cuando hay más de un MouseArea que está manejando la entrada, o cuando hay un MouseArea dentro de un Flickable. En este último caso, si se ejecuta alguna lógica en el manejador de señales onPressed y luego se empieza a arrastrar, el Flickable robará el manejo del ratón al MouseArea. En estos casos, para restablecer la lógica cuando el MouseArea ha perdido el manejo del ratón en favor del Flickable, se debe manejar canceled además de released.

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 de MouseArea (pulsar, moverse fuera de MouseArea, y luego volver a moverse dentro y liberar también se considera un clic).

El parámetro mouse proporciona información sobre el clic, incluyendo la posición x e y de la liberación del clic, y si el clic se ha mantenido.

Al manejar esta señal, cambiar la propiedad accepted del parámetro mouse no tiene ningún efecto, a menos que la propiedad propagateComposedEvents sea true.

doubleClicked(MouseEvent mouse)

Esta señal se emite cuando se produce un doble clic (una pulsación seguida de una liberación seguida de una pulsación). El parámetro mouse proporciona información sobre el clic, incluyendo la posición x e y de la liberación del clic, y si el clic fue mantenido.

Al manejar esta señal, si la propiedad accepted del parámetro mouse se establece en false, las señales pulsado/liberado/clic se emitirán para el segundo clic; en caso contrario, se suprimen. La propiedad accepted tiene por defecto el valor true.

entered()

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

Por defecto, esta señal sólo se emite si hay un botón pulsado. Establezca hoverEnabled en true para emitir esta señal aunque no haya ningún botón del ratón pulsado.

Véase también hoverEnabled.

exited()

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

Por defecto, esta señal sólo se emite si hay un botón pulsado. Establezca hoverEnabled en true para emitir esta señal incluso cuando no haya ningún botón del ratón pulsado.

El siguiente ejemplo muestra una relación bastante típica entre dos MouseAreas, con mouseArea2 encima de mouseArea1. Si mueve el ratón a mouseArea2 desde mouseArea1, 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 en lugar de eso le das a las dos MouseAreas una relación padre-hijo, mover el ratón a mouseArea2 desde mouseArea1 no causará que mouseArea1 emita exited. En su lugar, se considerará que ambas están sobrevoladas simultáneamente.

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, incluyendo la posición x e y, y cualquier botón actualmente pulsado.

Por defecto, esta señal sólo se emite si hay un botón pulsado. Establezca hoverEnabled en true para emitir esta señal incluso cuando no haya ningún botón del ratón pulsado.

Cuando se maneja esta señal, cambiar la propiedad accepted del parámetro mouse no tiene ningún efecto.

pressAndHold(MouseEvent mouse)

Esta señal se emite cuando se produce una pulsación larga (actualmente 800ms). El parámetro mouse proporciona información sobre la pulsación, incluyendo la posición x e y de la pulsación, y qué botón se pulsa.

Cuando se maneja esta señal, cambiar la propiedad accepted del parámetro mouse no tiene ningún efecto, a menos que la propiedad propagateComposedEvents sea true.

pressed(MouseEvent mouse)

Esta señal se emite cuando se produce una pulsación. El parámetro mouse proporciona información sobre la pulsación, incluyendo la posición x e y y qué botón se ha pulsado.

Cuando maneje esta señal, utilice la propiedad accepted del parámetro mouse para controlar si este MouseArea maneja la pulsación y todos los futuros eventos de ratón hasta la liberación. El valor por defecto es aceptar el evento y no permitir que otras MouseAreas por debajo de esta manejen el evento. Si el valor de aceptado es falso, no se enviarán más eventos a este MouseArea hasta que se vuelva a pulsar el botón.

released(MouseEvent mouse)

Esta señal se emite cuando se produce una liberación. El parámetro mouse proporciona información sobre el clic, incluyendo la posición x e y de la liberación del clic, y si el clic se ha mantenido.

Cuando se maneja esta señal, cambiar la propiedad accepted del parámetro mouse no tiene ningún efecto.

Véase también canceled.

wheel(WheelEvent wheel)

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

El parámetro wheel proporciona información sobre el evento, incluyendo la posición x e y, cualquier botón actualmente pulsado, e información sobre el movimiento de la rueda, incluyendo angleDelta y pixelDelta.