En esta página

MultiPointTouchArea QML Type

Permite gestionar múltiples puntos táctiles. Más información...

Import Statement: import QtQuick
Inherits:

Item

Propiedades

Señales

Descripción detallada

Un MultiPointTouchArea es un elemento invisible que se utiliza para realizar un seguimiento de múltiples puntos táctiles.

La propiedad « Item::enabled » se utiliza para activar y desactivar la gestión táctil. Cuando está desactivada, el área táctil se vuelve transparente a los eventos del ratón y táctiles.

De forma predeterminada, el ratón se gestiona de la misma manera que un único punto táctil, y los elementos situados bajo el área táctil no recibirán eventos del ratón, ya que es el área táctil la que los gestiona. Sin embargo, si la propiedad ` mouseEnabled ` se establece en `false`, el área se vuelve transparente a los eventos del ratón, de modo que se puede utilizar otro elemento sensible al ratón (como un ` MouseArea`) para gestionar la interacción del ratón por separado.

MultiPointTouchArea se puede utilizar de dos maneras:

  • estableciendo ` touchPoints ` para proporcionar objetos de punto táctil con propiedades que se pueden vincular a
  • utilizando los controladores onTouchUpdated o onPressed, onUpdated y onReleased

Aunque un MultiPointTouchArea puede asumir la propiedad exclusiva de determinados puntos táctiles, también es posible tener varios MultiPointTouchAreas activos al mismo tiempo, cada uno de los cuales opera sobre un conjunto diferente de puntos táctiles.

Véase también TouchPoint.

Documentación de propiedades

maximumTouchPoints : int

minimumTouchPoints : int

Estas propiedades definen el rango de puntos táctiles que debe gestionar el área táctil.

Se trata de una función que te permite, por ejemplo, tener áreas MultiPointTouchAreas anidadas, una que gestione los toques con dos dedos y otra que gestione los toques con tres dedos.

De forma predeterminada, se gestionan todos los puntos táctiles dentro del área táctil.

Si « mouseEnabled » es «true», el ratón actúa como un punto táctil, por lo que también está sujeto a estas restricciones: por ejemplo, si « maximumTouchPoints » es dos, puedes utilizar el ratón como un punto táctil y un dedo como otro punto táctil, lo que suma un total de dos.

mouseEnabled : bool

Esta propiedad determina si el elemento « MultiPointTouchArea » también gestionará los eventos del ratón. Si el valor es «true» (valor predeterminado), el área táctil tratará al ratón como si fuera un único punto táctil; si es «false», el área táctil ignorará los eventos del ratón y permitirá que «pasen a través» para que puedan ser gestionados por otros elementos situados debajo.

touchPoints : list<TouchPoint> [read-only]

Esta propiedad contiene un conjunto de objetos de puntos táctiles definidos por el usuario a los que se puede vincular.

Si ` mouseEnabled ` es `true` (valor predeterminado) y se pulsa el botón izquierdo del ratón mientras el cursor se encuentra sobre el área táctil, la posición actual del ratón será uno de estos puntos táctiles.

En el siguiente ejemplo, tenemos dos pequeños rectángulos que siguen a nuestros puntos táctiles.

import QtQuick

Rectangle {
    width: 400; height: 400
    MultiPointTouchArea {
        anchors.fill: parent
        touchPoints: [
            TouchPoint { id: point1 },
            TouchPoint { id: point2 }
        ]
    }

    Rectangle {
        width: 30; height: 30
        color: "green"
        x: point1.x
        y: point1.y
    }

    Rectangle {
        width: 30; height: 30
        color: "yellow"
        x: point2.x
        y: point2.y
    }
}

Por defecto, esta propiedad contiene una lista vacía.

Véase también « TouchPoint ».

Documentación de Signal

canceled(list<TouchPoint> touchPoints)

Esta señal se emite cuando se han cancelado nuevos eventos táctiles porque otro elemento ha interceptado el manejo de dichos eventos.

Esta señal es para uso avanzado: resulta útil cuando hay más de un « MultiPointTouchArea » gestionando la entrada, o cuando hay un « MultiPointTouchArea » dentro de un « Flickable ». En este último caso, si se ejecuta alguna lógica en el controlador de la señal « onPressed » y, a continuación, se inicia el arrastre, el « Flickable » puede apropiarse del control del toque del « MultiPointTouchArea ». En estos casos, para restablecer la lógica cuando el « MultiPointTouchArea » ha perdido el control del toque a favor del « Flickable », se debe gestionar « canceled » además de « released ».

touchPoints es la lista de puntos cancelados.

Nota: Si utilizas el argumento touchPoints en el código de tu controlador de señales, es recomendable cambiarle el nombre en tu parámetro formal para evitar confusiones con la propiedad touchPoints (véase Convenciones de codificación de QML):

onCanceled: (points) => console.log("canceled", points.length)

Nota: El controlador correspondiente es onCanceled.

gestureStarted(GestureEvent gesture)

Esta señal se emite cuando se ha alcanzado el umbral de arrastre global.

Esta señal se suele utilizar cuando un « MultiPointTouchArea » se ha anidado dentro de un «Flickable» u otro « MultiPointTouchArea ». Cuando se alcanza el umbral y se gestiona la señal, se puede determinar si el área táctil debe capturar o no los puntos táctiles actuales. Por defecto, no se capturarán; para capturarlos, llama a ` gesture.grab()`. Si no se captura el gesto, el `Flickable` anidado, por ejemplo, también tendría la oportunidad de capturarlo.

El objeto ` gesture ` también incluye información sobre el conjunto actual de ` touchPoints ` y el ` dragThreshold`.

Nota: El controlador correspondiente es ` onGestureStarted`.

pressed(list<TouchPoint> touchPoints)

Esta señal se emite cuando se añaden nuevos puntos táctiles. « touchPoints » es una lista de estos nuevos puntos.

Si minimumTouchPoints se establece en un valor superior a uno, esta señal no se emitirá hasta que se haya alcanzado el número mínimo de puntos táctiles requeridos.

Nota: Si utilizas el argumento ` touchPoints ` en el código de tu controlador de señal, es recomendable cambiarle el nombre en el parámetro formal para evitar confusiones con la propiedad ` touchPoints ` (véase Convenciones de programación de QML):

onPressed: (points) => console.log("pressed", points.length)

Nota: El controlador correspondiente es onPressed.

released(list<TouchPoint> touchPoints)

Esta señal se emite cuando se eliminan puntos táctiles existentes. « touchPoints » es una lista de dichos puntos eliminados.

Nota: Si utilizas el argumento ` touchPoints ` en el código de tu controlador de señales, es recomendable cambiarle el nombre en el parámetro formal para evitar confusiones con la propiedad ` touchPoints ` (véase Convenciones de programación de QML):

onReleased: (points) => console.log("released", points.length)

Nota: El controlador correspondiente es onReleased.

touchUpdated(list<TouchPoint> touchPoints)

Esta señal se emite cuando cambian los puntos táctiles gestionados por el MultiPointTouchArea. Esto incluye la adición de nuevos puntos táctiles, la eliminación o cancelación de puntos táctiles anteriores, así como la actualización de los datos de los puntos táctiles actuales. touchPoints es la lista de todos los puntos táctiles actuales.

Nota: El controlador correspondiente es onTouchUpdated.

updated(list<TouchPoint> touchPoints)

Esta señal se emite cuando se actualizan los puntos táctiles existentes. ` touchPoints ` es una lista de dichos puntos actualizados.

Nota: Si utilizas el argumento ` touchPoints ` en el código de tu controlador de señales, es recomendable cambiarle el nombre en el parámetro formal para evitar confusiones con la propiedad ` touchPoints ` (véase Convenciones de programación de QML):

onUpdated: (points) => console.log("updated", points.length)

Nota: El controlador correspondiente es onUpdated.

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