Image QML Type

Muestra una imagen. Más...

• Lista de todos los miembros, incluidos los heredados

Propiedades

• asynchronous : bool
• autoTransform : bool
• cache : bool
• currentFrame : int
• fillMode : enumeration
• frameCount : int
• horizontalAlignment : enumeration
• mipmap : bool
• mirror : bool
• mirrorVertically : bool (since 6.2)
• paintedHeight : real
• paintedWidth : real
• progress : real
• retainWhileLoading : bool (since 6.8)
• smooth : bool
• source : url
• sourceClipRect : rect
• sourceSize : size
• status : enumeration
• verticalAlignment : enumeration

Descripción detallada

El tipo Imagen muestra una imagen.

La fuente de la imagen se especifica como una URL utilizando la propiedad source. Las imágenes pueden suministrarse en cualquiera de los formatos de imagen estándar soportados por Qt, incluyendo formatos de mapa de bits como PNG y JPEG, y formatos de gráficos vectoriales como SVG. Si necesita mostrar imágenes animadas, utilice AnimatedSprite o AnimatedImage.

Si no se especifican las propiedades width y height, la Imagen utiliza automáticamente el tamaño de la imagen cargada. Por defecto, al especificar la anchura y la altura del elemento, la imagen se escala a ese tamaño. Este comportamiento puede cambiarse estableciendo la propiedad fillMode, permitiendo en su lugar que la imagen sea estirada y embaldosada.

Es posible proporcionar "@nx" high DPI syntax.

Ejemplo de uso

El siguiente ejemplo muestra el uso más sencillo del tipo Imagen.

import QtQuick

Image {
    source: "pics/qtlogo.png"
}

Archivos de textura comprimidos

Cuando la implementación de la API gráfica subyacente lo permite en tiempo de ejecución, las imágenes también pueden suministrarse en archivos de textura comprimida. El contenido debe ser una simple textura 2D en formato RGB(A). Los esquemas de compresión admitidos sólo están limitados por el controlador y la GPU subyacentes. Se admiten los siguientes formatos de archivos contenedores:

• PKM (desde Qt 5.10)
• KTX (desde Qt 5.11)
• ASTC (desde Qt 5.13)

transform: [ Translate { y: -myImage.height }, Scale { yScale: -1 } ]

o

mirrorVertically: true

convert foo.png \( +clone -alpha Extract \) -channel RGB -compose Multiply -composite foo_pm.png

No confunda los formatos contenedores, tales como, KTX, y el formato de los datos de textura reales almacenados en el archivo contenedor. Por ejemplo, la lectura de un archivo KTX es compatible con todas las plataformas, independientemente del controlador de GPU que se utilice en tiempo de ejecución. Sin embargo, esto no garantiza que el formato de textura comprimido, utilizado por los datos del archivo, sea compatible en tiempo de ejecución. Por ejemplo, si el archivo KTX contiene datos comprimidos con el formato ETC2 RGBA8, y la implementación de la API de gráficos 3D utilizada en tiempo de ejecución no admite las texturas comprimidas ETC2, el elemento Imagen no mostrará nada.

No asumas que el soporte de formatos comprimidos es específico de una plataforma. También puede ser específico del controlador y de la implementación de la API 3D en uso en esa plataforma concreta. En la práctica, las implementaciones de diferentes API de gráficos 3D (por ejemplo, Vulkan y OpenGL) en la misma plataforma (por ejemplo, Windows) del mismo proveedor para el mismo hardware pueden ofrecer un conjunto diferente de formatos de textura comprimida.

Cuando el objetivo son los entornos de escritorio (Windows, macOS, Linux) únicamente, una recomendación general es considerar el uso de los formatos DXTn/BCn ya que estos tienden a tener el soporte más amplio entre las implementaciones de Direct 3D, Vulkan, OpenGL y Metal en estas plataformas. Por el contrario, cuando se trata de dispositivos móviles o integrados, es probable que los formatos ETC2 o ASTC sean una mejor opción, ya que suelen ser los formatos compatibles con las implementaciones de OpenGL ES en este tipo de hardware.

Una aplicación que pretenda ejecutarse en equipos de sobremesa, móviles e integrados debe planificar y diseñar cuidadosamente el uso de texturas comprimidas. Es muy probable que confiar en un único formato no sea suficiente y, por lo tanto, la aplicación tendrá que diversificarse en función de la plataforma para utilizar texturas comprimidas en un formato adecuado, o tal vez omitir el uso de texturas comprimidas en algunos casos.

Detección automática de la extensión del archivo

Si la URL source indica un archivo o recurso local inexistente, el elemento Imagen intenta detectar automáticamente la extensión del archivo. Si se puede encontrar un archivo existente añadiendo a la URL source cualquiera de las extensiones de archivo de imagen admitidas, se cargará dicho archivo.

La búsqueda de archivos intenta buscar primero extensiones de archivos contenedores de texturas comprimidas. Si la búsqueda no tiene éxito, intenta buscar con las extensiones de archivo para el conventional image file types. Por ejemplo:

// Assuming the "pics" directory contains the following files:
//   dog.jpg
//   cat.png
//   cat.pkm

Image {
    source: "pics/cat.png"     // loads cat.png
}

Image {
    source: "pics/dog"         // loads dog.jpg
}

Image {
    source: "pics/cat"         // normally loads cat.pkm, but if no OpenGL, loads cat.png instead.
}

Esta funcionalidad facilita el despliegue de diferentes tipos de archivos de activos de imagen en diferentes plataformas de destino. Esto puede ser útil para ajustar el rendimiento de la aplicación y adaptarse a diferentes hardware de gráficos.

Esta funcionalidad se introdujo en Qt 5.11.

Rendimiento

Por defecto, las imágenes disponibles localmente se cargan inmediatamente, y la interfaz de usuario se bloquea hasta que se completa la carga. Si se va a cargar una imagen grande, puede ser preferible cargar la imagen en un hilo de baja prioridad, habilitando la propiedad asynchronous.

Si la imagen se obtiene de una red en lugar de un recurso local, se carga automáticamente de forma asíncrona, y las propiedades progress y status se actualizan según corresponda.

Las imágenes se almacenan en caché y se comparten internamente, por lo que si varios elementos Image tienen el mismo source, sólo se cargará una copia de la imagen.

Nota: Las imágenes suelen ser las que más memoria consumen en las interfaces de usuario QML. Se recomienda que las imágenes que no formen parte de la interfaz de usuario tengan su tamaño limitado mediante la propiedad sourceSize. Esto es especialmente importante para el contenido que se carga desde fuentes externas o que proporciona el usuario.

Véase también Qt Quick Ejemplos - Elementos de imagen, QQuickImageProvider, y QImageReader::setAutoDetectImageFormat().

Documentación de propiedades

asynchronous : bool

Especifica que las imágenes del sistema de archivos local deben cargarse de forma asíncrona en un subproceso separado. El valor por defecto es false, haciendo que el hilo de la interfaz de usuario se bloquee mientras se carga la imagen. Establecer asynchronous a true es útil cuando mantener una interfaz de usuario responsiva es más deseable que tener imágenes inmediatamente visibles.

Tenga en cuenta que esta propiedad sólo es válida para imágenes leídas desde el sistema de archivos local. Las imágenes cargadas a través de un recurso de red (por ejemplo, HTTP) siempre se cargan de forma asíncrona.

autoTransform : bool

Esta propiedad establece si la imagen debe aplicar automáticamente metadatos de transformación de imagen como la orientación EXIF.

Por defecto, esta propiedad es falsa.

cache : bool

Especifica si la imagen debe almacenarse en caché. El valor por defecto es true. Establecer cache a false es útil cuando se trata de imágenes grandes, para asegurarse de que no se almacenan en caché a expensas de las pequeñas imágenes de 'elementos ui'.

currentFrame es el marco visible en ese momento. Por defecto es 0. Puede establecerlo en un número entre 0 y frameCount - 1 para mostrar un marco diferente, si la imagen contiene múltiples marcos.

frameCount es el número de fotogramas de la imagen. La mayoría de las imágenes sólo tienen un fotograma.

fillMode : enumeration

Establezca esta propiedad para definir lo que ocurre cuando la imagen de origen tiene un tamaño diferente al del elemento.

Image {
    width: 130; height: 100
    source: "qtlogo.png"
}

Image {
    width: 130; height: 100
    fillMode: Image.PreserveAspectFit
    source: "qtlogo.png"
}

Image {
    width: 130; height: 100
    fillMode: Image.PreserveAspectCrop
    source: "qtlogo.png"
    clip: true
}

Image {
    width: 120; height: 120
    fillMode: Image.Tile
    horizontalAlignment: Image.AlignLeft
    verticalAlignment: Image.AlignTop
    source: "qtlogo.png"
}

Image {
    width: 120; height: 120
    fillMode: Image.TileVertically
    verticalAlignment: Image.AlignTop
    source: "qtlogo.png"
}

Image {
    width: 120; height: 120
    fillMode: Image.TileHorizontally
    verticalAlignment: Image.AlignLeft
    source: "qtlogo.png"
}

Tenga en cuenta que clip es false por defecto, lo que significa que el elemento podría pintar fuera de su rectángulo de delimitación, incluso si el fillMode se establece en PreserveAspectCrop.

Vea también Qt Quick Ejemplos - Elementos de Imagen.

Establece la alineación horizontal y vertical de la imagen. Por defecto, la imagen se alinea al centro.

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

mipmap : bool

Esta propiedad determina si la imagen utiliza el filtrado mipmap al escalarla o transformarla.

El filtrado mipmap proporciona una mejor calidad visual al reducir la escala en comparación con el suavizado, pero puede tener un coste de rendimiento (tanto al inicializar la imagen como durante el renderizado).

Por defecto, esta propiedad es falsa.

Véase también smooth.

mirror : bool

Esta propiedad indica si la imagen debe ser invertida horizontalmente (mostrando efectivamente una imagen reflejada).

El valor por defecto es false.

mirrorVertically : bool [since 6.2]

Esta propiedad indica si la imagen debe invertirse verticalmente (mostrando una imagen reflejada).

El valor por defecto es false.

Esta propiedad se introdujo en Qt 6.2.

Estas propiedades contienen el tamaño de la imagen que se pinta realmente. En la mayoría de los casos es el mismo que width y height, pero cuando se utiliza un Image.PreserveAspectFit o un Image.PreserveAspectCrop paintedWidth o paintedHeight pueden ser más pequeños o más grandes que width y height del elemento Imagen.

progress : real [read-only]

Esta propiedad contiene el progreso de carga de la imagen, desde 0.0 (nada cargado) hasta 1.0 (finalizado).

Véase también status.

retainWhileLoading : bool [since 6.8]

Esta propiedad define el comportamiento cuando se cambia la propiedad source y la carga se produce de forma asíncrona. Este es el caso cuando la propiedad asynchronous se establece en true, o si la imagen no está en el sistema de archivos local.

Si retainWhileLoading es false (por defecto), la imagen antigua se descarta inmediatamente, y el componente se borra mientras se carga la nueva imagen. Si se establece en true, la imagen antigua se conserva y permanece visible hasta que la nueva esté lista.

Activar esta propiedad puede evitar el parpadeo en los casos en que la carga de la nueva imagen lleve mucho tiempo. Tiene el coste de un uso extra de memoria para el doble buffering mientras se carga la nueva imagen.

Esta propiedad se introdujo en Qt 6.8.

smooth : bool

Esta propiedad determina si la imagen se filtra suavemente al escalarla o transformarla. El filtrado suave proporciona una mejor calidad visual, pero puede ser más lento en algunos equipos. Si la imagen se muestra en su tamaño natural, esta propiedad no tiene ningún efecto visual o de rendimiento.

Por defecto, esta propiedad está establecida en true.

Véase también mipmap.

source : url

Image puede manejar cualquier formato de imagen soportado por Qt, cargado desde cualquier esquema de URL soportado por Qt.

La URL puede ser absoluta o relativa a la URL del componente.

Véase también QQuickImageProvider, Compressed Texture Files, y Automatic Detection of File Extension.

sourceClipRect : rect

Esta propiedad, si está establecida, contiene la región rectangular de la imagen de origen que se va a cargar.

sourceClipRect funciona junto con la propiedad sourceSize para conservar los recursos del sistema cuando sólo es necesario cargar una parte de una imagen.

Rectangle {
    width: ...
    height: ...

    Image {
       anchors.fill: parent
       source: "reallyBigImage.svg"
       sourceSize.width: 1024
       sourceSize.height: 1024
       sourceClipRect: Qt.rect(100, 100, 512, 512)
    }
}

En el ejemplo anterior, primero escalamos conceptualmente el gráfico SVG a 1024x1024 y, a continuación, recortamos una región de interés de 512x512 píxeles desde una ubicación situada a 100 píxeles de los bordes superior e izquierdo. Así, sourceSize determina la escala, pero la imagen de salida real es de 512x512 píxeles.

Algunos formatos de imagen pueden ahorrar tiempo de CPU renderizando sólo la región especificada. Otros necesitarán cargar toda la imagen primero y luego recortarla a la región especificada.

Esta propiedad puede desactivarse para volver a cargar toda la imagen estableciendo sourceClipRect en undefined.

sourceSize : size

Esta propiedad contiene el ancho y alto escalados de la imagen a cuadro completo.

A diferencia de las propiedades width y height, que escalan el cuadro de la imagen, esta propiedad establece el número máximo de píxeles almacenados para la imagen cargada, de forma que las imágenes grandes no utilicen más memoria de la necesaria. Por ejemplo, esto garantiza que la imagen en memoria no sea mayor de 1024x1024 píxeles, independientemente de los valores width y height de la imagen:

Rectangle {
    width: ...
    height: ...

    Image {
       anchors.fill: parent
       source: "reallyBigImage.jpg"
       sourceSize.width: 1024
       sourceSize.height: 1024
    }
}

Si el tamaño real de la imagen es mayor que sourceSize, la imagen se reduce. Si sólo una dimensión del tamaño es mayor que 0, la otra dimensión se ajusta en proporción para preservar la relación de aspecto de la imagen de origen. (La dirección fillMode es independiente de esto).

Si se establecen tanto sourceSize.width como sourceSize.height, la imagen se reducirá para ajustarse al tamaño especificado (a menos que se utilice PreserveAspectCrop o PreserveAspectFit, en cuyo caso se reducirá para ajustarse al tamaño óptimo para recortar/ajustar), manteniendo la relación de aspecto de la imagen. El tamaño real de la imagen después del escalado está disponible a través de Item::implicitWidth y Item::implicitHeight.

Si la fuente es una imagen intrínsecamente escalable (por ejemplo, SVG), esta propiedad determina el tamaño de la imagen cargada independientemente del tamaño intrínseco. Evite cambiar esta propiedad dinámicamente; renderizar un SVG es lento comparado con una imagen.

Si la fuente es una imagen no escalable (p. ej., JPEG), la imagen cargada no será mayor de lo que especifica esta propiedad. Para algunos formatos (actualmente sólo JPEG), la imagen completa nunca se cargará en memoria.

Si la propiedad sourceClipRect también está establecida, sourceSize determina la escala, pero se recortará al tamaño del rectángulo de recorte.

sourceSize se puede borrar al tamaño natural de la imagen estableciendo sourceSize a undefined.

Véase también Qt Quick Ejemplos - Manejadores de punteros.

status : enumeration [read-only]

Esta propiedad contiene el estado de carga de la imagen. Puede ser uno de los siguientes

Utilice este estado para proporcionar una actualización o responder al cambio de estado de alguna manera. Por ejemplo, podría

• Activar un cambio de estado:

  State { name: 'loaded'; when: image.status == Image.Ready }

• Implementar un gestor de señales onStatusChanged:

  Image {
      id: image
      onStatusChanged: if (image.status == Image.Ready) console.log('Loaded')
  }

• Vincular al valor de estado:

  Text { text: image.status == Image.Ready ? 'Loaded' : 'Not loaded' }

Véase también progress.