Item QML Type

Un tipo visual básico de QML. Más...

• Lista de todos los miembros, incluidos los heredados

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
• 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 en 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 ser ú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 ítems pueden utilizar manejadores de entrada para gestionar los eventos de entrada entrantes (subclases de QInputEvent), como eventos de ratón, táctiles y de teclas. Esta es la forma declarativa preferida para manejar eventos.

Una forma alternativa de manejar eventos táctiles es subclasificar QQuickItem, llamar a setAcceptTouchEvents() en el constructor, y anular touchEvent(). Accept todo el evento para detener la entrega a los elementos por debajo, y para agarrar exclusivamente para todos los puntos táctiles del evento. Utiliza QPointerEvent::setExclusiveGrabber() para capturar sólo ciertos puntos de contacto y permitir que el evento se siga transmitiendo.

Del mismo modo, una subclase de QQuickItem puede llamar a setAcceptedMouseButtons() para registrarse para recibir eventos de botón de ratón, setAcceptHoverEvents() para recibir eventos hover (movimientos de ratón mientras no se pulsa ningún botón), y anular las funciones virtuales mousePressEvent(), mouseMoveEvent(), y mouseReleaseEvent(). Éstas también pueden aceptar el evento para evitar su envío y obtener un agarre implícito al mismo tiempo; o explícitamente grab el único QEventPoint que lleva el QMouseEvent.

El manejo de teclas está disponible para todos los tipos visuales basados en ítems 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 maneja la tecla izquierda a través del manejador general onPressed y la tecla de retorno a través del manejador 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.

Duplicación de diseños

El diseño de los elementos puede reflejarse utilizando la propiedad adjunta LayoutMirroring. Esto hace que anchors se invierta horizontalmente, y también hace que los elementos que maquetan o posicionan a sus hijos (como ListView o Row) inviertan horizontalmente la dirección de sus maquetaciones.

Véase LayoutMirroring para más detalles.

Capas de elementos

Normalmente, un elemento se muestra directamente en la ventana a la que pertenece. Sin embargo, configurando layer.enabled, es posible delegar el elemento y todo su subárbol en una superficie fuera de la pantalla. Sólo la superficie fuera de pantalla, una textura, se dibujará en la ventana.

Si se desea que el tamaño de la textura sea diferente al del elemento, esto es posible utilizando layer.textureSize. Para representar sólo 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á la interpolación lineal para el escalado si layer.smooth se establece en true y utilizará el mipmap para el muestreo descendente si layer.mipmap se establece en true. El mipmapping puede mejorar la calidad visual de los elementos reducidos. Para mipmapping de elementos de una sola Imagen, prefiera Image::mipmap.

Opacidad de capa vs. Opacidad de elemento

Cuando se aplica opacity a una jerarquía de elementos, la opacidad se aplica a cada elemento individualmente. Esto puede dar lugar a resultados visuales no deseados cuando la opacidad se aplica a un subárbol. Considere el siguiente ejemplo:

Opacidad sin capas Item { id: nonLayered opacity: 0.5 width: 100 height: 100 Rectangle { width: 80; height: 80; border.width: 1 } Rectangle { x: 20; y: 20; width: 80; height: 80; border.width: 1 } }

Una capa se renderiza con la opacidad del elemento raíz a 1, y luego la opacidad del elemento raíz se aplica a la textura cuando se dibuja. Esto significa que el desvanecimiento en una gran jerarquía de elementos de transparente a opaco, o viceversa, se puede hacer sin los artefactos de superposición que tiene la mezcla alfa normal elemento por elemento. Aquí está el mismo ejemplo con la capa activada:

Item {
    id: layered

    opacity: 0.5

    layer.enabled: true

    width: 100
    height: 100

    Rectangle { width: 80; height: 80; border.width: 1 }
    Rectangle { x: 20; y: 20; width: 80; height: 80; border.width: 1 }
}

Combinado con ShaderEffects

Establecer layer.enabled a true convertirá el ítem en un texture provider, haciendo posible usar el ítem directamente como una 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"
    }
}

Véase ShaderEffect para más información sobre el uso de efectos.

Memoria y rendimiento

Cuando se activa la capa de un elemento, el gráfico de escena asignará memoria en la GPU igual a width x height x 4. En configuraciones con restricciones de memoria, las capas grandes deben utilizarse con cuidado.

En el mundo QPainter / QWidget, a veces es favorable 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 de gráficos de escena, esto no será así en la mayoría de los casos. El exceso de llamadas a dibujo ya se ha reducido 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 de renderizar a un elemento fuera de la pantalla y la mezcla que implica dibujar la textura resultante es a menudo más costosa que simplemente dejar que el elemento y sus hijos se dibujen normalmente.

Además, un elemento que utiliza una capa no se puede procesar por lotes durante el renderizado. Esto significa que una escena con muchos elementos en capas puede tener problemas de rendimiento.

Las capas pueden ser convenientes y útiles para efectos visuales, pero en la mayoría de los casos deberían activarse mientras dure el efecto y desactivarse después.

Documentación de propiedades

activeFocus : bool [read-only]

Esta propiedad de sólo lectura indica si el elemento tiene el foco activo.

Si activeFocus es verdadero, este elemento es el que actualmente recibe la entrada del teclado, o es un FocusScope ancestro del elemento que actualmente recibe la entrada del teclado.

Normalmente, activeFocus se obtiene estableciendo focus en un elemento y en los objetos FocusScope que lo rodean. En el siguiente ejemplo, los objetos input y focusScope tendrán el foco activo, mientras que el objeto rectángulo 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 Keyboard Focus en Qt Quick.

activeFocusOnTab : bool

Esta propiedad indica si el elemento quiere estar en la cadena de enfoque de la pestaña. Por defecto, se establece en false.

La cadena de tabuladores recorre los elementos visitando primero el elemento padre y luego sus elementos hijos en el orden en que aparecen en la propiedad children. Al pulsar la tecla tabulador en un elemento de la cadena de tabuladores, el foco del teclado se desplaza al siguiente elemento de la cadena. Pulsando BackTab (normalmente Shift+Tab) se moverá el foco al elemento anterior.

Para configurar una cadena de tabulación manual, consulte KeyNavigation. Los eventos de la tecla Tab utilizados por Keys o KeyNavigation tienen precedencia sobre el comportamiento de la cadena de enfoque; ignora los eventos en otros manejadores de teclas para permitir que se propague.

Véase también QStyleHints::tabFocusBehavior y focusPolicy.

anchors group

Las anclas permiten posicionar un elemento especificando su relación con otros elementos.

Los márgenes se aplican a las anclas superior, inferior, izquierda, derecha y de relleno. La propiedad anchors.margins puede utilizarse 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 borrar un margen explícito, establezca su valor en undefined. Tenga en cuenta que los márgenes son específicos de las anclas y no se aplican si un elemento no utiliza anclas.

Los desplazamientos se aplican a los anclajes horizontal central, vertical central y de línea de base.

Item {
    Image {
        id: pic
        // ...
    }
    Text {
        id: label
        anchors.horizontalCenter: pic.horizontalCenter
        anchors.top: pic.bottom
        anchors.topMargin: 5
        // ...
    }
}

Item {
    Image {
        id: pic
        // ...
    }
    Text {
        id: label
        anchors.left: pic.right
        anchors.leftMargin: 5
        // ...
    }
}

anchors.fill proporciona una forma conveniente para que un elemento tenga la misma geometría que otro elemento, y es equivalente a conectar las cuatro anclas direccionales.

Para borrar un valor de anclaje, ajústelo a undefined.

anchors.alignWhenCentered (por defecto true) fuerza a los anclajes centrados a alinearse en un píxel entero; si el elemento que se está centrando tiene un valor impar width o height, el elemento se posicionará en un píxel entero en lugar de colocarse en medio píxel. Esto asegura que el elemento se pinte nítidamente. Hay casos en los que esto no es deseable, por ejemplo, al rotar el elemento pueden aparecer vibraciones al redondearse el centro.

Para más información, consulte Anclar diseños.

antialiasing : bool

Utilizado por los elementos visuales para decidir si el elemento debe utilizar antialiasing o no. En algunos casos los elementos con antialiasing requieren más memoria y son potencialmente más lentos de renderizar (ver Antialiasing para más detalles).

Por defecto es false, pero puede ser anulado por elementos derivados.

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 fijar su línea de base en la línea de base de su texto.

Para los elementos que no contienen texto, se utiliza una línea de base por defecto de 0.

La propiedad children contiene la lista de hijos visuales de este elemento. La propiedad resources contiene los recursos no visuales a los que se desea hacer referencia por su nombre.

Generalmente no es necesario hacer referencia a estas propiedades cuando se añaden elementos o recursos hijos, ya que la propiedad por defecto data asignará automáticamente objetos hijos a las propiedades children y resources según corresponda. Consulte la documentación de data para más detalles.

childrenRect group

Esta propiedad de sólo lectura contiene la posición colectiva y el tamaño de los elementos hijos.

Esta propiedad es útil si necesitas acceder a la geometría colectiva de los hijos de un elemento para dimensionar correctamente el elemento.

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 indica si el recorte está activado. El valor de recorte por defecto es false.

Si el recorte está habilitado, un elemento recortará su propia pintura, así como la pintura de sus hijos, a su rectángulo delimitador.

containmentMask : QObject*

Esta propiedad contiene una máscara opcional para el elemento que se utilizará en el método contains(). Su uso principal es actualmente determinar si un pointer event ha aterrizado en el elemento o no.

Por defecto, el método contains() devolverá verdadero para cualquier punto dentro del cuadro delimitador del elemento. containmentMask permite un control más preciso. Por ejemplo, si se utiliza una subclase de C++ QQuickItem con un método especializado contains() como containmentMask:

Item { id: item; containmentMask: AnotherItem { id: anotherItem } }

el método contains deitem devolvería true sólo si la implementación contains() de anotherItem devuelve true.

Un Shape puede utilizarse como máscara, para hacer que un elemento reaccione a pointer events sólo dentro de una región no rectangular:

Rectangle { width: 90; height: 100 color: hoverHandler.hovered ? "wheat" : "lightgray" containmentMask: shape HoverHandler { id: hoverHandler } Shape { id: shape containsMode: Shape.FillContains ShapePath { fillColor: "lightsteelblue" startX: 10; startY: 20 PathArc { x: 10; y: 80 radiusX: 40; radiusY: 40 useLargeArc: true } PathLine { x: 10; y: 20 } } } }

También es posible definir el método contains en QML. Por ejemplo, para crear un elemento circular que sólo responda a eventos dentro de sus límites reales:

Rectangle { id: circle width: 100; height: width radius: width / 2 color: tapHandler.pressed ? "tomato" : hoverHandler.hovered ? "darkgray" : "lightgray" TapHandler { id: tapHandler } HoverHandler { id: hoverHandler } containmentMask: QtObject { property alias radius: circle.radius function contains(point: point) : bool { return (Math.pow(point.x - radius, 2) + Math.pow(point.y - radius, 2)) < Math.pow(radius, 2) } } }

Véase también Qt Quick Ejemplos - Formas.

data : list<QtObject> [default]

La propiedad data permite mezclar libremente hijos visuales y recursos en un elemento. Si asignas un elemento visual a la lista de datos se convierte en un hijo y si asignas cualquier otro tipo de objeto, se añade como recurso.

Así que puedes escribir

Item {
    Text {}
    Rectangle {}
    Timer {}
}

en lugar de:

Item {
    children: [
        Text {},
        Rectangle {}
    ]
    resources: [
        Timer {}
    ]
}

En general, no debería ser necesario hacer referencia a la propiedad data, ya que es la propiedad por defecto de Item y, por tanto, todos los ítems hijos se asignan automáticamente a esta propiedad.

enabled : bool

Esta propiedad indica si el elemento recibe eventos de ratón y teclado. Por defecto, es true.

Cuando se establece a false, el elemento no recibe eventos de teclado o dispositivo señalador, como pulsar, soltar o hacer clic, pero aún puede recibir eventos hover.

Establecer esta propiedad afecta directamente al valor enabled de los elementos hijos. Cuando se establece a false, los valores de enabled de todos los elementos hijos también se convierten en false. Cuando se establece a true, los valores de enabled de los ítems hijos vuelven a true, a menos que hayan sido explícitamente establecidos a false.

Si se establece esta propiedad a false, activeFocus se establece automáticamente a false, y este elemento dejará de recibir eventos de teclado.

Véase también visible.

focus : bool

Esta propiedad indica si el elemento tiene foco dentro del elemento adyacente FocusScope. Si es true, este elemento obtendrá el foco activo cuando el elemento FocusScope adquiera el foco activo.

En el siguiente ejemplo, input tendrá foco activo cuando scope tenga 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. A nivel práctico, esto significa que el siguiente QML dará foco activo a input al iniciarse.

Rectangle {
    width: 100; height: 100

    TextInput {
          id: input
          focus: true
    }
}

Véase también activeFocus y Keyboard Focus en Qt Quick.

focusPolicy : enumeration [since 6.7]

Esta propiedad determina la forma en que el elemento acepta el foco.

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 a 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, el diseño determinará el tamaño preferido del elemento utilizando su tamaño implícito. En este caso, se ignorará el tamaño explícito 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 puede ser anulado, por ejemplo, Image y Text.

Establecer el tamaño implícito es útil para definir componentes que tienen un tamaño preferido basado en 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
    }
}

layer.effect : Component

Contiene el efecto que se aplica a esta capa.

El efecto suele ser un componente ShaderEffect, aunque se puede asignar cualquier componente Item. El efecto debe tener una propiedad de textura de origen con un nombre que coincida con layer.samplerName.

Véase también layer.samplerName y Item Layers.

layer.enabled : bool

Indica si el elemento tiene capas o no. La estratificación está desactivada por defecto.

Un elemento estratificado se renderiza en una superficie fuera de la pantalla y se almacena en caché hasta que se cambia. Habilitar la estratificación para jerarquías complejas de elementos QML puede ser a veces una optimización.

Ninguna de las otras propiedades de capa tiene efecto 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 tiene más sentido cuando también se especifica layer.effect.

Véase también Item Layers.

layer.live : bool [since 6.5]

Cuando esta propiedad es true la textura de la capa se actualiza cada vez que se actualiza el elemento. En caso contrario siempre será una imagen congelada.

Por defecto, esta propiedad está establecida a true.

Esta propiedad se introdujo en Qt 6.5.

Véase también Item Layers.

layer.mipmap : bool

Si esta propiedad es true, se generan mipmaps para la textura.

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.

Ver también layer.effect, ShaderEffect, y Item Layers.

layer.samples : enumeration

Esta propiedad permite solicitar renderizado multimuestreo en la capa.

Por defecto, el multimuestreo se habilita siempre que el multimuestreo esté habilitado para toda la ventana, suponiendo que el renderizador de scenegraph en uso y la API gráfica subyacente lo soporten.

Estableciendo el valor a 2, 4, etc. se puede solicitar el multimuestreo para una parte de la escena sin habilitar el multimuestreo para toda la escena. De esta forma, el multimuestreo se aplica sólo a un subárbol determinado, lo que puede suponer un aumento significativo del rendimiento, ya que el multimuestreo no se aplica a otras partes de la escena.

layer.smooth : bool

Indica si la capa se transforma suavemente. Cuando está activada, el muestreo de la textura de la capa se realiza utilizando la interpolación linear, mientras que si no es suave 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 ítem que debe ser renderizada en la textura. El rectángulo de origen puede ser mayor que el propio elemento. Si el rectángulo es nulo, que es el valor por defecto, entonces todo el elemento se renderiza 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 ser útil si la textura generada es accedida directamente por shaders personalizados, como los especificados por ShaderEffect. Si no se especifica ningún efecto para el elemento en capas, el reflejo no tiene ningún efecto en la representación UI del elemento.

layer.textureSize : size

Esta propiedad contiene el tamaño en píxeles solicitado para la textura de las capas. Si está vacía, que es el valor por defecto, se utiliza el tamaño del elemento.

Véase también Item Layers.

layer.wrapMode : enumeration

Esta propiedad define los modos de envoltura asociados a la textura. Modificar esta propiedad tiene más sentido cuando se especifica layer.effect.

Véase también Item Layers.

opacity : real

Esta propiedad contiene la opacidad del elemento. La opacidad se especifica como un número 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 hijos. Esto puede tener un efecto no deseado en algunas circunstancias. Por ejemplo, en el segundo conjunto de rectángulos de abajo, el rectángulo rojo ha especificado una opacidad de 0,5, que afecta a la opacidad de su rectángulo azul hijo, aunque el hijo no haya especificado una opacidad.

Item {
    Rectangle {
        color: "red"
        width: 100; height: 100
        Rectangle {
            color: "blue"
            x: 50; y: 50; width: 100; height: 100
        }
    }
}

Item {
    Rectangle {
        opacity: 0.5
        color: "red"
        width: 100; height: 100
        Rectangle {
            color: "blue"
            x: 50; y: 50; width: 100; height: 100
        }
    }
}

Cambiar la opacidad de un elemento no afecta a si el elemento recibe eventos de entrada del usuario. (Por el contrario, establecer la propiedad visible a false detiene los eventos de ratón, y establecer la propiedad enabled a false detiene los eventos de ratón y teclado, y también elimina 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 para el elemento. La paleta es utilizada por el estilo del ítem cuando renderiza todos los controles, y está disponible como un medio para asegurar que los controles personalizados puedan mantener la consistencia con la apariencia nativa de la plataforma. Es común que diferentes plataformas, o diferentes estilos, definan diferentes paletas 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 especiales por defecto para ciertos tipos de controles. También puede establecer la paleta predeterminada para los controles, ya sea:

• pasando una paleta personalizada a QGuiApplication::setPalette(), antes de cargar cualquier QML; o bien
• especificando los colores en el archivo qtquickcontrols2.conf.

Los elementos propagan las propiedades explícitas de la paleta de padres a hijos. Si se cambia una propiedad específica de la paleta de un elemento, esa propiedad se propaga a todos los elementos hijos, anulando cualquier valor predeterminado del sistema para esa propiedad.

Item {
    palette {
        buttonText: "maroon"
        button: "lavender"
    }

    Button {
        text: "Click Me"
    }
}

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.

rotation : real

Esta propiedad contiene la rotación del elemento en grados en el sentido de las agujas del reloj alrededor de su transformOrigin.

El valor por defecto es 0 grados (es decir, sin rotación).

Rectangle {
    color: "blue"
    width: 100; height: 100
    Rectangle {
        color: "red"
        x: 25; y: 25; width: 50; height: 50
        rotation: 30
    }
}

Véase también Transform y Rotation.

scale : real

Esta propiedad contiene el factor de escala para este elemento.

Una escala inferior a 1,0 hace que el elemento se muestre a un tamaño menor, y una escala superior a 1,0 hace que el elemento se muestre a un tamaño mayor. Una escala negativa hace que el elemento se refleje al renderizarlo.

El valor por defecto es 1.0.

La escala se aplica desde transformOrigin.

import QtQuick 2.0

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

    Rectangle {
        color: "green"
        width: 25; height: 25
    }

    Rectangle {
        color: "red"
        x: 25; y: 25; width: 50; height: 50
        scale: 1.4
        transformOrigin: Item.TopLeft
    }
}

Véase también Transform y Scale.

smooth : bool

Se utiliza principalmente en elementos basados en imágenes para decidir si el elemento debe utilizar un muestreo suave o no. El muestreo suave se realiza mediante interpolación lineal, mientras que el no suave se realiza mediante el vecino más próximo.

En Qt Quick 2.0, esta propiedad tiene un impacto mínimo en el rendimiento.

Por defecto, esta propiedad está establecida en true.

state : string

Esta propiedad contiene el nombre del estado actual del elemento.

Si el elemento está en su estado por defecto, es decir, no se ha establecido ningún estado explícito, esta propiedad contendrá una cadena vacía. Del mismo modo, puedes devolver un elemento a su estado por defecto estableciendo esta propiedad a una cadena vacía.

Véase también Qt Quick States.

states : list<State>

Esta propiedad contiene la lista de posibles estados para este elemento. Para cambiar el estado de este elemento, establezca la propiedad state a uno de estos estados, o establezca la propiedad state a una cadena vacía para revertir el elemento a su estado por defecto.

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 Qt Quick Estados y Animación y transiciones en Qt Quick para 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 a 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 más información, véase Transform.

transformOrigin : enumeration

Esta propiedad contiene el punto de origen alrededor del cual se transforman la escala y la rotación.

Hay nueve orígenes de transformación disponibles, como se muestra en la siguiente imagen. El origen de transformación por defecto es Item.Center.

Este ejemplo rota una imagen alrededor de su esquina inferior derecha.

Image {
    source: "myimage.png"
    transformOrigin: Item.BottomRight
    rotation: 45
}

Para establecer un punto de origen de transformación arbitrario, utilice los tipos de transformación Scale o Rotation con transform.

transitions : list<Transition>

Esta propiedad contiene la lista de transiciones para 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 {
            //...
        }
    ]
}

Ver Qt Quick Estados y Animación y Transiciones en Qt Quick para más detalles sobre el uso de estados y transiciones.

Véase también states.

visible : bool

Esta propiedad indica si el elemento es visible. Por defecto es true.

Establecer esta propiedad afecta directamente al valor visible de los elementos hijos. Cuando se establece a false, los valores de visible de todos los elementos hijos también se convierten en false. Cuando se establece a true, los valores de visible de los elementos hijos vuelven a true, a menos que se hayan establecido explícitamente a false.

(Debido a este comportamiento, el uso de la propiedad visible puede no tener el efecto deseado si un enlace de propiedad sólo debe responder a cambios explícitos de 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 de ratón, pero seguirá recibiendo eventos de teclado y conservará el teclado focus si se ha establecido. (Por el contrario, establecer la propiedad enabled a false detiene tanto los eventos de ratón como de teclado, y también elimina el foco del elemento).

Véase también opacity y enabled.

visibleChildren : list<Item>

Esta propiedad de sólo lectura lista todos los ítems hijos que son actualmente visibles. Tenga en cuenta que la visibilidad de un hijo puede haber cambiado explícitamente, o porque la visibilidad de este elemento (su padre) o de otro abuelo ha cambiado.

z : real

Establece el orden de apilamiento de los elementos hermanos. Por defecto, el orden de apilamiento es 0.

Los elementos con un valor de apilamiento mayor se dibujan encima de sus hermanos con un orden de apilamiento menor. Los elementos con el mismo valor de apilamiento se dibujan de abajo hacia arriba en el orden en que aparecen. Los elementos con un valor de apilamiento negativo se dibujan debajo del contenido de su padre.

El siguiente ejemplo muestra los distintos efectos del orden de apilamiento.

Item {
    Rectangle {
        color: "red"
        width: 100; height: 100
    }
    Rectangle {
        color: "blue"
        x: 50; y: 50; width: 100; height: 100
    }
}

Item {
    Rectangle {
        z: 1
        color: "red"
        width: 100; height: 100
    }
    Rectangle {
        color: "blue"
        x: 50; y: 50; width: 100; height: 100
    }
}

Item {
    Rectangle {
        color: "red"
        width: 100; height: 100
        Rectangle {
            color: "blue"
            x: 50; y: 50; width: 100; height: 100
        }
    }
}

Item {
    Rectangle {
        color: "red"
        width: 100; height: 100
        Rectangle {
            z: -1
            color: "blue"
            x: 50; y: 50; width: 100; height: 100
        }
    }
}

Método Documentación

Item childAt(real x, real y)

Devuelve el primer elemento hijo visible encontrado en el punto (x, y) dentro del sistema de coordenadas de este elemento.

Devuelve null si no existe tal elemento.

bool contains(point point)

Devuelve true si este elemento contiene point, que está en coordenadas locales; devuelve false en caso contrario. Esta es la misma comprobación que se utiliza para la prueba de acierto de un QEventPoint durante la entrega de eventos, y se ve afectada por containmentMask si está establecido.

[since 6.3] void dumpItemTree()

Vuelca algunos detalles sobre el árbol visual de Elementos empezando por este elemento y sus hijos, recursivamente.

La salida es similar a la 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 salida extra a la console.log, como valores de propiedades específicas.

Este método se introdujo en Qt 6.3.

Véase también QObject::dumpObjectTree().

void forceActiveFocus()

Fuerza el enfoque activo en el elemento.

Este método establece el foco en el elemento y asegura que todos los objetos FocusScope ancestros en la jerarquía de objetos también reciban focus.

La razón del cambio de foco será Qt::OtherFocusReason. Utiliza el método sobrecargado para especificar la razón del foco para permitir un mejor manejo del cambio de foco.

Véase también activeFocus.

void forceActiveFocus(Qt::FocusReason reason)

Fija el foco activo en el elemento con el valor reason.

Este método establece el foco en el elemento y asegura que todos los objetos FocusScope ancestros en la jerarquía de objetos también reciben focus.

Véase también activeFocus y Qt::FocusReason.

bool grabToImage(callback, targetSize)

Recoge el elemento en una imagen en memoria.

La captura se produce de forma asíncrona y la función de JavaScript callback se invoca cuando se completa la captura. La llamada de retorno recibe un argumento, que es el resultado de la operación de captura: un objeto ItemGrabResult.

Utilice 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 operación de captura, la función devuelve false.

El siguiente fragmento muestra cómo capturar un elemento y almacenar 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 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))
}

point mapFromGlobal(real x, real y)

Mapea el punto (x, y), que está en el sistema de coordenadas global, al sistema de coordenadas del elemento, y devuelve un point que coincide con la coordenada mapeada.

Las siguientes propiedades del elemento se utilizan en el mapeo: x, y, scale, rotation, transformOrigin, y transform.

Si los elementos forman parte de escenas diferentes, el mapeo incluye la posición relativa de las dos escenas.

Mapea el punto (x, y) o rect (x, y, width, height), que está en el sistema de coordenadas de item, al sistema de coordenadas de este elemento, y devuelve un point o rect que coincide con la coordenada mapeada.

Las siguientes propiedades del elemento se utilizan en la asignación: 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 null, esto mapea el punto o rect desde el sistema de coordenadas de la escena.

Las versiones que aceptan point y rect son desde Qt 5.15.

point mapToGlobal(real x, real y)

Mapea 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 mapeada.

Las siguientes propiedades del elemento se utilizan en el mapeo: x, y, scale, rotation, transformOrigin, y transform.

Si los elementos forman parte de escenas diferentes, el mapeo incluye la posición relativa de las dos escenas.

Mapea el punto (x, y) o rect (x, y, width, height), que está en el sistema de coordenadas de este elemento, al sistema de coordenadas de item, y devuelve un point o rect que coincide con la coordenada mapeada.

Las siguientes propiedades del elemento se utilizan en el mapeo: 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 null, esto mapea el punto o rect al sistema de coordenadas de la escena.

Las versiones que aceptan point y rect son desde 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 proporciona, es el siguiente elemento en la dirección hacia delante. Si forward es false, es el siguiente elemento en la dirección hacia atrás.