Item QML Type
Un tipo visual básico de QML. Más información...
Propiedades
- activeFocus : bool
- activeFocusOnTab : bool
- anchors
- anchors.alignWhenCentered : bool
- anchors.baseline : AnchorLine
- anchors.baselineOffset : real
- anchors.bottom : AnchorLine
- anchors.bottomMargin : real
- anchors.centerIn : Item
- anchors.fill : Item
- anchors.horizontalCenter : AnchorLine
- anchors.horizontalCenterOffset : real
- anchors.left : AnchorLine
- anchors.leftMargin : real
- anchors.margins : real
- anchors.right : AnchorLine
- anchors.rightMargin : real
- anchors.top : AnchorLine
- anchors.topMargin : real
- anchors.verticalCenter : AnchorLine
- anchors.verticalCenterOffset : real
- antialiasing : bool
- baselineOffset : int
- children : list<Item>
- childrenRect
- childrenRect.height : real
- childrenRect.width : real
- childrenRect.x : real
- childrenRect.y : real
- clip : bool
- containmentMask : QObject*
- data : list<QtObject>
- enabled : bool
- focus : bool
- focusPolicy : enumeration
(since 6.7) - height : real
- implicitHeight : real
- implicitWidth : real
- layer.effect : Component
- layer.enabled : bool
- layer.format : enumeration
- layer.live : bool
(since 6.5) - layer.mipmap : bool
- layer.samplerName : string
- layer.samples : enumeration
- layer.smooth : bool
- layer.sourceRect : rect
- layer.textureMirroring : enumeration
- layer.textureSize : size
- layer.wrapMode : enumeration
- mutabilityGroup : int
(since 6.12) - opacity : real
- palette : Palette
(since 6.0) - parent : Item
- resources : list<QtObject>
- rotation : real
- scale : real
- smooth : bool
- state : string
- states : list<State>
- transform : list<Transform>
- transformOrigin : enumeration
- transitions : list<Transition>
- visible : bool
- visibleChildren : list<Item>
- width : real
- x : real
- y : real
- z : real
Métodos
- Item childAt(real x, real y)
- bool contains(point point)
- void dumpItemTree()
(since 6.3) - void forceActiveFocus()
- void forceActiveFocus(Qt::FocusReason reason)
- bool grabToImage(callback, targetSize)
- point mapFromGlobal(real x, real y)
- point mapFromItem(Item item, point p)
- rect mapFromItem(Item item, rect r)
- point mapFromItem(Item item, real x, real y)
- rect mapFromItem(Item item, real x, real y, real width, real height)
- point mapToGlobal(real x, real y)
- point mapToItem(Item item, point p)
- rect mapToItem(Item item, rect r)
- point mapToItem(Item item, real x, real y)
- rect mapToItem(Item item, real x, real y, real width, real height)
- Item nextItemInFocusChain(bool forward)
Descripción detallada
El tipo «Item» es el tipo base para todos los elementos visuales de Qt Quick.
Todos los elementos visuales de Qt Quick heredan de «Item». Aunque un objeto «Item» no tiene apariencia visual, define todos los atributos comunes a los elementos visuales, como la posición x e y, la anchura y la altura, el anclaje y la compatibilidad con el manejo de teclas.
El tipo «Item» puede resultar útil para agrupar varios elementos bajo un único elemento visual raíz. Por ejemplo:
import QtQuick 2.0
Item {
Image {
source: "tile.png"
}
Image {
x: 80
width: 100
height: 100
source: "tile.png"
}
Image {
x: 190
width: 100
height: 100
fillMode: Image.Tile
source: "tile.png"
}
}Gestión de eventos
Todos los tipos visuales basados en Item pueden utilizar controladores de entrada (subclases de QInputEvent) para gestionar los eventos de entrada que se reciben, como los eventos de ratón, táctiles y de teclado. Esta es la forma declarativa preferida de gestionar eventos.
Una forma alternativa de gestionar eventos táctiles consiste en crear una subclase de ` QQuickItem`, llamar a `setAcceptTouchEvents()` en el constructor y sobrescribir `touchEvent()`. Utiliza ` Accept ` para capturar el evento completo y detener su propagación a los elementos subyacentes, así como para capturar de forma exclusiva todos los puntos táctiles del evento. Utiliza ` QPointerEvent::setExclusiveGrabber()` para capturar solo determinados puntos táctiles y permitir que el evento se propague más allá.
Del mismo modo, una subclase de ` QQuickItem ` puede llamar a `setAcceptedMouseButtons()` para registrarse y recibir eventos de botones del ratón, a `setAcceptHoverEvents()` para recibir eventos de desplazamiento del cursor (movimientos del ratón sin pulsar ningún botón) y sobrescribir las funciones virtuales `mousePressEvent()`, `mouseMoveEvent()` y `mouseReleaseEvent()`. Estas también pueden aceptar el evento para impedir que se transmita más allá y, al mismo tiempo, realizar una captura implícita; o bien, de forma explícita, utilizar ` grab ` para capturar el único evento de clic del ratón ( QEventPoint ) que transporta ` QMouseEvent `.
La gestión de teclas está disponible para todos los tipos visuales basados en «Item» a través de la propiedad adjunta Keys. La propiedad adjunta «Keys» proporciona señales básicas como pressed y released, así como señales para teclas específicas, como spacePressed. El ejemplo siguiente asigna el foco del teclado al elemento y gestiona la tecla izquierda mediante el controlador general onPressed y la tecla de retorno mediante el controlador onReturnPressed:
import QtQuick 2.0
Item {
focus: true
Keys.onPressed: (event)=> {
if (event.key == Qt.Key_Left) {
console.log("move left");
event.accepted = true;
}
}
Keys.onReturnPressed: console.log("Pressed return");
}Consulte la propiedad adjunta « Keys » para obtener documentación detallada.
Reflejo de la disposición
Los diseños de los elementos se pueden reflejar utilizando la propiedad adjunta LayoutMirroring. Esto hace que anchors se invierta horizontalmente y que los elementos que distribuyen o posicionan a sus hijos (como ListView o Row) inviertan horizontalmente la dirección de sus diseños.
Consulta LayoutMirroring para obtener más detalles.
Capas de elementos
Normalmente, un elemento se representará directamente en la ventana a la que pertenece. Sin embargo, al establecer ` layer.enabled`, es posible delegar el elemento y todo su subárbol a una superficie fuera de pantalla. Solo se dibujará en la ventana la superficie fuera de pantalla, es decir, una textura.
Si se desea que el tamaño de la textura sea diferente al del elemento, esto es posible utilizando layer.textureSize. Para renderizar solo una sección del elemento en la textura, utilice layer.sourceRect. También es posible especificar layer.sourceRect para que se extienda más allá de los límites del elemento. En este caso, el exterior se rellenará con píxeles transparentes.
El elemento utilizará interpolación lineal para el escalado si layer.smooth se establece en true y utilizará mipmap para el submuestreo si layer.mipmap se establece en true. El mipmapping puede mejorar la calidad visual de los elementos subescalados. Para el mipmapping de elementos de imagen individuales, es preferible utilizar Image::mipmap.
Opacidad de la capa frente a opacidad del elemento
Al aplicar opacity a una jerarquía de elementos, la opacidad se aplica a cada elemento de forma individual. Esto puede dar lugar a resultados visuales no deseados cuando la opacidad se aplica a un subárbol. Considera el siguiente ejemplo:
![]() | Opacidad sin capas |
Se renderiza una capa con la opacidad del elemento raíz establecida en 1 y, a continuación, la opacidad del elemento raíz se aplica a la textura al dibujarla. Esto significa que el fundido en una jerarquía de elementos grande, de transparente a opaco o viceversa, se puede realizar sin los artefactos de superposición que presenta la mezcla alfa normal elemento por elemento. Aquí está el mismo ejemplo con las capas activadas:
| Opacidad por capas |
Combinado con ShaderEffects
Al establecer ` layer.enabled ` en `true`, el elemento se convertirá en un « texture provider », lo que permite utilizarlo directamente como textura, por ejemplo, en combinación con el tipo ` ShaderEffect `.
Es posible aplicar un efecto a una capa en tiempo de ejecución utilizando `layer.effect`:
Item {
id: layerRoot
layer.enabled: true
layer.effect: ShaderEffect {
fragmentShader: "effect.frag.qsb"
}
}Consulta « ShaderEffect » para obtener más información sobre el uso de efectos.
Nota: « layer.enabled » es, en realidad, simplemente una forma más cómoda de utilizar « ShaderEffectSource ».
Memoria y rendimiento
Cuando se habilita la capa de un elemento, el grafo de escena asignará en la GPU una cantidad de memoria equivalente a ` width x height x 4`. En configuraciones con memoria limitada, las capas de gran tamaño deben utilizarse con precaución.
En el mundo de QPainter / QWidget, a veces resulta conveniente almacenar en caché contenido complejo en un mapa de píxeles, una imagen o una textura. En Qt Quick, debido a las técnicas ya aplicadas por el renderizador del grafo de escena, esto no suele ser necesario en la mayoría de los casos. Las llamadas de dibujo excesivas ya se reducen gracias al procesamiento por lotes y, en la mayoría de los casos, una caché acabará mezclando más píxeles que el contenido original. Por lo tanto, la sobrecarga que supone renderizar fuera de pantalla y la mezcla que conlleva dibujar la textura resultante suele ser más costosa que simplemente dejar que el elemento y sus hijos se dibujen con normalidad.
Además, un elemento que utilice una capa no puede agruparse en lotes durante el renderizado. Esto significa que una escena con muchos elementos en capas puede presentar problemas de rendimiento.
El uso de capas puede resultar práctico y útil para los efectos visuales, pero, en la mayoría de los casos, debería activarse solo mientras dure el efecto y desactivarse después.
Documentación de propiedades
activeFocus : bool [read-only]
Esta propiedad de solo lectura indica si el elemento tiene el foco activo.
Si `activeFocus` es `true`, o bien este elemento es el que recibe actualmente la entrada del teclado, o bien es un antepasado de tipo ` FocusScope ` del elemento que recibe actualmente la entrada del teclado.
Normalmente, se obtiene el foco activo estableciendo « focus » en un elemento y en sus objetos « FocusScope » contenedores. En el siguiente ejemplo, los objetos « input » y « focusScope » tendrán el foco activo, mientras que el objeto «rectangle» raíz no lo tendrá.
import QtQuick 2.0
Rectangle {
width: 100; height: 100
FocusScope {
id: focusScope
focus: true
TextInput {
id: input
focus: true
}
}
}Véase también « focus » y «Enfoque del teclado» en Qt Quick.
activeFocusOnTab : bool
Esta propiedad indica si el elemento desea formar parte de la cadena de enfoque del tab. Por defecto, está configurada en « false ».
La cadena de enfoque del tabulador recorre los elementos visitando primero el elemento padre y, a continuación, sus elementos hijos en el orden en que aparecen en la propiedad «children». Al pulsar la tecla Tab en un elemento de la cadena de enfoque del tabulador, el enfoque del teclado se desplazará al siguiente elemento de la cadena. Al pulsar BackTab (normalmente Mayús+Tab), el enfoque se desplazará al elemento anterior.
Para configurar una cadena de enfoque de la tecla Tab manualmente, consulta KeyNavigation. Los eventos de la tecla Tab utilizados por Keys o KeyNavigation tienen prioridad sobre el comportamiento de la cadena de enfoque; ignora los eventos en otros controladores de teclas para permitir que se propague.
Nota: tabFocusBehavior puede limitar aún más el foco a solo tipos específicos de controles, como por ejemplo, solo controles de texto o de lista. Este es el caso en macOS, donde el foco en controles concretos puede verse restringido en función de la configuración del sistema.
Véase también QStyleHints::tabFocusBehavior y focusPolicy.
anchors group
anchors.alignWhenCentered : bool
anchors.baseline : AnchorLine
anchors.baselineOffset : real
anchors.bottom : AnchorLine
anchors.bottomMargin : real
anchors.centerIn : Item
anchors.fill : Item
anchors.horizontalCenter : AnchorLine
anchors.horizontalCenterOffset : real
anchors.left : AnchorLine
anchors.leftMargin : real
anchors.margins : real
anchors.right : AnchorLine
anchors.rightMargin : real
anchors.top : AnchorLine
anchors.topMargin : real
anchors.verticalCenter : AnchorLine
anchors.verticalCenterOffset : real
Los puntos de referencia permiten posicionar un elemento especificando su relación con otros elementos.
Los márgenes se aplican a los puntos de referencia superior, inferior, izquierdo, derecho y de relleno. La propiedad ` anchors.margins ` se puede utilizar para establecer todos los márgenes a la vez, con el mismo valor. No anulará un margen específico que se haya establecido previamente; para eliminar un margen explícito, establezca su valor en ` undefined`. Tenga en cuenta que los márgenes son específicos de cada ancla y no se aplican si un elemento no utiliza anclas.
Los desplazamientos se aplican a los anclajes de centro horizontal, centro vertical y línea de base.
| Texto anclado a una imagen, centrado horizontalmente y situado verticalmente por debajo, con un margen. |
| Texto anclado a la izquierda de una imagen, centrada a la derecha, con un margen. La propiedad y de ambos tiene por valor predeterminado 0. |
anchors.fill Ofrece una forma cómoda de que un elemento tenga la misma geometría que otro, y equivale a conectar los cuatro anclajes direccionales.
Para borrar un valor de anclaje, establécelo en undefined.
anchors.alignWhenCentered (por defecto, ` true`) obliga a que los anclajes centrados se alineen con un píxel entero; si el elemento que se va a centrar tiene un valor impar de ` width ` o ` height`, dicho elemento se colocará en un píxel entero en lugar de en medio píxel. Esto garantiza que el elemento se dibuje con nitidez. Hay casos en los que esto no es deseable; por ejemplo, al rotar el elemento pueden apreciarse fluctuaciones debido a que el centro está redondeado.
Nota: Solose puede anclar un elemento a elementos hermanos o a un elemento padre.
Para obtener más información, consulta «Diseños de anclaje».
antialiasing : bool
Los elementos visuales lo utilizan para decidir si el elemento debe aplicar suavizado o no. En algunos casos, los elementos con suavizado requieren más memoria y su renderizado puede ser más lento (véase «Suavizado» para obtener más detalles).
El valor por defecto es «false», pero los elementos derivados pueden anularlo.
baselineOffset : int
Especifica la posición de la línea de base del elemento en coordenadas locales.
La línea de base de un elemento « Text » es la línea imaginaria sobre la que se sitúa el texto. Los controles que contienen texto suelen establecer su línea de base en la línea de base de su texto.
Para los elementos que no son de texto, se utiliza un desplazamiento predeterminado de la línea de base de 0.
La propiedad «children» contiene la lista de elementos hijos visuales de este elemento. La propiedad «resources» contiene recursos no visuales a los que se desea hacer referencia por su nombre.
Por lo general, no es necesario hacer referencia a estas propiedades al añadir elementos secundarios o recursos, ya que la propiedad predeterminada « data » asignará automáticamente los objetos secundarios a las propiedades « children » y « resources » según corresponda. Consulte la documentación de « data » para obtener más detalles.
childrenRect group
childrenRect.height : real [read-only]
childrenRect.width : real [read-only]
childrenRect.x : real [read-only]
childrenRect.y : real [read-only]
Esta propiedad de solo lectura contiene la posición y el tamaño conjuntos de los elementos secundarios del elemento.
Esta propiedad resulta útil si necesitas acceder a la geometría colectiva de los elementos secundarios de un elemento para ajustar correctamente el tamaño de este.
La geometría que se devuelve es local al elemento. Por ejemplo:
Item {
x: 50
y: 100
// prints: QRectF(-10, -20, 30, 40)
Component.onCompleted: print(childrenRect)
Item {
x: -10
y: -20
width: 30
height: 40
}
}clip : bool
Esta propiedad se mantiene independientemente de si el recorte está activado. El valor predeterminado del recorte es « false ».
Si el recorte está activado, un elemento recortará su propia representación, así como la de sus elementos secundarios, al rectángulo delimitador.
Nota: El recorte puede afectar al rendimiento del renderizado. Consulta la sección «Recorte» para obtener más información.
containmentMask : QObject*
Esta propiedad contiene una máscara opcional para el elemento que se utilizará en el método ` contains()`. Su principal función actual es determinar si un ` pointer event ` ha impactado en el elemento o no.
Por defecto, el método ` contains() ` devolverá `true` para cualquier punto dentro del rectángulo delimitador del `Item`. ` containmentMask ` permite un control más preciso. Por ejemplo, si se utiliza como `containmentMask` una subclase personalizada de `C++` ` QQuickItem ` con un método ` contains()` especializado:
Item { id: item; containmentMask: AnotherItem { id: anotherItem } }el método `contains`del elemento devolvería ` true ` solo si la implementación de` contains()` de `anotherItem` devuelve ` true`.
Se puede utilizar un ` Shape ` como máscara para que un elemento reaccione a ` pointer events ` únicamente dentro de una región no rectangular:
|
También es posible definir el método `contains` en QML. Por ejemplo, para crear un elemento circular que solo responda a eventos dentro de sus límites reales:
|
Véase también Ejemplos de «Qt Quick » - Formas.
data : list<QtObject> [default]
La propiedad «data» te permite combinar libremente elementos visuales secundarios y recursos dentro de un elemento. Si asignas un elemento visual a la lista de datos, este se convierte en un elemento secundario; si asignas cualquier otro tipo de objeto, se añade como recurso.
Así pues, puedes escribir:
en lugar de:
Por lo general, no debería ser necesario hacer referencia a la propiedad « data », ya que es la propiedad predeterminada de «Item» y, por lo tanto, todos los elementos secundarios se asignan automáticamente a esta propiedad.
enabled : bool
Esta propiedad determina si el elemento recibe eventos del ratón y del teclado. De forma predeterminada, el valor es « true ».
Cuando se establece en « false », el elemento no recibe eventos de teclado ni de dispositivos de puntero, como pulsaciones, sueltas o clics, pero sigue pudiendo recibir eventos de paso del cursor.
Nota: En Qt 5, al establecer « enabled » en « false » también se bloqueaban los eventos de desplazamiento del cursor. Esto se modificó en Qt 6 para permitir que « tooltips » y funciones similares funcionaran en elementos desactivados.
La configuración de esta propiedad afecta directamente al valor de ` enabled ` de los elementos hijos. Cuando se establece en ` false`, los valores de ` enabled ` de todos los elementos hijos también pasan a ser ` false`. Cuando se establece en ` true`, los valores de ` enabled ` de los elementos hijos vuelven a ser ` true`, a menos que se hayan establecido explícitamente en ` false`.
Al establecer esta propiedad en « false », se establece automáticamente « activeFocus » en « false », y este elemento ya no recibirá eventos de teclado.
Véase también visible.
focus : bool
Esta propiedad indica si el elemento tiene el foco dentro del FocusScope que lo contiene. Si el valor es «true», este elemento obtendrá el foco activo cuando el FocusScope que lo contiene obtenga el foco activo.
En el siguiente ejemplo, input recibirá el foco activo cuando scope obtenga el foco activo:
import QtQuick 2.0
Rectangle {
width: 100; height: 100
FocusScope {
id: scope
TextInput {
id: input
focus: true
}
}
}A efectos de esta propiedad, se supone que la escena en su conjunto actúa como un ámbito de foco. En la práctica, esto significa que el siguiente código QML otorgará el foco activo a input al iniciarse.
Véase también activeFocus y «Foco del teclado» en Qt Quick.
focusPolicy : enumeration [since 6.7]
Esta propiedad determina la forma en que el elemento acepta el foco.
| Constante | Descripción |
|---|---|
Qt.TabFocus | El elemento acepta el foco mediante la tecla Tab. |
Qt.ClickFocus | El elemento acepta el foco al hacer clic. |
Qt.StrongFocus | El elemento recibe el foco tanto al pulsar la tecla Tab como al hacer clic. |
Qt.WheelFocus | El elemento admite el foco mediante la tecla Tab, al hacer clic y al utilizar la rueda del ratón. |
Qt.NoFocus | El elemento no admite el foco. Nota: Esta propiedad formaba parte del tipo QML « Control » en Qt 6.6 y versiones anteriores. |
Esta propiedad se introdujo en Qt 6.7.
Define la posición y el tamaño del elemento. El valor por defecto es 0.
La posición (x, y) es relativa al parent.
Item { x: 100; y: 100; width: 100; height: 100 }Define la anchura o altura preferida del elemento.
Si no se especifica « width » o « height », el tamaño efectivo de un elemento vendrá determinado por su « implicitWidth » o « implicitHeight ».
Sin embargo, si un elemento es hijo de un diseño, este determinará el tamaño preferido del elemento utilizando su tamaño implícito. En tal caso, se ignorarán los valores explícitos de width o height.
El tamaño implícito por defecto para la mayoría de los elementos es 0x0; sin embargo, algunos elementos tienen un tamaño implícito inherente que no se puede anular, por ejemplo, Image y Text.
Establecer el tamaño implícito resulta útil para definir componentes que tienen un tamaño preferido en función de su contenido; por ejemplo:
// Label.qml
import QtQuick 2.0
Item {
property alias icon: image.source
property alias label: text.text
implicitWidth: text.implicitWidth + image.implicitWidth
implicitHeight: Math.max(text.implicitHeight, image.implicitHeight)
Image { id: image }
Text {
id: text
wrapMode: Text.Wrap
anchors.left: image.right; anchors.right: parent.right
anchors.verticalCenter: parent.verticalCenter
}
}Nota: El uso de ` implicitWidth `, ` Text ` o ` TextEdit ` y la configuración explícita del ancho conlleva una pérdida de rendimiento, ya que el texto debe maquetarse dos veces.
layer.effect : Component
Almacena el efecto aplicado a esta capa.
El efecto suele ser un componente de « ShaderEffect », aunque se puede asignar cualquier componente de « Item ». El efecto debe tener una propiedad de textura de origen cuyo nombre coincida con « layer.samplerName ».
Véase también « layer.samplerName » y « Item Layers ».
layer.enabled : bool
Indica si el elemento está en capas o no. Por defecto, la función de capas está desactivada.
Un elemento en capas se representa en una superficie fuera de pantalla y se almacena en caché hasta que se modifica. Activar las capas para jerarquías complejas de elementos QML puede suponer, en ocasiones, una optimización.
Ninguna de las demás propiedades de capa tiene efecto alguno cuando la capa está desactivada.
Véase también Item Layers.
layer.format : enumeration
Esta propiedad define el formato de la textura de fondo. Modificar esta propiedad resulta más útil cuando también se especifica la propiedad « layer.effect ».
| Constante | Descripción |
|---|---|
ShaderEffectSource.RGBA8 | |
ShaderEffectSource.RGBA16F | |
ShaderEffectSource.RGBA32F | |
ShaderEffectSource.Alpha | A partir de Qt 6.0, este valor ya no se utiliza y, en la práctica, tiene el mismo efecto que RGBA8. |
ShaderEffectSource.RGB | A partir de Qt 6.0, este valor no se utiliza y, en la práctica, tiene el mismo efecto que ` RGBA8 `. |
ShaderEffectSource.RGBA | A partir de Qt 6.0, este valor ya no se utiliza y, en la práctica, tiene el mismo efecto que RGBA8. |
Véase también Item Layers.
layer.live : bool [since 6.5]
Cuando esta propiedad tiene el valor «true», la textura de la capa se actualiza cada vez que se actualiza el elemento. De lo contrario, siempre será una imagen fija.
Por defecto, esta propiedad está establecida en « true ».
Esta propiedad se introdujo en Qt 6.5.
Véase también « Item Layers ».
layer.mipmap : bool
Si esta propiedad es verdadera, se generan mipmaps para la textura.
Nota: Algunas implementaciones de OpenGL ES 2 no admiten el mipmapping de texturas que no sean potencias de dos.
Véase también Item Layers.
layer.samplerName : string
Contiene el nombre de la propiedad de textura de origen del efecto.
Este valor debe coincidir con el nombre de la propiedad de textura de origen del efecto para que el elemento pueda pasar correctamente la superficie fuera de pantalla de la capa al efecto.
Véase también layer.effect, ShaderEffect y Item Layers.
layer.samples : enumeration
Esta propiedad permite solicitar un renderizado con muestreo múltiple en la capa.
Por defecto, el multimuestreo está habilitado siempre que esté habilitado para toda la ventana, siempre que el renderizador de grafos de escena utilizado y la API gráfica subyacente lo admitan.
Al establecer el valor en 2, 4, etc., se puede solicitar el renderizado con multimuestreo para una parte de la escena sin habilitarlo para toda la escena. De esta forma, el multimuestreo se aplica únicamente a un subárbol determinado, lo que puede suponer una mejora significativa del rendimiento, ya que no se aplica a otras partes de la escena.
Nota: Habilitar el multimuestreo puede resultar potencialmente costoso, independientemente del tamaño de la capa, ya que conlleva un coste de rendimiento y memoria que depende del hardware y del controlador.
Nota: Esta propiedad solo funciona cuando se dispone de compatibilidad con buffers de renderizado multimuestreados y transferencias de framebuffer. De lo contrario, el valor se ignora sin aviso.
layer.smooth : bool
Indica si la capa se transforma de forma suave. Cuando está activada, el muestreo de la textura de la capa se realiza mediante una interpolación de tipo « linear », mientras que, si no está activada, se utiliza el modo de filtrado « nearest ».
Por defecto, esta propiedad está establecida en « false ».
Véase también « Item Layers ».
layer.sourceRect : rect
Esta propiedad define el área rectangular del elemento que debe representarse en la textura. El rectángulo de origen puede ser más grande que el propio elemento. Si el rectángulo es nulo, que es el valor por defecto, se representa todo el elemento en la textura.
Véase también Item Layers.
layer.textureMirroring : enumeration
Esta propiedad define cómo debe reflejarse la textura generada. El valor por defecto es « ShaderEffectSource.MirrorVertically ». El reflejo personalizado puede resultar útil si se accede directamente a la textura generada mediante shaders personalizados, como los especificados en « ShaderEffect ». Si no se especifica ningún efecto para el elemento en capas, el reflejo no tiene ningún efecto en la representación del elemento en la interfaz de usuario.
| Constante | Descripción |
|---|---|
ShaderEffectSource.NoMirroring | Sin reflejo |
ShaderEffectSource.MirrorHorizontally | La textura generada se invierte a lo largo del eje X. |
ShaderEffectSource.MirrorVertically | La textura generada se invierte a lo largo del eje Y. |
layer.textureSize : size
Esta propiedad contiene el tamaño en píxeles solicitado de la textura de las capas. Si está vacía, que es el valor por defecto, se utiliza el tamaño del elemento.
Nota: Algunas plataformas tienen un límite en cuanto al tamaño mínimo que pueden tener los objetos framebuffer, lo que significa que el tamaño real de la textura podría ser mayor que el solicitado.
Véase también Item Layers.
layer.wrapMode : enumeration
Esta propiedad define los modos de repetición asociados a la textura. Modificar esta propiedad resulta más útil cuando se especifica el modo de repetición « layer.effect ».
| Constante | Descripción |
|---|---|
ShaderEffectSource.ClampToEdge | GL_CLAMP_TO_EDGE tanto en horizontal como en vertical |
ShaderEffectSource.RepeatHorizontally | GL_REPEAT en horizontal, GL_CLAMP_TO_EDGE en vertical |
ShaderEffectSource.RepeatVertically | GL_CLAMP_TO_EDGE en horizontal, GL_REPEAT en vertical |
ShaderEffectSource.Repeat | GL_REPEAT tanto en horizontal como en vertical Nota: Algunas implementaciones de OpenGL ES 2 no admiten el modo de repetición GL_REPEAT con texturas que no sean potencias de dos. |
Véase también Item Layers.
mutabilityGroup : int [since 6.12]
Se trata de una propiedad avanzada que puede utilizarse para optimizaciones de bajo nivel. Sirve como indicación para el renderizador sobre la frecuencia con la que se actualizará un elemento. En los casos de uso habituales, basta con dejar esta propiedad en su valor por defecto (Item.AutoMutabilityGroup (0)).
Sin embargo, en determinados casos, un análisis del rendimiento puede revelar cuellos de botella que el comportamiento por defecto del renderizador de grafos de escena Qt Quick no ha podido optimizar. Normalmente, esto puede ocurrir si la geometría que se actualiza rápidamente se agrupa junto con geometría estática. Para evitarlo, puede, por ejemplo, intentar asignar los componentes que se actualizan rápidamente a Item.DynamicMutabilityGroup. La geometría de diferentes grupos de mutabilidad no se agrupará.
El grupo de mutabilidad solo se aplica al propio elemento. No se propaga a los elementos secundarios.
Consulta «Renderizador predeterminado del grafo de escena deQt Quick » para obtener más información sobre el funcionamiento interno del renderizador del grafo de escena « Qt Quick » y el agrupamiento de geometría.
Valores predefinidos:
| Constante | Descripción |
|---|---|
Item.AutoMutabilityGroup | El grupo de mutabilidad predeterminado. |
Item.StaticMutabilityGroup | Indica que el elemento se actualiza muy pocas veces o nunca. |
Item.ModerateMutabilityGroup | Indica que el elemento se actualiza con una frecuencia moderada. |
Item.DynamicMutabilityGroup | Indica que el elemento se actualiza con frecuencia o en cada fotograma. Nota: El rango numérico válido de los grupos de mutabilidad es [0 .. 15]. La propiedad se limitará a este rango. Por convención, se espera que la frecuencia aumente con el valor numérico del grupo. |
Esta propiedad se introdujo en Qt 6.12.
opacity : real
Esta propiedad define la opacidad del elemento. La opacidad se especifica como un número comprendido entre 0,0 (totalmente transparente) y 1,0 (totalmente opaco). El valor por defecto es 1,0.
Cuando se establece esta propiedad, la opacidad especificada también se aplica individualmente a los elementos secundarios. Esto puede tener un efecto no deseado en algunas circunstancias. Por ejemplo, en el segundo conjunto de rectángulos que se muestra a continuación, el rectángulo rojo tiene especificada una opacidad de 0,5, lo que afecta a la opacidad de su rectángulo secundario azul, aunque este último no tenga especificada ninguna opacidad.
| |
|
Cambiar la opacidad de un elemento no afecta a su capacidad para recibir eventos de entrada del usuario. (Por el contrario, establecer la propiedad visible en false detiene los eventos del ratón, y establecer la propiedad enabled en false detiene los eventos del ratón y del teclado, además de eliminar el foco activo del elemento).
Véase también visible.
palette : Palette [since 6.0]
Esta propiedad contiene la paleta establecida actualmente para el elemento.
Esta propiedad describe la paleta solicitada por el elemento. La paleta es utilizada por el estilo del elemento al renderizar todos los controles, y está disponible como un medio para garantizar que los controles personalizados puedan mantener la coherencia con el aspecto y el comportamiento nativos de la plataforma. Es habitual que diferentes plataformas, o diferentes estilos, definan paletas distintas para una aplicación.
La paleta predeterminada depende del entorno del sistema. ApplicationWindow mantiene una paleta de sistema/tema que sirve como predeterminada para todos los controles. También puede haber paletas predeterminadas especiales para determinados tipos de controles. Asimismo, puedes establecer la paleta predeterminada para los controles de una de estas dos formas:
- pasando una paleta personalizada a QGuiApplication::setPalette(), antes de cargar cualquier QML; o
- especificando los colores en el archivo qtquickcontrols2.conf.
Los elementos propagan las propiedades explícitas de la paleta de los padres a los hijos. Si se modifica una propiedad específica de la paleta de un elemento, dicha propiedad se propaga a todos los hijos de ese elemento, anulando cualquier valor predeterminado del sistema para esa propiedad.
Esta propiedad se introdujo en Qt 6.0.
Véase también Window::palette, Popup::palette, ColorGroup, Palette y SystemPalette.
parent : Item
Esta propiedad contiene el padre visual del elemento.
Nota: El concepto de «padre visual » difiere del de «padre eQObject ». El padre visual de un elemento no tiene por qué ser necesariamente el mismo que su padre e . Para obtener más detalles, consulte «Conceptos: padre visual» en Qt Quick.
rotation : real
Esta propiedad indica la rotación del elemento en grados en el sentido de las agujas del reloj alrededor de su eje transformOrigin.
El valor por defecto es 0 grados (es decir, sin rotación).
|
Véase también « Transform » y « Rotation ».
scale : real
Esta propiedad contiene el factor de escala de este elemento.
Una escala inferior a 1,0 hace que el elemento se muestre con un tamaño menor, mientras que una escala superior a 1,0 hace que se muestre con un tamaño mayor. Una escala negativa hace que el elemento se refleje al mostrarse.
El valor por defecto es 1,0.
El escalado se aplica a partir de la propiedad « transformOrigin ».
|
Véase también Transform y Scale.
smooth : bool
Se utiliza principalmente en elementos basados en imágenes para determinar si el elemento debe emplear el muestreo suave o no. El muestreo suave se realiza mediante interpolación lineal, mientras que el no suave se lleva a cabo mediante el método del vecino más cercano.
En « Qt Quick » 2.0, esta propiedad tiene un impacto mínimo en el rendimiento.
De forma predeterminada, esta propiedad está configurada en « true ».
state : string
Esta propiedad contiene el nombre del estado actual del elemento.
Si el elemento se encuentra en su estado predeterminado, es decir, si no se ha establecido ningún estado explícito, esta propiedad contiene una cadena vacía. Del mismo modo, puedes restablecer el estado predeterminado de un elemento estableciendo esta propiedad en una cadena vacía.
Véase también «Estados deQt Quick ».
states : list<State>
Esta propiedad contiene la lista de estados posibles para este elemento. Para cambiar el estado de este elemento, establece la propiedad « state » en uno de estos estados, o bien establece la propiedad « state » en una cadena vacía para restablecer el estado predeterminado del elemento.
Esta propiedad se especifica como una lista de objetos State. Por ejemplo, a continuación se muestra un elemento con los estados «red_color» y «blue_color»:
import QtQuick 2.0
Rectangle {
id: root
width: 100; height: 100
states: [
State {
name: "red_color"
PropertyChanges { root.color: "red" }
},
State {
name: "blue_color"
PropertyChanges { root.color: "blue" }
}
]
}Consulte «Estados deQt Quick » y «Animación y transiciones en Qt Quick » para obtener más detalles sobre el uso de estados y transiciones.
Véase también « transitions ».
transform : list<Transform> [read-only]
Esta propiedad contiene la lista de transformaciones que se deben aplicar.
Esta propiedad se especifica como una lista de objetos derivados de ` Transform`. Por ejemplo:
import QtQuick
Image {
source: "images/qt-logo.png"
transform: [
Scale { origin.x: 25; origin.y: 25; xScale: 1.25 },
Rotation { origin.x: 45; origin.y: 55; angle: 45 }
]
}Para obtener más información, consulta Transform.
transformOrigin : enumeration
Esta propiedad define el punto de origen alrededor del cual se realizan las transformaciones de escala y rotación.
Hay nueve orígenes de transformación disponibles, tal y como se muestra en la imagen siguiente. El origen de transformación predeterminado es Item.Center.

En este ejemplo se gira una imagen en torno a su esquina inferior derecha.
Image {
source: "myimage.png"
transformOrigin: Item.BottomRight
rotation: 45
}Para establecer un punto de origen de transformación arbitrario, utiliza los tipos de transformación « Scale » o « Rotation » con « transform ».
transitions : list<Transition>
Esta propiedad contiene la lista de transiciones de este elemento. Estas definen las transiciones que se aplicarán al elemento cada vez que cambie su « state ».
Esta propiedad se especifica como una lista de objetos « Transition ». Por ejemplo:
import QtQuick 2.0
Item {
transitions: [
Transition {
//...
},
Transition {
//...
}
]
}Consulte «Estados deQt Quick » y «Animación y transiciones» en Qt Quick para obtener más detalles sobre el uso de estados y transiciones.
Véase también « states ».
visible : bool
Esta propiedad indica si el elemento está visible. Por defecto, su valor es «true».
Al configurar esta propiedad, se modifica directamente el valor de « visible » de los elementos secundarios. Cuando se establece en « false », los valores de « visible » de todos los elementos secundarios también pasan a ser « false ». Cuando se establece en « true », los valores de « visible » de los elementos secundarios vuelven a ser « true », a menos que se hayan establecido explícitamente en « false ».
(Debido a este comportamiento derivado, el uso de la propiedad « visible » puede no tener el efecto deseado si un enlace de propiedad solo debe responder a cambios explícitos en la propiedad. En tales casos, puede ser mejor utilizar la propiedad « opacity » en su lugar).
Si esta propiedad se establece en « false », el elemento dejará de recibir eventos del ratón, pero seguirá recibiendo eventos de teclado y conservará la propiedad « focus » del teclado si se ha establecido. (Por el contrario, establecer la propiedad « enabled » en « false » detiene tanto los eventos del ratón como los del teclado, y además retira el foco del elemento.)
Nota: El valor deesta propiedad solo se ve afectado por cambios en esta misma propiedad o en la propiedad visible del elemento padre. No cambia, por ejemplo, si este elemento se desplaza fuera de la pantalla o si el opacity cambia a 0.
Véase también « opacity » y « enabled ».
visibleChildren : list<Item>
Esta propiedad de solo lectura enumera todos los elementos secundarios del elemento que están visibles en este momento. Ten en cuenta que la visibilidad de un elemento secundario puede haber cambiado de forma explícita o porque haya cambiado la visibilidad de este elemento (su padre) o de otro bisabuelo.
z : real
Establece el orden de superposición de los elementos hermanos. Por defecto, el orden de superposición es 0.
Los elementos con un valor de superposición mayor se dibujan encima de los elementos hermanos con un orden de superposición menor. Los elementos con el mismo valor de superposición se dibujan de abajo hacia arriba, en el orden en que aparecen. Los elementos con un valor de superposición negativo se dibujan debajo del contenido de su elemento padre.
El siguiente ejemplo muestra los distintos efectos del orden de superposición.
| Mismo valor de « z »: los elementos hijos posteriores se sitúan encima de los anteriores:
|
| z o más alto en la parte superior:
|
| Mismo « z » — los hijos por encima de los padres:
|
| z inferior:
|
Documentación del método
Item childAt(real x, real y)
Devuelve el primer elemento secundario visible que se encuentre en el punto (x, y) dentro del sistema de coordenadas de este elemento.
Devuelve ` null ` si no existe dicho elemento.
bool contains(point point)
Devuelve « true » si este elemento contiene « point », que está en coordenadas locales; en caso contrario, devuelve « false ». Se trata de la misma comprobación que se utiliza para la prueba de colisión de un « QEventPoint » durante la entrega de eventos, y se ve afectada por « containmentMask » si está activada.
[since 6.3] void dumpItemTree()
Muestra algunos detalles sobre el árbol visual de los elementos, empezando por este elemento y sus hijos, de forma recursiva.
El resultado es similar al de este código QML:
function dump(object, indent) {
console.log(indent + object)
for (const i in object.children)
dump(object.children[i], indent + " ")
}
dump(myItem, "")Así que, si quieres más detalles, puedes implementar tu propia función y añadir información adicional a `console.log`, como los valores de propiedades específicas.
Este método se introdujo en Qt 6.3.
Véase también QObject::dumpObjectTree().
void forceActiveFocus()
Establece el foco en el elemento.
Este método establece el foco en el elemento y garantiza que todos los objetos FocusScope anteriors de la jerarquía de objetos también reciban focus.
El motivo del cambio de foco será Qt::OtherFocusReason. Utilice el método sobrecargado para especificar el motivo del foco y permitir así una mejor gestión del cambio de foco.
Véase también activeFocus.
void forceActiveFocus(Qt::FocusReason reason)
Establece el foco activo en el elemento con el reason especificado.
Este método establece el foco en el elemento y garantiza que a todos los objetos « FocusScope » anteros en la jerarquía de objetos también se les asigne el valor « focus ».
Se trata de una función sobrecargada.
Véase también activeFocus y Qt::FocusReason.
bool grabToImage(callback, targetSize)
Recoge el elemento en una imagen en memoria.
La captura se realiza de forma asíncrona y, cuando finaliza, se invoca la función JavaScript ` callback `. La función de devolución de llamada admite un único argumento, que es el resultado de la operación de captura: un objeto ` ItemGrabResult `.
Utiliza ` targetSize ` para especificar el tamaño de la imagen de destino. Por defecto, el resultado tendrá el mismo tamaño que el elemento.
Si no se ha podido iniciar la captura, la función devuelve ` false`.
El siguiente fragmento de código muestra cómo capturar un elemento y guardar los resultados en un archivo:
Rectangle {
id: sourceRectangle
width: 100
height: 100
focus: true
gradient: Gradient {
GradientStop { position: 0; color: "steelblue" }
GradientStop { position: 1; color: "black" }
}
Keys.onSpacePressed: {
sourceRectangle.grabToImage(function(result) {
result.saveToFile("something.png")
})
}
}El siguiente fragmento de código muestra cómo capturar un elemento y utilizar los resultados en otro elemento de imagen:
Image {
id: image
}
Keys.onSpacePressed: {
sourceRectangle.grabToImage(function(result) {
image.source = result.url
}, Qt.size(50, 50))
}Nota: Esta función renderizará el elemento en una superficie fuera de pantalla y copiará dicha superficie de la memoria de la GPU a la de la CPU, lo que puede resultar bastante costoso. Para obtener una vista previa «en directo», utiliza layers o ShaderEffectSource.
point mapFromGlobal(real x, real y)
Asigna el punto (x, y), que se encuentra en el sistema de coordenadas global, al sistema de coordenadas del elemento, y devuelve un point que coincide con la coordenada asignada.
En la asignación se utilizan las siguientes propiedades del elemento: x, y, scale, rotation, transformOrigin y transform.
Si los elementos forman parte de escenas diferentes, la asignación incluye la posición relativa de las dos escenas.
point mapFromItem(Item item, real x, real y)
point mapFromItem(Item item, point p)
rect mapFromItem(Item item, real x, real y, real width, real height)
rect mapFromItem(Item item, rect r)
Asigna el punto (x, y) o el rectángulo (x, y, width, height), que se encuentra en el sistema de coordenadas de item, al sistema de coordenadas de este elemento, y devuelve un point o un rect que coincide con la coordenada asignada.
En la asignación se utilizan las siguientes propiedades del elemento: x, y, scale, rotation, transformOrigin y transform.
Si los elementos forman parte de escenas diferentes, la asignación incluye la posición relativa de las dos escenas.
Si ` item ` es un valor de tipo ` null `, esto asigna el punto o el rectángulo desde el sistema de coordenadas de la escena.
Las versiones que admiten «point» y «rect» están disponibles a partir de Qt 5.15.
point mapToGlobal(real x, real y)
Asigna el punto (x, y), que se encuentra en el sistema de coordenadas de este elemento, al sistema de coordenadas global, y devuelve un point que coincide con la coordenada asignada.
En la mapeación se utilizan las siguientes propiedades del elemento: x, y, scale, rotation, transformOrigin y transform.
Si los elementos forman parte de escenas diferentes, la correspondencia incluye la posición relativa de las dos escenas.
point mapToItem(Item item, real x, real y)
point mapToItem(Item item, point p)
rect mapToItem(Item item, real x, real y, real width, real height)
rect mapToItem(Item item, rect r)
Asigna el punto (x, y) o el rectángulo (x, y, width, height), que se encuentra en el sistema de coordenadas de este elemento, al sistema de coordenadas de item, y devuelve un point o un rect que coincide con la coordenada asignada.
En la asignación se utilizan las siguientes propiedades del elemento: x, y, scale, rotation, transformOrigin y transform.
Si los elementos forman parte de escenas diferentes, la asignación incluye la posición relativa de las dos escenas.
Si ` item ` es un valor de tipo ` null `, esto asigna el punto o el rectángulo al sistema de coordenadas de la escena.
Las versiones que admiten «point» y «rect» son a partir de Qt 5.15.
Item nextItemInFocusChain(bool forward)
Devuelve el elemento de la cadena de enfoque que se encuentra junto a este elemento. Si forward es true, o no se ha especificado, se trata del siguiente elemento en la dirección hacia delante. Si forward es false, se trata del siguiente elemento en la dirección hacia atrás.
© 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.











