Image QML Type

Zeigt ein Bild an. Mehr...

• Liste aller Mitglieder, einschließlich geerbter Mitglieder

Eigenschaften

• 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

Ausführliche Beschreibung

Der Typ „Image“ zeigt ein Bild an.

Die Quelle des Bildes wird über die Eigenschaft „ source “ als URL angegeben. Bilder können in jedem der von Qt unterstützten Standardbildformate bereitgestellt werden, darunter Bitmap-Formate wie PNG und JPEG sowie Vektorgrafikformate wie SVG. Wenn Sie animierte Bilder anzeigen möchten, verwenden Sie „ AnimatedSprite “ oder „ AnimatedImage “.

Wenn die Eigenschaften ` width ` und ` height ` nicht angegeben sind, verwendet das `Image` automatisch die Größe des geladenen Bildes. Standardmäßig führt die Angabe von Breite und Höhe des Elements dazu, dass das Bild auf diese Größe skaliert wird. Dieses Verhalten lässt sich durch Setzen der Eigenschaft ` fillMode ` ändern, wodurch das Bild stattdessen gestreckt und gekachelt wird.

Es ist möglich, „ "@nx" high DPI syntax “ anzugeben.

Anwendungsbeispiel

Das folgende Beispiel zeigt die einfachste Verwendung des Typs „Image“.

import QtQuick

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

Komprimierte Texturdateien

Sofern dies von der Implementierung der zugrunde liegenden Grafik-API zur Laufzeit unterstützt wird, können Bilder auch in komprimierten Texturdateien bereitgestellt werden. Der Inhalt muss eine einfache 2D-Textur im RGB(A)-Format sein. Die unterstützten Komprimierungsverfahren sind nur durch den zugrunde liegenden Treiber und die GPU begrenzt. Die folgenden Container-Dateiformate werden unterstützt:

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

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

oder

mirrorVertically: true

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

Verwechseln Sie nicht Containerformate wie „ KTX “ mit dem Format der eigentlichen Texturdaten, die in der Container-Datei gespeichert sind. Beispielsweise wird das Einlesen einer „ KTX “-Datei auf allen Plattformen unterstützt, unabhängig davon, welcher GPU-Treiber zur Laufzeit verwendet wird. Dies garantiert jedoch nicht, dass das komprimierte Texturformat, das von den Daten in der Datei verwendet wird, zur Laufzeit unterstützt wird. Wenn die KTX-Datei beispielsweise komprimierte Daten im Format ETC2 RGBA8 enthält und die zur Laufzeit verwendete 3D-Grafik-API-Implementierung keine komprimierten Texturen im Format ETC2 unterstützt, wird das Image-Element nichts anzeigen.

Gehen Sie nicht davon aus, dass die Unterstützung komprimierter Formate plattformspezifisch ist. Sie kann auch spezifisch für den Treiber und die auf dieser bestimmten Plattform verwendete 3D-API-Implementierung sein. In der Praxis können Implementierungen verschiedener 3D-Grafik-APIs (z. B. Vulkan und OpenGL) auf derselben Plattform (z. B. Windows) desselben Anbieters für dieselbe Hardware unterschiedliche komprimierte Texturformate unterstützen.

Wenn ausschließlich Desktop-Umgebungen (Windows, macOS, Linux) angesprochen werden, lautet eine allgemeine Empfehlung, die Verwendung der Formate „ DXTn “ bzw. „BCn “ in Betracht zu ziehen, da diese in der Regel die breiteste Unterstützung unter den Implementierungen von Direct 3D, Vulkan, OpenGL und Metal auf diesen Plattformen genießen. Im Gegensatz dazu sind bei der Ausrichtung auf mobile oder eingebettete Geräte die Formate ETC2 oder ASTC wahrscheinlich die bessere Wahl, da diese in der Regel von den OpenGL ES-Implementierungen auf solcher Hardware unterstützt werden.

Eine Anwendung, die auf Desktop-, Mobil- und eingebetteter Hardware laufen soll, sollte den Einsatz komprimierter Texturen sorgfältig planen und gestalten. Es ist sehr wahrscheinlich, dass die Verwendung eines einzigen Formats nicht ausreichen wird, und daher muss die Anwendung wahrscheinlich je nach Plattform verzweigen, um komprimierte Texturen in einem dort geeigneten Format zu verwenden oder in manchen Fällen möglicherweise ganz auf die Verwendung komprimierter Texturen zu verzichten.

Automatische Erkennung der Dateiendung

Wenn die URL „ source “ auf eine nicht vorhandene lokale Datei oder Ressource verweist, versucht das „Image“-Element, die Dateiendung automatisch zu erkennen. Wenn eine vorhandene Datei gefunden werden kann, indem eine der unterstützten Bilddateiendungen an die URL „ source “ angehängt wird, wird diese Datei geladen.

Bei der Dateisuche wird zunächst nach Dateiendungen für komprimierte Textur-Container gesucht. Ist die Suche erfolglos, wird versucht, mit den Dateiendungen für „ conventional image file types “ zu suchen. Beispiel:

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

Diese Funktionalität erleichtert die Bereitstellung verschiedener Bilddateitypen auf unterschiedlichen Zielplattformen. Dies kann nützlich sein, um die Anwendungsleistung zu optimieren und an unterschiedliche Grafikhardware anzupassen.

Diese Funktionalität wurde in Qt 5.11 eingeführt.

Leistung

Standardmäßig werden lokal verfügbare Bilder sofort geladen, und die Benutzeroberfläche wird bis zum Abschluss des Ladevorgangs gesperrt. Wenn ein großes Bild geladen werden soll, kann es vorteilhaft sein, das Bild in einem Thread mit niedriger Priorität zu laden, indem die Eigenschaft ` asynchronous ` aktiviert wird.

Wird das Bild nicht aus einer lokalen Ressource, sondern über ein Netzwerk abgerufen, wird es automatisch asynchron geladen, und die Eigenschaften „ progress “ und „ status “ werden entsprechend aktualisiert.

Bilder werden zwischengespeichert und intern gemeinsam genutzt. Wenn also mehrere „Image“-Elemente denselben „ source “ haben, wird nur eine Kopie des Bildes geladen.

Hinweis: Bilder sind in QML-Benutzeroberflächen oft der größte Speicherverbraucher. Es wird empfohlen, die Größe von Bildern, die nicht Teil der Benutzeroberfläche sind, über die Eigenschaft ` sourceSize ` zu begrenzen. Dies ist besonders wichtig für Inhalte, die aus externen Quellen geladen oder vom Benutzer bereitgestellt werden.

Siehe auch „Qt Quick -Beispiele – Bildelemente“, QQuickImageProvider und QImageReader::setAutoDetectImageFormat().

Dokumentation zur Eigenschaft

asynchronous : bool

Legt fest, dass Bilder aus dem lokalen Dateisystem asynchron in einem separaten Thread geladen werden sollen. Der Standardwert ist „false“, wodurch der Benutzeroberflächen-Thread während des Ladens des Bildes blockiert wird. Die Einstellung „ asynchronous “ auf „true“ ist sinnvoll, wenn eine reaktionsschnelle Benutzeroberfläche wichtiger ist als die sofortige Anzeige der Bilder.

Beachten Sie, dass diese Eigenschaft nur für Bilder gilt, die aus dem lokalen Dateisystem gelesen werden. Bilder, die über eine Netzwerkressource (z. B. HTTP) geladen werden, werden immer asynchron geladen.

autoTransform : bool

Diese Eigenschaft legt fest, ob das Bild automatisch Metadaten zur Bildtransformation wie beispielsweise die EXIF-Ausrichtung anwenden soll.

Standardmäßig ist diese Eigenschaft auf „false“ gesetzt.

cache : bool

Legt fest, ob das Bild zwischengespeichert werden soll. Der Standardwert ist „true“. Die Einstellung „ cache “ auf „false“ ist bei großen Bildern sinnvoll, um sicherzustellen, dass diese nicht auf Kosten kleiner Bilder von „UI-Elementen“ zwischengespeichert werden.

currentFrame ist der derzeit sichtbare Frame. Der Standardwert ist 0. Sie können einen Wert zwischen 0 und frameCount - 1 festlegen, um einen anderen Frame anzuzeigen, sofern das Bild mehrere Frames enthält.

frameCount ist die Anzahl der Frames im Bild. Die meisten Bilder haben nur einen Frame.

fillMode : enumeration

Legen Sie diese Eigenschaft fest, um zu definieren, was geschieht, wenn das Quellbild eine andere Größe als das Element hat.

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

Beachten Sie, dass „ clip “ standardmäßig auf „ false “ gesetzt ist, was bedeutet, dass das Element möglicherweise über sein Begrenzungsrechteck hinaus gezeichnet wird, selbst wenn „fillMode“ auf „ PreserveAspectCrop “ gesetzt ist.

Siehe auch „Qt Quick “-Beispiele – Bildelemente.

Legt die horizontale und vertikale Ausrichtung des Bildes fest. Standardmäßig wird das Bild zentriert ausgerichtet.

Die gültigen Werte für „ horizontalAlignment “ sind „ Image.AlignLeft “, „ Image.AlignRight “ und „ Image.AlignHCenter “. Die gültigen Werte für „ verticalAlignment “ sind „ Image.AlignTop “, „ Image.AlignBottom “ und „ Image.AlignVCenter “.

mipmap : bool

Diese Eigenschaft gilt unabhängig davon, ob das Bild beim Skalieren oder Transformieren Mipmap-Filterung verwendet.

Die Mipmap-Filterung bietet beim Verkleinern eine bessere Bildqualität als die glatte Skalierung, kann jedoch zu Leistungseinbußen führen (sowohl bei der Initialisierung des Bildes als auch während des Renderings).

Standardmäßig ist diese Eigenschaft auf „false“ gesetzt.

Siehe auch „ smooth “.

mirror : bool

Diese Eigenschaft legt fest, ob das Bild horizontal gespiegelt werden soll (wodurch effektiv ein Spiegelbild angezeigt wird).

Der Standardwert ist „false“.

mirrorVertically : bool [since 6.2]

Diese Eigenschaft legt fest, ob das Bild vertikal gespiegelt werden soll (wodurch effektiv ein Spiegelbild angezeigt wird).

Der Standardwert ist „false“.

Diese Eigenschaft wurde in Qt 6.2 eingeführt.

Diese Eigenschaften geben die Größe des tatsächlich gezeichneten Bildes an. In den meisten Fällen entspricht sie den Werten unter „ width “ und „ height “, doch bei Verwendung von „ Image.PreserveAspectFit “ oder „ Image.PreserveAspectCrop “ können „ paintedWidth “ oder „ paintedHeight “ kleiner oder größer sein als „ width “ und „ height “ des Image-Elements.

progress : real [read-only]

Diese Eigenschaft gibt den Fortschritt beim Laden des Bildes an, von 0,0 (noch nichts geladen) bis 1,0 (fertig).

Siehe auch status.

retainWhileLoading : bool [since 6.8]

Diese Eigenschaft legt das Verhalten fest, wenn die Eigenschaft „ source “ geändert wird und das Laden asynchron erfolgt. Dies ist der Fall, wenn die Eigenschaft „ asynchronous “ auf „ true “ gesetzt ist oder wenn sich das Bild nicht im lokalen Dateisystem befindet.

Wenn „ retainWhileLoading “ auf „ false “ gesetzt ist (Standardeinstellung), wird das alte Bild sofort verworfen und die Komponente geleert, während das neue Bild geladen wird. Bei der Einstellung „ true “ bleibt das alte Bild erhalten und sichtbar, bis das neue Bild bereit ist.

Durch Aktivieren dieser Eigenschaft lässt sich Flackern vermeiden, wenn das Laden des neuen Bildes lange dauert. Dies geht jedoch mit einem zusätzlichen Speicherbedarf für die Doppelpufferung einher, während das neue Bild geladen wird.

Diese Eigenschaft wurde in Qt 6.8 eingeführt.

smooth : bool

Diese Eigenschaft legt fest, ob das Bild beim Skalieren oder Transformieren glatt gefiltert wird. Eine glatte Filterung sorgt für eine bessere Bildqualität, kann jedoch auf manchen Hardwarekomponenten zu einer Verlangsamung führen. Wird das Bild in seiner natürlichen Größe angezeigt, hat diese Eigenschaft keine Auswirkungen auf die Darstellung oder die Leistung.

Standardmäßig ist diese Eigenschaft auf „true“ gesetzt.

Siehe auch „ mipmap “.

source : url

„Image“ kann jedes von Qt unterstützte Bildformat verarbeiten, das über jedes von Qt unterstützte URL-Schema geladen wird.

Die URL kann absolut oder relativ zur URL der Komponente sein.

Siehe auch QQuickImageProvider, Compressed Texture Files und Automatic Detection of File Extension.

sourceClipRect : rect

Diese Eigenschaft enthält, sofern sie festgelegt ist, den rechteckigen Bereich des Quellbildes, der geladen werden soll.

Die Eigenschaft „ sourceClipRect “ arbeitet mit der Eigenschaft „ sourceSize “ zusammen, um Systemressourcen zu schonen, wenn nur ein Teil eines Bildes geladen werden muss.

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

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

Im obigen Beispiel skalieren wir die SVG-Grafik zunächst konzeptionell auf 1024×1024 und schneiden dann einen interessierenden Bereich von 512×512 Pixeln aus, der sich 100 Pixel vom oberen und linken Rand entfernt befindet. Somit bestimmt ` sourceSize ` den Maßstab, das tatsächlich ausgegebene Bild hat jedoch eine Größe von 512×512 Pixel.

Einige Bildformate können CPU-Zeit sparen, indem sie nur den angegebenen Bereich rendern. Andere müssen zunächst das gesamte Bild laden und es dann auf den angegebenen Bereich zuschneiden.

Diese Eigenschaft kann zurückgesetzt werden, um das gesamte Bild neu zu laden, indem „ sourceClipRect “ auf „ undefined “ gesetzt wird.

sourceSize : size

Diese Eigenschaft enthält die skalierte Breite und Höhe des Vollbildes.

Im Gegensatz zu den Eigenschaften „ width “ und „ height “, die die Darstellung des Bildes skalieren, legt diese Eigenschaft die maximale Anzahl der für das geladene Bild gespeicherten Pixel fest, damit große Bilder nicht mehr Speicherplatz als nötig beanspruchen. So wird beispielsweise sichergestellt, dass das Bild im Speicher nicht größer als 1024 × 1024 Pixel ist, unabhängig von den Werten „ width “ und „ height “ des Bildes:

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

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

Ist die tatsächliche Größe des Bildes größer als „sourceSize“, wird das Bild verkleinert. Ist nur eine der beiden Abmessungen auf einen Wert größer als 0 gesetzt, wird die andere Abmessung proportional angepasst, um das Seitenverhältnis des Quellbildes beizubehalten. (Die Eigenschaft „ fillMode “ ist davon unabhängig.)

Sind sowohl „sourceSize.width“ als auch „sourceSize.height“ festgelegt, wird das Bild so verkleinert, dass es in die angegebene Größe passt (es sei denn, „PreserveAspectCrop“ oder „PreserveAspectFit“ werden verwendet; in diesem Fall wird es auf die optimale Größe für das Zuschneiden bzw. Anpassen skaliert), wobei das Seitenverhältnis des Bildes beibehalten wird. Die tatsächliche Größe des Bildes nach der Skalierung ist über „ Item::implicitWidth “ und „ Item::implicitHeight “ abrufbar.

Wenn es sich bei der Quelle um ein von Natur aus skalierbares Bild handelt (z. B. SVG), bestimmt diese Eigenschaft die Größe des geladenen Bildes unabhängig von dessen ursprünglicher Größe. Vermeiden Sie es, diese Eigenschaft dynamisch zu ändern; das Rendern eines SVG-Bildes ist im Vergleich zu einem Bild langsam.

Ist die Quelle ein nicht skalierbares Bild (z. B. JPEG), ist das geladene Bild nicht größer als durch diese Eigenschaft festgelegt. Bei einigen Formaten (derzeit nur JPEG) wird das gesamte Bild niemals tatsächlich in den Arbeitsspeicher geladen.

Wenn zusätzlich die Eigenschaft „ sourceClipRect “ gesetzt ist, bestimmt „ sourceSize “ den Skalierungsfaktor, das Bild wird jedoch auf die Größe des Ausschnittrechtecks beschnitten.

„sourceSize“ kann auf die natürliche Größe des Bildes zurückgesetzt werden, indem „sourceSize“ auf „ undefined “ gesetzt wird.

Siehe auch „Qt Quick -Beispiele – Zeiger-Handler“.

status : enumeration [read-only]

Diese Eigenschaft gibt den Status des Bildladevorgangs an. Mögliche Werte sind:

Verwenden Sie diesen Status, um eine Aktualisierung bereitzustellen oder auf die Statusänderung in irgendeiner Weise zu reagieren. Sie könnten beispielsweise:

• Eine Statusänderung auslösen:

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

• Einen Signal-Handler für „ onStatusChanged “ implementieren:

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

• Eine Bindung an den Statuswert herstellen:

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

Siehe auch „ progress “.