Canvas QML Type

Fournit un élément « canvas » 2D permettant de dessiner via JavaScript. En savoir plus...

• Liste de tous les membres, y compris les membres hérités
• Membres obsolètes

Propriétés

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

Signaux

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

Méthodes

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

Description détaillée

L'élément Canvas permet de tracer des lignes droites et courbes, des formes simples et complexes, des graphiques et d'intégrer des images graphiques référencées. Il permet également d'ajouter du texte, des couleurs, des ombres, des dégradés et des motifs, ainsi que d'effectuer des opérations de bas niveau sur les pixels. Le résultat généré par Canvas peut être enregistré sous forme de fichier image ou sérialisé vers une URL.

Le rendu sur le « Canvas » s’effectue à l’aide d’un objet « Context2D », généralement à la suite du signal « paint ».

Pour définir une zone de dessin dans l’élément Canvas, configurez les propriétés ` width ` et ` height `. Par exemple, le code suivant crée un élément Canvas dont la zone de dessin mesure 100 pixels de hauteur et 200 pixels de largeur :

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);
    }
}

Actuellement, l’élément Canvas ne prend en charge que le contexte de rendu bidimensionnel.

Rendu multithread et cible de rendu

Dans Qt 6.0, l’élément Canvas prend en charge une cible de rendu : Canvas.Image.

La cible de rendu « Canvas.Image » est un objet de type « QImage ». Cette cible de rendu prend en charge le rendu en thread d’arrière-plan, ce qui permet d’exécuter des opérations de dessin complexes ou longues sans bloquer l’interface utilisateur. Il s’agit de la seule cible de rendu prise en charge par tous les backends d’ Qt Quick.

La cible de rendu par défaut est Canvas.Image et l’ renderStrategy par défaut est Canvas.Immediate.

Opérations sur les pixels

Toutes les opérations sur les pixels du contexte 2D HTML5 sont prises en charge. Afin de garantir de meilleures performances de lecture/écriture des pixels, il est recommandé de choisir la cible de rendu « Canvas.Image ».

Conseils pour le portage d’applications HTML5 Canvas existantes

Bien que l’élément Canvas fournisse une API similaire à celle de HTML5, les applications HTML5 Canvas doivent être modifiées pour fonctionner dans l’élément Canvas :

• Remplacez tous les appels à l’API DOM par des liaisons de propriétés QML ou des méthodes de l’élément Canvas.
• Remplacez tous les gestionnaires d’événements HTML par l’élément « MouseArea ».
• Remplacez les appels aux fonctions setInterval/setTimeout par l’élément « Timer » ou par l’utilisation de requestAnimationFrame().
• Placez le code de dessin dans le gestionnaire « onPaint » et déclenchez le dessin en appelant les méthodes « markDirty() » ou « requestPaint() ».
• Pour dessiner des images, chargez-les en appelant la méthode loadImage() du Canvas, puis demandez leur affichage dans le gestionnaire onImageLoaded.

À partir de Qt 5.4, le Canvas est un texture provider et peut être utilisé directement dans ShaderEffects et d’autres classes qui utilisent des fournisseurs de textures.

Voir également Context2D, QQuickPaintedItem et Qt Quick Exemples - Gestionnaires de pointeurs.

Documentation sur les propriétés

available : bool [read-only]

Indique quand Canvas est en mesure de fournir un contexte de dessin sur lequel effectuer des opérations.

canvasSize : size

Contient la taille logique du canevas sur lequel le contexte effectue le dessin.

Par défaut, la taille du canevas correspond à celle de l'élément de canevas actuel.

En définissant les paramètres canvasSize, tileSize et canvasWindow, l’élément Canvas peut fonctionner comme un grand canevas virtuel composé de nombreux rectangles (tuiles) rendus séparément. Seules les tuiles situées dans la fenêtre actuelle du canevas sont dessinées par le moteur de rendu de Canvas.

Voir également tileSize et canvasWindow.

context : object [read-only]

Contient le contexte de dessin actif.

Si le canevas est prêt et qu'un appel à ` getContext()` a abouti, ou si la propriété ` contextType ` a été définie avec un type de contexte pris en charge, cette propriété contiendra le contexte de dessin actuel ; sinon, elle sera nulle.

contextType : string

Le type de contexte de dessin à utiliser.

Cette propriété est définie sur le nom du type de contexte actif.

Si elle est définie explicitement, le canevas tentera de créer un contexte du type indiqué dès qu'il sera disponible.

Le nom du type est le même que celui utilisé dans l'appel getContext(), pour le canevas 2D, la valeur sera « 2d ».

Voir également getContext() et available.

renderStrategy : enumeration

Contient la stratégie de rendu actuelle du canevas.

Cette indication est fournie avec ` renderTarget ` au contexte graphique afin de déterminer la méthode de rendu. Il se peut qu’une stratégie de rendu (`renderStrategy`), une stratégie de composition (` renderTarget `) ou une combinaison des deux ne soit pas prise en charge par un contexte graphique ; dans ce cas, le contexte choisira les options appropriées et Canvas signalera la modification aux propriétés.

Des tests de configuration ou d’exécution peuvent entraîner le rendu du graphe de scène QML dans le thread de l’interface graphique. Le fait de sélectionner ` Canvas.Cooperative` ne garantit pas que le rendu s’effectuera sur un thread distinct du thread de l’interface graphique.

La valeur par défaut est Canvas.Immediate.

Voir également ` renderTarget`.

renderTarget : enumeration

Contient la cible de rendu actuelle du canevas.

Cette indication est fournie avec l'option ` renderStrategy ` au contexte graphique afin de déterminer la méthode de rendu. Il se peut qu'un contexte graphique ne prenne pas en charge l'option ` renderStrategy`, `renderTarget` ou une combinaison de celles-ci ; dans ce cas, le contexte choisira les options appropriées et `Canvas` signalera la modification aux propriétés.

La cible de rendu par défaut est « Canvas.Image ».

Documentation sur les signaux

imageLoaded()

Ce signal est émis lorsqu'une image a été chargée.

Voir également loadImage().

paint(rect region)

Ce signal est émis lorsque l'region doit être affiché. Si un contexte est actif, il peut être référencé via la propriété « context ».

Ce signal peut être déclenché par les méthodes ` markDirty()`, ` requestPaint()` ou par la modification de la fenêtre de canevas actuelle.

painted()

Ce signal est émis une fois que toutes les commandes de dessin contextuelles ont été exécutées et que le Canvas a été affiché.

Documentation de la méthode

void cancelRequestAnimationFrame(int handle)

Cette fonction annulera la fonction de rappel d'animation référencée par handle.

Context2D getContext(string contextId, ... args)

Renvoie un contexte de dessin, ou ` null ` si aucun contexte n'est disponible.

Le paramètre ` contextId ` désigne le contexte requis. L'élément `Canvas` renverra un contexte implémentant le mode de dessin requis. Après le premier appel à `getContext`, tout appel ultérieur à `getContext` avec le même `contextId` renverra le même objet de contexte. Tout argument supplémentaire (args) est actuellement ignoré.

Si le type de contexte n’est pas pris en charge ou si le canvas a déjà été sollicité pour fournir un type de contexte différent et incompatible, la valeur « null » sera renvoyée.

Canvas ne prend en charge qu’un contexte 2D.

bool isImageError(url image)

Renvoie « true » si le chargement de l'image a échoué, « false » dans le cas contraire.

Voir également loadImage().

bool isImageLoaded(url image)

Renvoie ` true ` si l'image ` a été chargé avec succès et est prêt à être utilisé.

Voir aussi loadImage().

bool isImageLoading(url image)

Renvoie ` true ` si le fichier ` image ` est en cours de chargement.

Voir aussi loadImage().

void loadImage(url image, size sourceSize = undefined)

Charge l'image spécifiée de manière asynchrone.

Une fois l'image prête, le signal ` imageLoaded()` est émis. L'image chargée peut être déchargée à l'aide de la méthode ` unloadImage()`.

Si sourceSize est spécifié, l’image sera redimensionnée à cette taille lors du chargement. Cela est utile pour charger des images redimensionnables (vectorielles) (par exemple, des SVG) à leur taille d’affichage prévue. Ce paramètre a été introduit dans Qt 6.7.

Voir également : unloadImage(), imageLoaded(), isImageLoaded(), Context2D::createImageData() et Context2D::drawImage().

void markDirty(rect area)

Marque l'area on donnée comme « sale », de sorte que lorsque cette zone est visible, le moteur de rendu du canevas la redessine. Cela déclenche le signal « paint ».

Voir également paint et requestPaint().

int requestAnimationFrame(callback)

Cette fonction planifie l'appel de la fonction ` callback ` avant la composition de la scène ` Qt Quick `.

void requestPaint()

Demander le rafraîchissement de toute la zone visible.

Voir également markDirty().

bool save(string filename, size imageSize = undefined)

Enregistre le contenu actuel du canevas dans un fichier image filename. Le format de l'image enregistrée est automatiquement déterminé par le suffixe de filename. Renvoie true en cas de succès. Si imageSize est spécifié, l'image résultante aura cette taille et un devicePixelRatio de 1.0. Sinon, la méthode devicePixelRatio() de la fenêtre dans laquelle le canevas est affiché est appliquée à l'image enregistrée.

Voir également canvasWindow, canvasSize et toDataURL().

string toDataURL(string mimeType)

Renvoie une URL de données correspondant à l'image affichée dans le canvas.

L'mimeType par défaut est « image/png ».

Voir aussi save().

void unloadImage(url image)

Décharge l'image.

Une fois qu’une image est déchargée, elle ne peut plus être dessinée par le contexte du canevas, à moins d’être rechargée.

Voir également loadImage(), imageLoaded(), isImageLoaded(), Context2D::createImageData() et Context2D::drawImage.