Canvas QML Type

Stellt ein 2D-Canvas-Element bereit, das das Zeichnen über JavaScript ermöglicht. Mehr...

• Liste aller Mitglieder, einschließlich geerbter Mitglieder
• Veraltete Elemente

Eigenschaften

• available : bool
• canvasSize : size
• context : object
• contextType : string
• renderStrategy : enumeration
• renderTarget : enumeration

Signale

• imageLoaded()
• paint(rect region)
• painted()

Methoden

• void cancelRequestAnimationFrame(int handle)
• Context2D getContext(string contextId, ... args)
• bool isImageError(url image)
• bool isImageLoaded(url image)
• bool isImageLoading(url image)
• void loadImage(url image, size sourceSize)
• void markDirty(rect area)
• int requestAnimationFrame(callback)
• void requestPaint()
• bool save(string filename, size imageSize)
• string toDataURL(string mimeType)
• void unloadImage(url image)

Ausführliche Beschreibung

Das Canvas-Element ermöglicht das Zeichnen von geraden und gekrümmten Linien, einfachen und komplexen Formen, Diagrammen sowie eingebundenen Grafiken. Außerdem können Text, Farben, Schatten, Farbverläufe und Muster hinzugefügt sowie Pixeloperationen auf niedriger Ebene durchgeführt werden. Die Canvas-Ausgabe kann als Bilddatei gespeichert oder an eine URL serialisiert werden.

Die Darstellung auf dem „Canvas“ erfolgt über ein „ Context2D “-Objekt, in der Regel als Reaktion auf das Signal „ paint “.

Um einen Zeichenbereich im „Canvas“-Element zu definieren, legen Sie die Eigenschaften „ width “ und „ height “ fest. Der folgende Code erstellt beispielsweise ein „Canvas“-Element mit einem Zeichenbereich von 100 Pixeln Höhe und 200 Pixeln Breite:

import QtQuick 2.0
Canvas {
    id: mycanvas
    width: 100
    height: 200
    onPaint: {
        var ctx = getContext("2d");
        ctx.fillStyle = Qt.rgba(1, 0, 0, 1);
        ctx.fillRect(0, 0, width, height);
    }
}

Derzeit unterstützt das „Canvas“-Element nur den zweidimensionalen Rendering-Kontext.

Threaded Rendering und Render-Ziel

In Qt 6.0 unterstützt das „Canvas“-Element ein Renderziel: „ Canvas.Image “.

Das Renderziel „ Canvas.Image “ ist ein „ QImage “-Objekt. Dieses Renderziel unterstützt das Rendern im Hintergrund-Thread, wodurch komplexe oder lang andauernde Zeichenvorgänge ausgeführt werden können, ohne die Benutzeroberfläche zu blockieren. Dies ist das einzige Renderziel, das von allen „ Qt Quick “-Backends unterstützt wird.

Das Standard-Renderziel ist „Canvas.Image“ und die Standard- renderStrategy -Einstellung ist „Canvas.Immediate“.

Pixeloperationen

Alle Pixeloperationen des HTML5-2D-Kontexts werden unterstützt. Um eine verbesserte Leistung beim Lesen und Schreiben von Pixeln zu gewährleisten, sollte das Renderziel „ Canvas.Image “ gewählt werden.

Tipps zur Portierung bestehender HTML5-Canvas-Anwendungen

Obwohl das „Canvas“-Element eine HTML5-ähnliche API bereitstellt, müssen HTML5-Canvas-Anwendungen angepasst werden, um im „Canvas“-Element ausgeführt werden zu können:

• Ersetzen Sie alle DOM-API-Aufrufe durch QML-Eigenschaftsbindungen oder Methoden des Canvas-Elements.
• Ersetzen Sie alle HTML-Ereignisbehandler durch das „ MouseArea “-Element.
• Ersetzen Sie setInterval-/setTimeout-Funktionsaufrufe durch das „ Timer “-Element oder die Verwendung von „ requestAnimationFrame()“.
• Platzieren Sie den Zeichen-Code im „ onPaint “-Handler und lösen Sie das Zeichnen durch Aufruf der Methoden „ markDirty()“ oder „ requestPaint()“ aus.
• Um Bilder zu zeichnen, laden Sie diese durch Aufruf der Methode ` loadImage()` des Canvas und fordern Sie anschließend im ` onImageLoaded `-Handler das Zeichnen an.

Ab Qt 5.4 ist die „Canvas“-Klasse ein „ texture provider “ und kann direkt in „ ShaderEffects “ sowie anderen Klassen verwendet werden, die Textur-Provider nutzen.

Siehe auch Context2D, QQuickPaintedItem und Qt Quick – Beispiele: Zeiger-Handler.

Dokumentation zu Eigenschaften

available : bool [read-only]

Gibt an, wann Canvas einen Zeichenkontext bereitstellen kann, in dem gearbeitet werden kann.

canvasSize : size

Enthält die logische Leinwandgröße, auf der der Kontext zeichnet.

Standardmäßig entspricht die Leinwandgröße der Größe des aktuellen Leinwandelements.

Durch die Festlegung von `canvasSize`, `tileSize` und `canvasWindow` kann das Canvas-Element als große virtuelle Leinwand mit vielen separat gerenderten Kachelrechtecken fungieren. Nur die Kacheln innerhalb des aktuellen Canvas-Fensters werden von der Canvas-Render-Engine gezeichnet.

Siehe auch tileSize und canvasWindow.

context : object [read-only]

Enthält den aktiven Zeichenkontext.

Wenn die Zeichenfläche bereit ist und ein erfolgreicher Aufruf von ` getContext()` erfolgt ist oder die Eigenschaft ` contextType ` mit einem unterstützten Kontexttyp gesetzt wurde, enthält diese Eigenschaft den aktuellen Zeichenkontext, andernfalls `null`.

contextType : string

Der zu verwendende Zeichnungskontext.

Diese Eigenschaft wird auf den Namen des aktiven Kontexttyps gesetzt.

Wird dieser Wert explizit festgelegt, versucht die Leinwand, einen Kontext des genannten Typs zu erstellen, sobald dieser verfügbar ist.

Der Typname entspricht dem im Aufruf von ` getContext()` verwendeten Namen; für die 2D-Canvas lautet der Wert „2d“.

Siehe auch getContext() und available.

renderStrategy : enumeration

Enthält die aktuelle Rendering-Strategie für die Leinwand.

Dieser Hinweis wird zusammen mit „ renderTarget “ an den Grafikkontext übergeben, um die Art der Darstellung zu bestimmen. „renderStrategy“, „ renderTarget “ oder eine Kombination daraus werden möglicherweise von einem Grafikkontext nicht unterstützt; in diesem Fall wählt der Kontext geeignete Optionen aus und „Canvas“ signalisiert die Änderung an den Eigenschaften.

Konfigurations- oder Laufzeittests können dazu führen, dass der QML-Szenenbaum im GUI-Thread gerendert wird. Die Auswahl von „ Canvas.Cooperative “ garantiert nicht, dass das Rendern in einem vom GUI-Thread getrennten Thread erfolgt.

Der Standardwert ist „ Canvas.Immediate “.

Siehe auch „ renderTarget “.

renderTarget : enumeration

Enthält das aktuelle Renderziel der Leinwand.

Dieser Hinweis wird zusammen mit „ renderStrategy “ an den Grafikkontext übermittelt, um die Rendering-Methode zu bestimmen. „ renderStrategy “, „renderTarget“ oder eine Kombination daraus werden möglicherweise von einem Grafikkontext nicht unterstützt; in diesem Fall wählt der Kontext geeignete Optionen aus und „Canvas“ signalisiert die Änderung an den Eigenschaften.

Das Standard-Renderziel ist „ Canvas.Image “.

Signal-Dokumentation

imageLoaded()

Dieses Signal wird ausgelöst, wenn ein Bild geladen wurde.

Siehe auch loadImage().

paint(rect region)

Dieses Signal wird ausgelöst, wenn die „ region “ gerendert werden muss. Ist ein Kontext aktiv, kann über die Eigenschaft „context“ darauf verwiesen werden.

Dieses Signal kann durch „ markDirty()“, „ requestPaint()“ oder durch das Wechseln des aktuellen Canvas-Fensters ausgelöst werden.

painted()

Dieses Signal wird ausgelöst, nachdem alle Befehle zum Zeichnen des Kontexts ausgeführt und die Leinwand gerendert wurde.

Methodendokumentation

void cancelRequestAnimationFrame(int handle)

Diese Funktion hebt den Animations-Callback auf, auf den „ handle “ verweist.

Context2D getContext(string contextId, ... args)

Gibt einen Zeichenkontext zurück oder „ null “, falls kein Kontext verfügbar ist.

Der Parameter „ contextId “ bezeichnet den gewünschten Kontext. Das Canvas-Element gibt einen Kontext zurück, der den gewünschten Zeichenmodus implementiert. Nach dem ersten Aufruf von „getContext“ gibt jeder nachfolgende Aufruf von „getContext“ mit derselben „contextId“ dasselbe Kontext-Objekt zurück. Alle zusätzlichen Argumente (args) werden derzeit ignoriert.

Wenn der Kontexttyp nicht unterstützt wird oder zuvor bereits ein anderer, inkompatibler Kontexttyp von der Canvas-Instanz angefordert wurde, wird „ null “ zurückgegeben.

Canvas unterstützt nur einen 2D-Kontext.

bool isImageError(url image)

Gibt „ true “ zurück, wenn das Laden von „ image “ fehlgeschlagen ist, andernfalls „ false “.

Siehe auch loadImage().

bool isImageLoaded(url image)

Gibt „ true “ zurück, wenn „ image “ erfolgreich geladen wurde und einsatzbereit ist.

Siehe auch loadImage().

bool isImageLoading(url image)

Gibt „ true “ zurück, wenn die Seite „ image “ gerade geladen wird.

Siehe auch loadImage().

void loadImage(url image, size sourceSize = undefined)

Lädt das angegebene image asynchron.

Sobald das Bild bereit ist, wird das Signal ` imageLoaded()` ausgelöst. Das geladene Bild kann mit der Methode ` unloadImage()` entladen werden.

Wenn sourceSize angegeben wird, wird das Bild beim Laden auf diese Größe skaliert. Dies ist nützlich, um skalierbare (Vektor-)Bilder (z. B. SVGs) in ihrer vorgesehenen Anzeigegröße zu laden. Dieser Parameter wurde in Qt 6.7 eingeführt.

Siehe auch „ unloadImage()“, „ imageLoaded()“, „ isImageLoaded()“, „ Context2D::createImageData()“ und „ Context2D::drawImage()“.

void markDirty(rect area)

Markiert den angegebenen Bereich „ area “ als „dirty“, sodass der Canvas-Renderer diesen Bereich neu zeichnet, sobald er sichtbar ist. Dadurch wird das Signal „ paint “ ausgelöst.

Siehe auch ` paint ` und ` requestPaint()`.

int requestAnimationFrame(callback)

Diese Funktion sorgt dafür, dass die Funktion „ callback “ vor dem Erstellen der Szene „ Qt Quick “ aufgerufen wird.

void requestPaint()

Fordern Sie an, dass der gesamte sichtbare Bereich neu gezeichnet wird.

Siehe auch markDirty().

bool save(string filename, size imageSize = undefined)

Speichert den aktuellen Inhalt der Leinwand in einer Bilddatei „ filename “. Das Format des gespeicherten Bildes wird automatisch anhand der Dateiendung von „ filename “ festgelegt. Bei Erfolg wird „ true “ zurückgegeben. Wenn „ imageSize “ angegeben wird, hat das resultierende Bild diese Größe und ein „devicePixelRatio“ von „ 1.0 “. Andernfalls wird die Funktion „ devicePixelRatio()“ des Fensters, in dem die Leinwand angezeigt wird, auf das gespeicherte Bild angewendet.

Siehe auch „ canvasWindow“ , „ canvasSize “ und „ toDataURL()“.

string toDataURL(string mimeType)

Gibt eine Daten-URL für das Bild im Canvas zurück.

Die Standard- mimeType ist „image/png“.

Siehe auch ` save()`.

void unloadImage(url image)

Lädt das Bild „ image “ aus.

Sobald ein Bild entladen wurde, kann es vom Canvas-Kontext nicht mehr gezeichnet werden, es sei denn, es wird erneut geladen.

Siehe auch „ loadImage()“, „ imageLoaded()“, „ isImageLoaded()“, „ Context2D::createImageData()“ und „ Context2D::drawImage “.