Canvas QML Type

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

• Liste aller Mitglieder, einschließlich geerbter Mitglieder
• Ausgeschiedene Mitglieder

Eigenschaften

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

Signale

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

Methoden

• void cancelRequestAnimationFrame(int handle)
• object 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)

Detaillierte Beschreibung

Das Element Canvas ermöglicht das Zeichnen von geraden und gekrümmten Linien, einfachen und komplexen Formen, Diagrammen und referenzierten Grafiken. Es kann auch Text, Farben, Schatten, Farbverläufe und Muster hinzufügen und Pixeloperationen auf niedriger Ebene durchführen. Die Canvas-Ausgabe kann als Bilddatei gespeichert oder zu einer URL serialisiert werden.

Die Darstellung auf dem Canvas erfolgt über ein Context2D Objekt, in der Regel als Ergebnis des paint Signals.

Um einen Zeichenbereich im Canvas-Element zu definieren, setzen Sie die Eigenschaften width und height. Der folgende Code erstellt beispielsweise ein Canvas-Element, das eine Zeichenfläche mit einer Höhe von 100 Pixeln und einer Breite von 200 Pixeln hat:

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 Target

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

Das Renderziel Canvas.Image ist ein QImage Objekt. Dieses Rendering-Ziel unterstützt das Rendering in einem Hintergrund-Thread, so dass komplexe oder lang andauernde Malvorgänge ausgeführt werden können, ohne die Benutzeroberfläche zu blockieren. Dies ist das einzige Rendering-Ziel, das von allen Qt Quick Backends unterstützt wird.

Das Standard-Rendering-Ziel ist Canvas.Image und das Standard renderStrategy ist Canvas.Immediate.

Pixel-Operationen

Alle HTML5 2D-Kontext-Pixeloperationen werden unterstützt. Um eine verbesserte Leistung beim Lesen/Schreiben von Pixeln zu gewährleisten, sollte das Rendering-Ziel Canvas.Image gewählt werden.

Tipps für die Portierung bestehender HTML5-Canvas-Anwendungen

Obwohl das Canvas-Element eine HTML5-ähnliche API bereitstellt, müssen HTML5-Canvas-Anwendungen für die Ausführung im Canvas-Element angepasst werden:

• Ersetzen Sie alle DOM-API-Aufrufe durch QML-Eigenschaftsbindungen oder Canvas-Elementmethoden.
• Ersetzen Sie alle HTML-Ereignishandler durch das Element MouseArea.
• Ersetzen Sie die Funktionsaufrufe setInterval/setTimeout durch das Element Timer oder die Verwendung von requestAnimationFrame().
• Platzieren Sie den Malcode in den onPaint -Handler und lösen Sie das Malen durch den Aufruf der Methoden markDirty() oder requestPaint() aus.
• Um Bilder zu zeichnen, laden Sie sie durch den Aufruf der Methode loadImage() des Canvas und fordern Sie sie dann im onImageLoaded Handler zum Malen an.

Ab Qt 5.4 ist der Canvas ein texture provider und kann direkt in ShaderEffects und anderen Klassen verwendet werden, die Texturanbieter nutzen.

Siehe auch Context2D, QQuickPaintedItem, und Qt Quick Beispiele - Pointer Handlers.

Dokumentation der Eigenschaften

available : bool [read-only]

Zeigt an, ob Canvas einen Zeichnungskontext für die Bearbeitung bereitstellen kann.

canvasSize : size

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

Standardmäßig entspricht die Leinwandgröße der Größe des aktuellen Canvas-Elements.

Durch die Einstellung 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-Rendering-Engine gezeichnet.

Siehe auch tileSize und canvasWindow.

context : object [read-only]

Enthält den aktiven Zeichenkontext.

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

contextType : string

Der Typ des zu verwendenden Zeichnungskontexts.

Diese Eigenschaft wird auf den Namen des aktiven Kontexttyps gesetzt.

Wenn sie explizit gesetzt wird, versucht die Leinwand, einen Kontext des genannten Typs zu erstellen, sobald sie verfügbar ist.

Der Name des Typs ist derselbe, der im Aufruf getContext() verwendet wird; für den 2D-Canvas lautet der Wert "2d".

Siehe auch getContext() und available.

renderStrategy : enumeration

Enthält die aktuelle Canvas-Rendering-Strategie.

Dieser Hinweis wird zusammen mit renderTarget an den Grafikkontext übergeben, um die Rendering-Methode zu bestimmen. Es kann sein, dass eine RenderStrategie, renderTarget oder eine Kombination von einem Grafikkontext nicht unterstützt wird. In diesem Fall wählt der Kontext die entsprechenden Optionen und Canvas signalisiert die Änderung der Eigenschaften.

Konfigurations- oder Laufzeittests können dazu führen, dass der QML-Szenengraph im GUI-Thread gerendert wird. Die Auswahl von Canvas.Cooperative garantiert nicht, dass das Rendering 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 übergeben, um die Renderingmethode zu bestimmen. Es kann sein, dass renderStrategy, renderTarget oder eine Kombination davon von einem Grafikkontext nicht unterstützt wird. In diesem Fall wählt der Kontext die entsprechenden Optionen und Canvas signalisiert die Änderung der Eigenschaften.

Das Standard-Rendering-Ziel ist Canvas.Image.

Signal-Dokumentation

imageLoaded()

Dieses Signal wird ausgegeben, wenn ein Bild geladen wurde.

Siehe auch loadImage().

paint(rect region)

Dieses Signal wird ausgegeben, wenn die Seite region gerendert werden muss. Wenn ein Kontext aktiv ist, kann er über die Eigenschaft context referenziert werden.

Dieses Signal kann durch markDirty(), requestPaint() oder durch Änderung des aktuellen Canvas-Fensters ausgelöst werden.

painted()

Dieses Signal wird ausgegeben, nachdem alle Context-Painting-Befehle ausgeführt wurden und das Canvas gerendert worden ist.

Dokumentation der Methode

void cancelRequestAnimationFrame(int handle)

Diese Funktion bricht den von handle referenzierten Animationsrückruf ab.

object getContext(string contextId, ... args)

Gibt einen Zeichnungskontext zurück, oder null, wenn kein Kontext verfügbar ist.

Der Parameter contextId benennt den gewünschten Kontext. Das Canvas-Element gibt einen Kontext zurück, der den erforderlichen Zeichenmodus implementiert. Nach dem ersten Aufruf von getContext gibt jeder weitere Aufruf von getContext mit der gleichen contextId das gleiche Kontextobjekt zurück. Alle zusätzlichen Argumente (args) werden derzeit ignoriert.

Wenn der Kontexttyp nicht unterstützt wird oder der Canvas zuvor aufgefordert wurde, einen anderen und inkompatiblen Kontexttyp bereitzustellen, wird null zurückgegeben.

Canvas unterstützt nur einen 2d-Kontext.

bool isImageError(url image)

Gibt true zurück, wenn image nicht geladen werden konnte, andernfalls false.

Siehe auch loadImage().

bool isImageLoaded(url image)

Gibt true zurück, wenn die image erfolgreich geladen und einsatzbereit ist.

Siehe auch loadImage().

bool isImageLoading(url image)

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

Siehe auch loadImage().

void loadImage(url image, size sourceSize = undefined)

Lädt das angegebene image asynchron.

Sobald das Bild fertig ist, wird das Signal imageLoaded() ausgegeben. Das geladene Bild kann mit der Methode unloadImage() wieder entladen werden.

Wenn sourceSize angegeben ist, wird das Bild beim Laden auf diese Größe skaliert. Dies ist nützlich für das Laden von skalierbaren (Vektor-)Bildern (z.B. SVGs) in der vorgesehenen Anzeigegröße. 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 schmutzig, so dass der Canvas-Renderer ihn neu zeichnet, wenn dieser Bereich sichtbar ist. Dadurch wird das Signal paint ausgelöst.

Siehe auch paint und requestPaint().

int requestAnimationFrame(callback)

Diese Funktion sieht vor, dass callback aufgerufen wird, bevor die Szene Qt Quick zusammengesetzt wird.

void requestPaint()

Der gesamte sichtbare Bereich soll neu gezeichnet werden.

Siehe auch markDirty().

bool save(string filename, size imageSize = undefined)

Speichert den aktuellen Leinwandinhalt in einer Bilddatei filename. Das gespeicherte Bildformat wird automatisch durch das Suffix von filename bestimmt. Gibt bei Erfolg true zurück. Wenn imageSize angegeben ist, hat das resultierende Bild diese Größe und ein devicePixelRatio von 1.0. Andernfalls wird das 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.

Der Standardwert mimeType ist "image/png".

Siehe auch save().

void unloadImage(url image)

Entlädt das image.

Sobald ein Bild entladen ist, kann es vom Canvas-Kontext nicht mehr gezeichnet werden, bis es erneut geladen wird.

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