Image QML Type

Affiche une image. Plus d'informations...

• Liste de tous les membres, y compris les membres hérités

Propriétés

• 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

Description détaillée

Le type Image affiche une image.

La source de l'image est spécifiée sous forme d'URL à l'aide de la propriété source. Les images peuvent être fournies dans n'importe quel format d'image standard pris en charge par Qt Image Formats, y compris les formats bitmap tels que PNG et JPEG, et les formats graphiques vectoriels tels que SVG. Si vous devez afficher des images animées, utilisez AnimatedSprite ou AnimatedImage.

Si les propriétés width et height ne sont pas spécifiées, l'image utilise automatiquement la taille de l'image chargée. Par défaut, la spécification de la largeur et de la hauteur de l'élément entraîne la mise à l'échelle de l'image à cette taille. Ce comportement peut être modifié en définissant la propriété fillMode, ce qui permet d'étirer l'image et de la mettre en mosaïque.

Il est possible de fournir "@nx" high DPI syntax.

Exemple d'utilisation

L'exemple suivant montre l'utilisation la plus simple du type Image.

import QtQuick

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

Fichiers de texture compressés

Lorsque la mise en œuvre de l'API graphique sous-jacente le permet au moment de l'exécution, les images peuvent également être fournies sous forme de fichiers de texture compressés. Le contenu doit être une simple texture 2D au format RGB(A). Les schémas de compression pris en charge sont uniquement limités par le pilote et le GPU sous-jacents. Les formats de fichiers de conteneurs suivants sont pris en charge :

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

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

ou

mirrorVertically: true

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

Ne confondez pas les formats de conteneurs, tels que KTX, et le format des données de texture réelles stockées dans le fichier conteneur. Par exemple, la lecture d'un fichier KTX est prise en charge sur toutes les plateformes, indépendamment du pilote GPU utilisé au moment de l'exécution. Toutefois, cela ne garantit pas que le format de texture compressé, utilisé par les données du fichier, soit pris en charge au moment de l'exécution. Par exemple, si le fichier KTX contient des données compressées au format ETC2 RGBA8 et que l'implémentation de l'API graphique 3D utilisée au moment de l'exécution ne prend pas en charge les textures compressées ETC2, l'élément Image n'affichera rien.

Ne supposez pas que la prise en charge du format compressé est spécifique à une plate-forme. Elle peut également être spécifique au pilote et à l'implémentation de l'API 3D utilisés sur cette plateforme particulière. En pratique, les implémentations de différentes API graphiques 3D (par exemple, Vulkan et OpenGL) sur la même plateforme (par exemple, Windows) du même fournisseur pour le même matériel peuvent offrir un ensemble différent de formats de texture compressée.

Pour les environnements de bureau (Windows, macOS, Linux) uniquement, il est généralement recommandé d'utiliser les formats DXTn/BCn, car ils sont généralement les plus largement pris en charge par les implémentations de Direct 3D, Vulkan, OpenGL et Metal sur ces plates-formes. En revanche, lorsque l'on vise des appareils mobiles ou embarqués, les formats ETC2 ou ASTC sont susceptibles d'être un meilleur choix car ce sont généralement les formats pris en charge par les implémentations OpenGL ES sur ce type de matériel.

Une application qui a l'intention de fonctionner sur du matériel de bureau, mobile et embarqué doit planifier et concevoir son utilisation de textures compressées avec soin. Il est très probable qu'un seul format ne suffise pas et que l'application doive donc s'adapter à la plateforme pour utiliser les textures compressées dans un format approprié, ou peut-être ne pas utiliser les textures compressées dans certains cas.

Détection automatique de l'extension de fichier

Si l'URL source indique un fichier ou une ressource locale inexistante, l'élément Image tente de détecter automatiquement l'extension du fichier. Si un fichier existant peut être trouvé en ajoutant à l'URL source l'une des extensions de fichier image prises en charge, ce fichier sera chargé.

La recherche de fichiers tente d'abord de trouver les extensions de fichiers de conteneurs de textures compressées. Si la recherche est infructueuse, elle tente de rechercher les extensions de fichier pour l'URL conventional image file types. Par exemple :

// 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.
}

Cette fonctionnalité facilite le déploiement de différents types de fichiers image sur différentes plateformes cibles. Cela peut s'avérer utile pour ajuster les performances des applications et s'adapter à différents matériels graphiques.

Cette fonctionnalité a été introduite dans Qt 5.11.

Performances

Par défaut, les images disponibles localement sont chargées immédiatement et l'interface utilisateur est bloquée jusqu'à ce que le chargement soit terminé. Si une grande image doit être chargée, il peut être préférable de charger l'image dans un thread de faible priorité, en activant la propriété asynchronous.

Si l'image est obtenue à partir d'un réseau plutôt que d'une ressource locale, elle est automatiquement chargée de manière asynchrone et les propriétés progress et status sont mises à jour en conséquence.

Les images sont mises en cache et partagées en interne, de sorte que si plusieurs éléments Image ont le même source, une seule copie de l'image sera chargée.

Remarque: les images sont souvent les plus grandes consommatrices de mémoire dans les interfaces utilisateur QML. Il est recommandé de limiter la taille des images qui ne font pas partie de l'interface utilisateur au moyen de la propriété sourceSize. Ceci est particulièrement important pour le contenu qui est chargé à partir de sources externes ou fourni par l'utilisateur.

Voir également Qt Quick Exemples - Éléments d'image, QQuickImageProvider, et QImageReader::setAutoDetectImageFormat().

Documentation sur les propriétés

asynchronous : bool

Spécifie que les images du système de fichiers local doivent être chargées de manière asynchrone dans un thread séparé. La valeur par défaut est false, ce qui entraîne le blocage du thread de l'interface utilisateur pendant le chargement de l'image. La valeur true de asynchronous est utile lorsque le maintien d'une interface utilisateur réactive est plus souhaitable que la visibilité immédiate des images.

Notez que cette propriété n'est valable que pour les images lues à partir du système de fichiers local. Les images chargées via une ressource réseau (par exemple HTTP) sont toujours chargées de manière asynchrone.

autoTransform : bool

Cette propriété indique si l'image doit automatiquement appliquer des métadonnées de transformation d'image telles que l'orientation EXIF.

Par défaut, cette propriété est définie sur false.

cache : bool

Indique si l'image doit être mise en cache. La valeur par défaut est true. La valeur false de cache est utile pour les images de grande taille, afin de s'assurer qu'elles ne sont pas mises en cache au détriment des petites images des éléments d'interface utilisateur.

currentFrame est le cadre actuellement visible. La valeur par défaut est 0. Vous pouvez lui donner une valeur comprise entre 0 et frameCount - 1 pour afficher un cadre différent, si l'image contient plusieurs cadres.

frameCount est le nombre d'images dans l'image. La plupart des images n'ont qu'un seul cadre.

fillMode : enumeration

Cette propriété permet de définir ce qui se passe lorsque l'image source a une taille différente de celle de l'élément.

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"
}

Notez que clip est false par défaut, ce qui signifie que l'élément peut être peint en dehors de son rectangle de délimitation même si le mode de remplissage est défini sur PreserveAspectCrop.

Voir également Qt Quick Exemples - Éléments d'image.

Définit l'alignement horizontal et vertical de l'image. Par défaut, l'image est centrée.

Les valeurs valides pour horizontalAlignment sont Image.AlignLeft, Image.AlignRight et Image.AlignHCenter. Les valeurs valides pour verticalAlignment sont Image.AlignTop, Image.AlignBottom et Image.AlignVCenter.

mipmap : bool

Cette propriété indique si l'image utilise le filtrage mipmap lorsqu'elle est mise à l'échelle ou transformée.

Le filtrage mipmap offre une meilleure qualité visuelle lors de la mise à l'échelle que le filtrage lisse, mais il peut avoir un coût en termes de performances (à la fois lors de l'initialisation de l'image et lors du rendu).

Par défaut, cette propriété est définie sur false.

Voir aussi smooth.

mirror : bool

Cette propriété indique si l'image doit être inversée horizontalement (affichage d'une image miroir).

La valeur par défaut est false.

mirrorVertically : bool [since 6.2]

Cette propriété indique si l'image doit être inversée verticalement (affichage d'une image miroir).

La valeur par défaut est false.

Cette propriété a été introduite dans Qt 6.2.

Ces propriétés indiquent la taille de l'image qui est réellement peinte. Dans la plupart des cas, elle est identique à celle de width et height, mais lorsque vous utilisez Image.PreserveAspectFit ou Image.PreserveAspectCrop, paintedWidth ou paintedHeight peuvent être plus petites ou plus grandes que width et height de l'élément Image.

progress : real [read-only]

Cette propriété indique la progression du chargement de l'image, de 0.0 (rien n'est chargé) à 1.0 (terminé).

Voir aussi status.

retainWhileLoading : bool [since 6.8]

Cette propriété définit le comportement lorsque la propriété source est modifiée et que le chargement se fait de manière asynchrone. C'est le cas lorsque la propriété asynchronous est définie sur true, ou si l'image ne se trouve pas sur le système de fichiers local.

Si retainWhileLoading est false (valeur par défaut), l'ancienne image est immédiatement supprimée et le composant est effacé pendant le chargement de la nouvelle image. Si la valeur est true, l'ancienne image est conservée et reste visible jusqu'à ce que la nouvelle soit prête.

L'activation de cette propriété permet d'éviter le scintillement dans les cas où le chargement de la nouvelle image prend beaucoup de temps. Elle a pour prix une utilisation supplémentaire de la mémoire pour la double mise en mémoire tampon pendant le chargement de la nouvelle image.

Cette propriété a été introduite dans Qt 6.8.

smooth : bool

Cette propriété indique si l'image est filtrée de manière lisse lorsqu'elle est mise à l'échelle ou transformée. Le filtrage lisse donne une meilleure qualité visuelle, mais il peut être plus lent sur certains matériels. Si l'image est affichée à sa taille naturelle, cette propriété n'a aucun effet sur l'aspect visuel ou les performances.

Par défaut, cette propriété est définie sur true.

Voir aussi mipmap.

source : url

Image peut gérer n'importe quel format d'image pris en charge par Qt, chargé à partir de n'importe quel schéma d'URL pris en charge par Qt.

L'URL peut être absolue ou relative à l'URL du composant.

Voir aussi QQuickImageProvider, Compressed Texture Files, et Automatic Detection of File Extension.

sourceClipRect : rect

Cette propriété, si elle est définie, contient la région rectangulaire de l'image source à charger.

La propriété sourceClipRect fonctionne avec la propriété sourceSize pour conserver les ressources du système lorsque seule une partie de l'image doit être chargée.

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

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

Dans l'exemple ci-dessus, nous commençons par mettre à l'échelle le graphique SVG à 1024x1024, puis nous découpons une région d'intérêt de 512x512 pixels à partir d'un emplacement situé à 100 pixels des bords supérieur et gauche. Ainsi, sourceSize détermine l'échelle, mais l'image de sortie réelle est de 512x512 pixels.

Certains formats d'image peuvent économiser le temps de l'unité centrale en ne rendant que la région spécifiée. D'autres devront d'abord charger l'ensemble de l'image, puis la découper dans la région spécifiée.

Cette propriété peut être supprimée pour recharger l'ensemble de l'image en réglant sourceClipRect sur undefined.

sourceSize : size

Cette propriété contient la largeur et la hauteur mises à l'échelle de l'image plein cadre.

Contrairement aux propriétés width et height, qui mettent à l'échelle la peinture de l'image, cette propriété définit le nombre maximal de pixels stockés pour l'image chargée afin que les grandes images n'utilisent pas plus de mémoire que nécessaire. Par exemple, cette propriété garantit que l'image en mémoire ne dépasse pas 1024 x 1024 pixels, quelles que soient les valeurs width et height de l'image :

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

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

Si la taille réelle de l'image est supérieure à la sourceSize, l'image est réduite. Si une seule dimension de la taille est supérieure à 0, l'autre dimension est définie proportionnellement afin de préserver le rapport hauteur/largeur de l'image source. (Le site fillMode est indépendant de cela).

Si sourceSize.width et sourceSize.height sont tous deux définis, l'image sera réduite pour tenir dans la taille spécifiée (sauf si PreserveAspectCrop ou PreserveAspectFit sont utilisés, auquel cas elle sera mise à l'échelle pour correspondre à la taille optimale pour le recadrage/l'ajustement), en conservant le rapport hauteur/largeur de l'image. La taille réelle de l'image après mise à l'échelle est disponible via Item::implicitWidth et Item::implicitHeight.

Si la source est une image intrinsèquement extensible (par exemple SVG), cette propriété détermine la taille de l'image chargée indépendamment de la taille intrinsèque. Évitez de modifier cette propriété de manière dynamique ; le rendu d'un SVG est lent par rapport à celui d'une image.

Si la source est une image non redimensionnable (par exemple JPEG), l'image chargée n'aura pas une taille supérieure à celle spécifiée par cette propriété. Pour certains formats (actuellement seulement JPEG), l'image entière ne sera jamais chargée en mémoire.

Si la propriété sourceClipRect est également définie, sourceSize détermine l'échelle, mais l'image sera découpée à la taille du rectangle de découpage.

La propriété sourceSize peut être ramenée à la taille naturelle de l'image en définissant la propriété sourceSize sur undefined.

Voir également Qt Quick Exemples - Manipulateurs de pointeurs.

status : enumeration [read-only]

Cette propriété indique l'état de chargement de l'image. Il peut s'agir de l'un des éléments suivants

Utilisez ce statut pour fournir une mise à jour ou répondre au changement de statut d'une manière ou d'une autre. Par exemple, vous pouvez

• Déclencher un changement d'état :

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

• implémenter un gestionnaire de signal onStatusChanged:

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

• se lier à la valeur de l'état :

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

Voir aussi progress.