En esta página

Shape QML Type

Representa una ruta. Más...

Import Statement: import QtQuick.Shapes 1.12
Inherits:

Item

Inherited By:

EllipseShape and MaskShape

Propiedades

Descripción detallada

Representa una ruta mediante la triangulación de la geometría procedente de un QPainterPath.

Este enfoque difiere de la representación de formas mediante QQuickPaintedItem o el lienzo 2D, ya que la ruta nunca se rasteriza por software. Por lo tanto, Shape resulta adecuado para crear formas que se extienden por áreas más amplias de la pantalla, evitando la pérdida de rendimiento que suponen las cargas de texturas o las transferencias de búfer de fotogramas. Además, la API declarativa permite manipular, vincular e incluso animar las propiedades de los elementos de la ruta, como la posición inicial y final, los puntos de control, etc.

Los tipos para especificar elementos de trazado son comunes a PathView y Shape. Sin embargo, no todas las implementaciones de Shape admiten todos los tipos de elementos de trazado, mientras que algunos pueden no tener sentido para PathView. El subconjunto actualmente admitido por Shape es: PathMove, PathLine, PathQuad, PathCubic, PathArc, PathText y PathSvg.

Consulta Path para obtener una descripción detallada de los elementos de ruta admitidos.

Shape {
    width: 200
    height: 150
    anchors.centerIn: parent
    ShapePath {
        strokeWidth: 4
        strokeColor: "red"
        fillGradient: LinearGradient {
            x1: 20; y1: 20
            x2: 180; y2: 130
            GradientStop { position: 0; color: "blue" }
            GradientStop { position: 0.2; color: "green" }
            GradientStop { position: 0.4; color: "red" }
            GradientStop { position: 0.6; color: "yellow" }
            GradientStop { position: 1; color: "cyan" }
        }
        strokeStyle: ShapePath.DashLine
        dashPattern: [ 1, 4 ]
        startX: 20; startY: 20
        PathLine { x: 180; y: 130 }
        PathLine { x: 20; y: 130 }
        PathLine { x: 20; y: 20 }
    }
}

Triángulo con relleno en degradado de arcoíris y contorno discontinuo rojo

Al igual que en Item, Shape también permite declarar cualquier objeto visual o no visual como elemento secundario. Los objetos ShapePath se tratan de forma especial. Esto resulta útil, ya que permite añadir elementos visuales, como Rectangle o Image, y objetos no visuales, como Timer, directamente como elementos secundarios de Shape.

La siguiente lista resume los métodos de renderizado de Shape disponibles:

  • Cuando Qt Quick se ejecuta con el backend predeterminado, acelerado por hardware (RHI), se utilizará el renderizador genérico de formas. Este convierte las formas en triángulos que se pasan al renderizador.
  • El backend « software » es totalmente compatible. En este caso, la ruta se renderiza mediante QPainter::strokePath() y QPainter::fillPath().
  • Actualmente no se admite el backend OpenVG.

Al utilizar Shape, es importante tener en cuenta las posibles implicaciones en el rendimiento:

  • Cuando la aplicación se ejecuta con la implementación genérica de Shape basada en triangulación, la generación de la geometría se realiza íntegramente en la CPU. Esto puede resultar costoso. Cambiar el conjunto de elementos de la ruta, modificar las propiedades de dichos elementos o alterar ciertas propiedades de la propia Shape conlleva una nueva triangulación de las rutas afectadas con cada cambio. Por lo tanto, aplicar animaciones a dichas propiedades puede afectar al rendimiento en sistemas menos potentes.
  • Sin embargo, la naturaleza declarativa y basada en datos de la API de Shape suele implicar una mejor capacidad de almacenamiento en caché para los recursos subyacentes de la CPU y la GPU. Un cambio de propiedad en una « ShapePath » solo provocará el reprocesamiento de las « ShapePath » afectadas, dejando inalteradas las demás partes de la «Shape». Por lo tanto, una propiedad que cambia con frecuencia puede seguir dando lugar a una menor carga global del sistema que con los enfoques de dibujo imperativos (por ejemplo, QPainter).
  • Al mismo tiempo, hay que prestar atención al número de elementos «Shape» en la escena. La forma en que un elemento «Shape» de este tipo se representa en el grafo de escena es diferente a la de un elemento ordinario basado en geometría, y conlleva un cierto coste en lo que respecta a los cambios de estado de OpenGL.
  • Como regla general, las escenas deben evitar el uso de elementos «Shape» independientes cuando no sea absolutamente necesario. Es preferible utilizar un único elemento «Shape» con varios elementos « ShapePath » en lugar de múltiples elementos «Shape».

Véanse también los ejemplos deQt Quick: «Shapes», «Weather Forecast Example», Path, PathMove, PathLine, PathQuad, PathCubic, PathArc y PathSvg.

Documentación de la propiedad

asynchronous : bool

Cuando « rendererType » tiene el valor « Shape.GeometryRenderer » o « Shape.CurveRenderer », se lleva a cabo un cierto grado de preprocesamiento de la ruta de entrada en la CPU durante la fase de pulido de la forma. Esto puede resultar costoso. Para descargar este trabajo a subprocesos de trabajo independientes, configura esta propiedad en « true ».

Cuando está habilitada, al hacer visible una forma no se esperará a que el contenido esté disponible. En su lugar, el hilo principal o de la interfaz gráfica de usuario no se bloquea y los resultados del renderizado de la ruta solo se muestran cuando todo el trabajo asíncrono ha finalizado.

El valor por defecto es « false ».

boundingRect : rect [read-only, since 6.6]

Contiene el rectángulo delimitador unificado de todas las subtrayectorias de la forma.

Esta propiedad se introdujo en Qt 6.6.

containsMode : enumeration [since QtQuick.Shapes 1.11]

Esta propiedad determina la definición de ` contains()` para la forma. Resulta útil en caso de que añadas controladores de entrada de tipo «Qt Quick » y quieras que la respuesta se active únicamente cuando el ratón o el punto de contacto se encuentren completamente dentro de la forma.

ConstanteDescripción
Shape.BoundingRectContainsLa implementación predeterminada de ` QQuickItem::contains()` solo comprueba si el punto dado se encuentra dentro del rectángulo delimitador. Esta es la implementación más eficiente, por lo que es la predeterminada.
Shape.FillContainsComprueba si el interior (la parte que se rellenaría si se representara con relleno) de cualquier ShapePath que forme parte de esta Shape contiene el punto dado. Cuanto más complejos y numerosos sean los ShapePaths que añadas, menos eficiente será esta comprobación, lo que podría ralentizar la entrega de eventos en tu aplicación. Por lo tanto, debe utilizarse con precaución.

Una forma de acelerar la comprobación de « FillContains » es generar un contorno aproximado con el menor número posible de puntos, colocarlo en una «Shape» transparente en la parte superior y añadir tus «Pointer Handlers» a esta, de modo que la comprobación de contención resulte más ligera durante la entrega de eventos.

Esta propiedad se introdujo en QtQuick.Shapes 1.11.

data : list<Object> [default]

Esta propiedad contiene los objetos ` ShapePath ` que definen el contenido de la forma. También puede contener cualquier otro tipo de objeto, ya que la forma, al igual que el elemento, permite añadir como hijos cualquier objeto visual o no visual.

fillMode : enumeration [since QtQuick.Shapes 6.7]

Establece esta propiedad para definir qué ocurre cuando la ruta tiene un tamaño diferente al del elemento.

ConstanteDescripción
Shape.NoResizela forma se representa a su tamaño nativo, independientemente del tamaño del elemento. Esta es la opción por defecto
Shape.Stretchla forma se escala para ajustarse al elemento, modificando la relación de aspecto si es necesario. Ten en cuenta que el escalado no uniforme puede provocar una reducción de la calidad del suavizado al utilizar el renderizador de curvas
Shape.PreserveAspectFitla forma se escala de manera uniforme para ajustarse al interior del elemento
Shape.PreserveAspectCropla forma se escala de manera uniforme para llenar completamente el elemento, extendiéndose fuera de él si es necesario. Ten en cuenta que esto solo recorta realmente el contenido si « clip » es «true»

Esta propiedad se introdujo en QtQuick.Shapes 6.7.

horizontalAlignment : enumeration [since 6.7]

verticalAlignment : enumeration [since 6.7]

Establece la alineación horizontal y vertical de la forma dentro del elemento. Por defecto, la forma se alinea con el punto de referencia de la página ( (0,0) ) en la esquina superior izquierda.

Los valores válidos para « horizontalAlignment » son « Shape.AlignLeft », « Shape.AlignRight » y « Shape.AlignHCenter ». Los valores válidos para « verticalAlignment » son « Shape.AlignTop », « Shape.AlignBottom » y « Shape.AlignVCenter ».

Estas propiedades se introdujeron en Qt 6.7.

preferredRendererType : enumeration [since 6.6]

Solicita un backend específico para renderizar la forma. Los valores posibles son los mismos que para ` rendererType`. El valor por defecto es ` Shape.UnknownRenderer`, lo que indica que no hay ninguna preferencia concreta.

Si el tipo de renderizador solicitado no es compatible con el backend actual de Qt Quick, se utilizará en su lugar el renderizador por defecto de ese backend. Esto se reflejará en rendererType cuando se inicialice el backend.

Shape.SoftwareRenderer Actualmente no se puede seleccionar sin ejecutar el grafo de escena con el backend software; en ese caso, se seleccionará independientemente del valor de preferredRendererType.

Consulte rendererType para obtener más información sobre las implicaciones.

Esta propiedad se introdujo en Qt 6.6.

rendererType : enumeration [read-only]

Esta propiedad determina qué motor de representación de rutas está activo.

ConstanteDescripción
Shape.UnknownRendererSe desconoce el renderizador.
Shape.GeometryRendererLa solución genérica e independiente del controlador para la representación por GPU. Utiliza el mismo enfoque de triangulación basado en la CPU que el motor de pintura OpenGL 2 de QPainter. Esta es la opción predeterminada cuando se utiliza el motor de representación de grafos de escena Qt Quick basado en RHI.
Shape.SoftwareRendererDibujo puro de « QPainter » mediante el motor de pintura rasterizado. Esta es la opción predeterminada, y la única, cuando el grafo de escena de « Qt Quick » se ejecuta con el backend « software ».
Shape.CurveRendererRenderizador basado en GPU que tiene como objetivo preservar la curvatura a cualquier escala. A diferencia de Shape.GeometryRenderer, las curvas no se aproximan mediante líneas rectas cortas. En su lugar, las curvas se renderizan utilizando un sombreador de fragmentos especializado. Esto mejora la calidad visual y evita la pérdida de rendimiento por retesselación al hacer zoom. Además, Shape.CurveRenderer proporciona un suavizado nativo de alta calidad, sin el coste de rendimiento que suponen el multimuestreo o el supermuestreo.

Por defecto, se seleccionará « Shape.GeometryRenderer » a menos que el grafo de escena « Qt Quick » se ejecute con el backend « software ». En ese caso, se utilizará « Shape.SoftwareRenderer ». Se puede solicitar « Shape.CurveRenderer » mediante la propiedad « preferredRendererType ».

Nota: El « Shape.CurveRenderer » aproximará las curvas cúbicas con curvas cuadráticas y, por lo tanto, puede divergir ligeramente de la visualización matemáticamente correcta de la forma. Además, si la forma se está representando en una escena 3D de « Qt Quick » y el backend de OpenGL para RHI está activo, se requiere la extensión « GL_OES_standard_derivatives » de OpenGL (esta está disponible por defecto en OpenGL ES 3 y versiones posteriores, pero es opcional en OpenGL ES 2).

status : enumeration [read-only]

Esta propiedad determina el estado de la forma y es relevante cuando Shape.asynchronous está establecido en « true ».

ConstanteDescripción
Shape.NullAún no se ha inicializado.
Shape.ReadyLa forma ha finalizado su procesamiento.
Shape.ProcessingSe está procesando la ruta.

vendorExtensionsEnabled : bool

Esta propiedad controla el uso de extensiones de OpenGL no estándar.

El valor por defecto es false.

A partir de Qt 6.0 no hay implementadas rutas de renderizado específicas de ningún proveedor.

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