ShapePath QML Type
Describe una ruta y las propiedades asociadas para el trazado y el relleno. Más...
| Import Statement: | import QtQuick.Shapes 1.12 |
| Inherits: |
Propiedades
- capStyle : enumeration
- cosmeticStroke : bool
(since 6.11) - dashOffset : real
- dashPattern : list<real>
- fillColor : color
- fillGradient : ShapeGradient
- fillItem : Item
(since 6.8) - fillRule : enumeration
- fillTransform : matrix4x4
(since 6.8) - joinStyle : enumeration
- miterLimit : int
- pathHints : PathHints
(since 6.7) - strokeColor : color
- strokeGradient : ShapeGradient
(since 6.12) - strokeStyle : enumeration
- strokeWidth : real
- trim
(since 6.10)- trim.end : real
(since 6.10) - trim.offset : real
(since 6.10) - trim.start : real
(since 6.10)
- trim.end : real
Descripción detallada
Un objeto « Shape » contiene uno o más elementos «ShapePath». Se necesita al menos un «ShapePath» para que un «Shape» genere algo visible. Un «ShapePath» es, en sí mismo, un objeto « Path » con propiedades adicionales que describen los parámetros de trazo y relleno, como el grosor y el color del trazo, el color de relleno o el degradado, los estilos de unión y remate, etc. Al igual que los objetos « Path » habituales, «ShapePath» también contiene una lista de elementos de trazado como « PathMove », « PathLine », « PathCubic », « PathQuad », « PathArc », junto con una posición inicial.
Cualquier cambio en las propiedades de estos conjuntos de datos se propagará y modificará el resultado de la forma. Esto significa que resulta sencillo y fácil cambiar, o incluso animar, la posición inicial y final, los puntos de control o cualquier parámetro de trazo o relleno utilizando los enlaces habituales de QML y tipos de animación como NumberAnimation.
En el siguiente ejemplo, el estilo de unión de líneas cambia automáticamente en función del valor de `joinStyleIndex`:
ShapePath {
strokeColor: "black"
strokeWidth: 16
fillColor: "transparent"
capStyle: ShapePath.RoundCap
property int joinStyleIndex: 0
property variant styles: [
ShapePath.BevelJoin,
ShapePath.MiterJoin,
ShapePath.RoundJoin
]
joinStyle: styles[joinStyleIndex]
startX: 30
startY: 30
PathLine { x: 100; y: 100 }
PathLine { x: 30; y: 100 }
}Una vez asociado a una forma, este es el resultado con un `joinStyleIndex` de 2 (ShapePath.RoundJoin):

Véanse también los ejemplos de «Qt Quick » (Formas), el ejemplo de previsión meteorológica y « Shape ».
Documentación de propiedades
capStyle : enumeration
Esta propiedad define cómo se dibujan los extremos de las líneas. El valor por defecto es « ShapePath.SquareCap ».
| Constante | Descripción |
|---|---|
ShapePath.FlatCap | Un extremo de línea cuadrado que no cubre el punto final de la línea. |
ShapePath.SquareCap | Un extremo de línea cuadrado que cubre el punto final y se extiende más allá de él la mitad del ancho de la línea. |
ShapePath.RoundCap | Un extremo de línea redondeado. |
cosmeticStroke : bool [since 6.11]
Esta propiedad determina si el grosor del trazo se mantiene constante independientemente de la escala de representación.
Cuando esta propiedad se establece en « true », el contorno de la forma se dibuja con un ancho constante en píxeles independientes del dispositivo, tal y como se especifica en « strokeWidth », independientemente de las transformaciones que se apliquen a la forma, como « QtQuick::Item::scale ».
El valor por defecto es false.
Esta propiedad se introdujo en Qt 6.11.
Véase también strokeWidth.
dashOffset : real
Esta propiedad define el punto de inicio del patrón de guiones, medido en las unidades utilizadas para especificar dicho patrón.
El valor por defecto es 0.
Véase también ` QPen::setDashOffset()`.
dashPattern : list<real>
Esta propiedad define el patrón de guiones cuando strokeStyle se establece en ShapePath.DashLine. El patrón debe especificarse como un número par de entradas positivas, en las que las entradas 1, 3, 5... son los guiones y las 2, 4, 6... son los espacios. El patrón se especifica en unidades equivalentes al ancho del trazo.
El valor por defecto es (4, 2), lo que significa un trazo de 4 * strokeWidth píxeles seguido de un espacio de 2 * strokeWidth píxeles.
Véase también QPen::setDashPattern().
fillColor : color
Esta propiedad determina el color de relleno.
Si se establece en transparent, no se aplica ningún relleno.
El valor predeterminado es « white ».
Nota: Si se establece « fillGradient » o « fillItem » en un valor distinto de « null », estos tendrán prioridad sobre « fillColor ». En este caso, se ignorará la propiedad « fillColor ».
fillGradient : ShapeGradient
Esta propiedad define el degradado de relleno. Por defecto, no hay ningún degradado activado y el valor es « null ». En este caso, el relleno se basará en la propiedad « fillItem » si está configurada; de lo contrario, se utilizará la propiedad « fillColor ».
Nota: El tipo «Gradient» no se puede utilizar aquí. Es preferible utilizar uno de los subtipos avanzados, como « LinearGradient ».
Nota: Si se establece un valor distinto de « null », la propiedad « fillGradient » tendrá prioridad sobre « fillItem » y « fillColor ».
De forma predeterminada, se pueden mostrar hasta 256 degradados diferentes simultáneamente. Este límite se puede personalizar con la variable de entorno QT_QUICKSHAPES_MAX_GRADIENTS.
fillItem : Item [since 6.8]
Esta propiedad define otro elemento « Qt Quick » que se utilizará como relleno de la forma. El elemento debe ser un proveedor de texturas (como un « layered item », un « ShaderEffectSource » o un « Image »). Si no se trata de un proveedor de texturas válido, esta propiedad se ignorará.
El padre visual de fillItem debe ser un Qt Quick o un Item. En concreto, dado que ShapePath no es un Item, sus hijos no pueden utilizarse como elementos de relleno. Es necesario establecer manualmente el padre de fillItem cuando se crea como hijo de ShapePath.
Por ejemplo, al crear un objeto Image directamente en la asignación de la propiedad fillItem, este pasará a ser un elemento secundario del ShapePath. En este caso, su elemento principal debe configurarse manualmente. En el siguiente ejemplo utilizamos el contentItem de la ventana como elemento principal.
fillItem: Image {
visible: false
source: "contents.png"
parent: window.contentItem
}Nota: Al utilizar un elemento en capas como « fillItem », es posible que se observen efectos de pixelación al transformar el relleno. Establecer la propiedad « layer.smooth » en «true» proporcionará mejores resultados visuales en este caso.
Por defecto, no se establece ningún elemento de relleno y el valor es « null ».
Nota: Si se establece en un valor distinto de « null », la propiedad « fillItem » tiene prioridad sobre « fillColor ». La propiedad « fillGradient », a su vez, tiene prioridad tanto sobre « fillItem » como sobre « fillColor ».
Esta propiedad se introdujo en Qt 6.8.
fillRule : enumeration
Esta propiedad define la regla de relleno. El valor por defecto es « ShapePath.OddEvenFill ». Para obtener una explicación sobre las reglas de relleno, consulta QPainterPath::setFillRule().
| Constante | Descripción |
|---|---|
ShapePath.OddEvenFill | Regla de relleno par-impar. |
ShapePath.WindingFill | Regla de relleno de bobinado distinta de cero. |
fillTransform : matrix4x4 [since 6.8]
Esta propiedad define una transformación que se aplicará al patrón de relleno de la ruta (fillGradient o fillItem). No tiene ningún efecto si el relleno es de un color liso o transparente. Por defecto, no hay ninguna transformación de relleno activada y el valor de esta propiedad es la matriz identity.
Este ejemplo muestra un rectángulo rellenado con el contenido de myImageItem, girado 45 grados alrededor del punto central de myShape:
ShapePath {
fillItem: myImageItem
fillTransform: PlanarTransform.fromRotate(45, myShape.width / 2, myShape.height / 2)
PathRectangle { x: 10; y: 10; width: myShape.width - 20; height: myShape.height - 20 }
}Esta propiedad se introdujo en Qt 6.8.
joinStyle : enumeration
Esta propiedad define cómo se dibujan las uniones entre dos líneas conectadas. El valor por defecto es « ShapePath.BevelJoin ».
| Constante | Descripción |
|---|---|
ShapePath.MiterJoin | Los bordes exteriores de las líneas se extienden hasta encontrarse en ángulo, y esta zona se rellena. |
ShapePath.BevelJoin | Se rellena la muesca triangular entre las dos líneas. |
ShapePath.RoundJoin | Se rellena un arco circular entre las dos líneas. |
miterLimit : int
Cuando la opción « joinStyle » está configurada en « ShapePath.MiterJoin », esta propiedad especifica la distancia a la que puede extenderse la unión en inglete desde el punto de unión.
El valor por defecto es 2.
pathHints : PathHints [since 6.7]
Esta propiedad describe las características de la forma. Si se activa, estas indicaciones pueden permitir una representación optimizada. Por defecto, no hay ninguna indicación activada. Puede ser una combinación de los siguientes valores:
| Constante | Descripción |
|---|---|
ShapePath.PathLinear | La ruta solo contiene líneas rectas, sin curvas. |
ShapePath.PathQuadratic | La ruta no contiene curvas cúbicas: solo líneas y curvas de Bézier cuadráticas. |
ShapePath.PathConvex | La ruta no tiene muescas ni agujeros. Todas las líneas rectas entre dos puntos dentro de la forma estarán completamente dentro de la misma. |
ShapePath.PathFillOnRight | El trazado sigue la convención TrueType, según la cual los contornos alrededor de los rellenos sólidos tienen sus puntos de control ordenados en el sentido de las agujas del reloj, y los contornos alrededor de los huecos de la forma tienen sus puntos de control ordenados en sentido contrario a las agujas del reloj. |
ShapePath.PathSolid | El trazado no tiene agujeros o, en términos matemáticos, es simplemente conexo. |
ShapePath.PathNonIntersecting | El contorno del trazado no se cruza consigo mismo. |
ShapePath.PathNonOverlappingControlPointTriangles | Los triángulos definidos por los puntos de control de la curva no se solapan entre sí ni con ninguno de los segmentos de línea. Además, ningún segmento de línea se cruza con otro. Esto implica que PathNonIntersecting. |
No todas las condiciones son lógicamente independientes, pero las dependencias no son obligatorias. Por ejemplo, « PathLinear » implica « PathQuadratic », pero es válido que se cumpla « PathLinear » sin que se cumpla « PathQuadratic ».
La propiedad `pathHints` describe un conjunto de afirmaciones que se sabe que son verdaderas; la ausencia de una pista no significa necesariamente que la afirmación correspondiente sea falsa.
Esta propiedad se introdujo en Qt 6.7.
strokeColor : color
Esta propiedad determina el color del trazo.
Cuando se establece en « transparent », no se aplica ningún trazo. Si se establece la propiedad « strokeGradient », tendrá prioridad sobre « strokeColor ».
El valor por defecto es « white ».
strokeGradient : ShapeGradient [since 6.12]
Esta propiedad define el degradado del trazo. Por defecto, no hay ningún degradado activado y el valor es « null ». En este caso, el trazo se basará en la propied strokeColor.
Nota: El tipo «Gradient» no se puede utilizar aquí. En su lugar, es preferible utilizar uno de los subtipos avanzados, como « LinearGradient ».
Nota: Si se establece un valor distinto de « null », la propiedad « strokeGradient » tendrá prioridad sobre « strokeColor ».
Por defecto, se pueden mostrar hasta 256 degradados diferentes simultáneamente. Este límite se puede personalizar con la variable de entorno « QT_QUICKSHAPES_MAX_GRADIENTS ».
Esta propiedad se introdujo en Qt 6.12.
strokeStyle : enumeration
Esta propiedad define el estilo del trazo. El valor por defecto es ShapePath.SolidLine.
| Constante | Descripción |
|---|---|
ShapePath.SolidLine | Una línea continua. |
ShapePath.DashLine | Trazos separados por unos pocos píxeles. |
strokeWidth : real
Esta propiedad determina el ancho del trazo.
Si se establece un valor negativo, no se traza ningún trazo.
El valor por defecto es 1.
Véase también cosmeticStroke.
trim group
Especifica la sección de esta ruta que se mostrará.
La sección viene definida por las fracciones de longitud de ruta start y end. Por defecto, start es 0 (lo que indica el inicio de la ruta) y end es 1 (lo que indica el final de la ruta), por lo que se muestra la ruta completa.
El valor de offset se suma a start y end. Si ello provoca que se sobrepase o no se alcance el rango [0, 1], los valores se reajustarán, al igual que la sección de ruta resultante. El rango efectivo de offset está comprendido entre -1 y 1. El valor por defecto es 0.
Estas propiedades se introdujeron en Qt 6.10.
© 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.