Image QML Type

Affiche une image. En savoir plus…

• 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, y compris les formats bitmap tels que PNG et JPEG, ainsi que les formats graphiques vectoriels tels que SVG. Si vous souhaitez afficher des images animées, utilisez ` AnimatedSprite ` ou ` AnimatedImage`.

Si les propriétés ` width ` et ` height ` ne sont pas spécifiées, l’objet `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 à l’image d’être étirée et mise en mosaïque à la place.

Il est possible de fournir une image de remplissage ( "@nx" high DPI syntax).

Exemple d'utilisation

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

import QtQuick

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

Fichiers de texture compressés

Lorsque l’implémentation de l’API graphique sous-jacente le prend en charge à l’exécution, les images peuvent également être fournies sous forme de fichiers de texture compressés. Le contenu doit être une texture 2D au format RVB(A) simple. Les schémas de compression pris en charge ne sont limités que par le pilote et le GPU sous-jacents. Les formats de fichiers 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

Il ne faut pas confondre les formats de conteneur, tels que ` KTX`, et le format des données de texture proprement dites stockées dans le fichier conteneur. Par exemple, la lecture d’un fichier ` KTX ` est prise en charge sur toutes les plateformes, quel que soit le pilote GPU utilisé au moment de l’exécution. Cependant, cela ne garantit pas que le format de texture compressée, 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 au format ETC2, l’élément Image n’affichera rien.

Ne partez pas du principe que la prise en charge d'un format compressé est spécifique à une plateforme. Elle peut également dépendre du pilote et de 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 une même plateforme (par exemple, Windows) provenant du même fournisseur et destinées au même matériel peuvent proposer un ensemble différent de formats de textures compressées.

Lorsque vous ciblez uniquement des environnements de bureau (Windows, macOS, Linux), il est généralement recommandé d’envisager l’utilisation des formats DXTn/BCn, car ceux-ci bénéficient généralement de la prise en charge la plus large parmi les implémentations de Direct 3D, Vulkan, OpenGL et Metal sur ces plateformes. En revanche, lorsque l’on cible des appareils mobiles ou embarqués, les formats ETC2 ou ASTC constituent probablement un meilleur choix, car ce sont généralement les formats pris en charge par les implémentations d’OpenGL ES sur ce type de matériel.

Une application destinée à fonctionner sur du matériel de bureau, mobile et embarqué doit planifier et concevoir avec soin son utilisation des textures compressées. Il est fort probable qu’un seul format ne suffise pas ; l’application devra donc probablement s’adapter en fonction de la plateforme pour utiliser des textures compressées dans un format adapté à celle-ci, voire renoncer à l’utilisation de 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’une des extensions de fichier image prises en charge à l’URL source, alors ce fichier sera chargé.

La recherche de fichier tente d’abord de trouver les extensions de fichiers conteneurs de textures compressées. Si la recherche échoue, elle tente alors 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 d’images sur différentes plateformes cibles. Cela peut s’avérer utile pour optimiser les performances de l’application 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’à la fin du chargement. Si une image volumineuse doit être chargée, il peut être préférable de la charger dans un thread à faible priorité, en activant la propriété ` asynchronous `.

Si l’image provient 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 ; ainsi, si plusieurs éléments Image ont la même propriété ` source`, une seule copie de l’image sera chargée.

Remarque: les images sont souvent les éléments qui consomment le plus 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 via la propriété ` sourceSize `. Ceci est particulièrement important pour le contenu chargé à partir de sources externes ou fourni par l’utilisateur.

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

Documentation sur la propriété

asynchronous : bool

Spécifie que les images présentes sur le système de fichiers local doivent être chargées de manière asynchrone dans un thread distinct. 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. Il est utile de définir « asynchronous » sur « true » lorsque le maintien d'une interface utilisateur réactive est plus important que l'affichage immédiat 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é détermine si l'image doit automatiquement appliquer les 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 ». Il est utile de définir « cache » sur « false » lorsque l'on traite des images volumineuses, afin de s'assurer qu'elles ne soient pas mises en cache au détriment des petites images des « éléments d'interface utilisateur ».

currentFrame correspond à l'image actuellement affichée. La valeur par défaut est 0. Vous pouvez définir cette valeur sur un nombre compris entre 0 et frameCount - 1 pour afficher une autre image, si celle-ci en contient plusieurs.

frameCount correspond au nombre d'images composant l'image. La plupart des images ne comportent qu'une seule image.

fillMode : enumeration

Définissez cette propriété pour déterminer 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 la propriété « clip » est définie par défaut sur « false », ce qui signifie que l'élément peut s'afficher en dehors de son rectangle de délimitation même si le « fillMode » est défini sur « PreserveAspectCrop ».

Voir également Exemples d’Qt Quick - É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é s'applique que l'image utilise ou non le filtrage par mipmap lors de sa mise à l'échelle ou de sa transformation.

Le filtrage mipmap offre une meilleure qualité visuelle lors de la réduction d'échelle par rapport au lissage, mais il peut entraîner une perte de performances (tant lors de l'initialisation de l'image que pendant le rendu).

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

Voir également smooth.

mirror : bool

Cette propriété détermine si l'image doit être inversée horizontalement (ce qui revient à afficher une image en miroir).

La valeur par défaut est « false ».

mirrorVertically : bool [since 6.2]

Cette propriété détermine si l'image doit être inversée verticalement (ce qui revient à afficher une image en 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 réellement affichée. Dans la plupart des cas, elle correspond à width et height, mais lorsque l'on utilise un Image.PreserveAspectFit ou un Image.PreserveAspectCrop, paintedWidth ou paintedHeight peuvent être inférieures ou supérieures à 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'a été chargé) à 1,0 (chargement terminé).

Voir également 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 s'effectue 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 défini sur false (valeur par défaut), l’ancienne image est immédiatement supprimée et le composant est vidé pendant le chargement de la nouvelle image. S’il est défini sur 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 lorsque le chargement de la nouvelle image prend beaucoup de temps. Cela s’accompagne toutefois d’une consommation de mémoire supplémentaire due à la mise en mémoire tampon double pendant le chargement de la nouvelle image.

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

smooth : bool

Cette propriété détermine si l'image fait l'objet d'un filtrage lissé lorsqu'elle est redimensionnée ou transformée. Le filtrage lissé offre une meilleure qualité visuelle, mais peut ralentir le système sur certains matériels. Si l'image est affichée à sa taille d'origine, cette propriété n'a aucun effet sur l'affichage ni sur les performances.

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

Voir également mipmap.

source : url

Image prend en charge tous les formats d'image pris en charge par Qt, chargés à 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 également QQuickImageProvider, Compressed Texture Files et Automatic Detection of File Extension.

sourceClipRect : rect

Cette propriété, si elle est définie, spécifie la zone rectangulaire de l'image source à charger.

La propriété « sourceClipRect » fonctionne conjointement avec la propriété « sourceSize » afin de préserver les ressources système lorsqu'une partie seulement d'une 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 redimensionnons d’abord le graphique SVG à 1 024 × 1 024, puis nous découpons une zone d’intérêt de 512 × 512 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 mesure 512 × 512 pixels.

Certains formats d’image permettent d’économiser du temps de processeur en ne rendant que la zone spécifiée. D’autres devront d’abord charger l’image entière, puis la recadrer à la zone spécifiée.

Cette propriété peut être désactivée pour recharger l’image entière en définissant ` sourceClipRect ` sur ` undefined`.

sourceSize : size

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

Contrairement aux propriétés ` width ` et ` height `, qui redimensionnent le rendu de l’image, cette propriété définit le nombre maximal de pixels stockés pour l’image chargée, afin que les images volumineuses n’utilisent pas plus de mémoire que nécessaire. Par exemple, cela garantit que l’image en mémoire ne dépasse pas 1 024 × 1 024 pixels, quelles que soient les valeurs des propriétés ` width ` et ` height ` de l’objet `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 valeur sourceSize, l’image est réduite. Si une seule des dimensions est définie sur une valeur supérieure à 0, l’autre dimension est ajustée proportionnellement afin de conserver le rapport d’aspect de l’image source. (La propriété « fillMode » est indépendante de ce paramètre.)

Si sourceSize.width et sourceSize.height sont tous deux définis, l’image sera réduite pour s’adapter à la taille spécifiée (à moins que les options PreserveAspectCrop ou PreserveAspectFit ne soient utilisées, auquel cas elle sera redimensionnée pour correspondre à la taille optimale pour le recadrage ou l’ajustement), tout en conservant le rapport d’aspect 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 redimensionnable (par exemple, un fichier SVG), cette propriété détermine la taille de l’image chargée, quelle que soit sa taille intrinsèque. Évitez de modifier cette propriété de manière dynamique ; le rendu d’un fichier SVG est lent par rapport à celui d’une image.

Si la source est une image non redimensionnable (par exemple, un JPEG), l’image chargée ne dépassera pas la taille spécifiée par cette propriété. Pour certains formats (actuellement uniquement le JPEG), l’image entière ne sera jamais réellement chargée en mémoire.

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

La propriété `sourceSize` peut être réinitialisée à la taille naturelle de l’image en définissant `sourceSize` sur ` undefined`.

Voir également Exemples d’Qt Quick - Gestionnaires de pointeurs.

status : enumeration [read-only]

Cette propriété indique l'état de chargement de l'image. Elle peut prendre l'une des valeurs suivantes :

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

• 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')
  }

• Lier la valeur du statut :

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

Voir également progress.