Canvas QML Type

Fournit un élément de canevas 2D permettant de dessiner via JavaScript. Plus d'informations...

• Liste de tous les membres, y compris les membres hérités
• Membres dépréciés

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

Description détaillée

L'élément Canvas permet de dessiner des lignes droites et courbes, des formes simples et complexes, des graphiques et 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, et d'effectuer des opérations de bas niveau sur les pixels. La sortie de Canvas peut être enregistrée sous la forme d'un fichier image ou sérialisée dans une URL.

Le rendu sur le Canvas est effectué à 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, définissez les propriétés width et height. Par exemple, le code suivant crée un élément Canvas avec une zone de dessin d'une hauteur de 100 pixels et d'une largeur de 200 pixels :

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 threadé 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 QImage. Cette cible de rendu prend en charge le rendu en arrière-plan, ce qui permet d'exécuter des peintures complexes ou de longue durée sans bloquer l'interface utilisateur. Il s'agit de la seule cible de rendu prise en charge par tous les backends de Qt Quick.

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

Opérations sur les pixels

Toutes les opérations sur les pixels du contexte HTML5 2D sont prises en charge. Afin d'améliorer les performances de lecture et d'écriture des pixels, il convient 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 de type HTML5, les applications HTML5 Canvas doivent être modifiées pour fonctionner dans l'élément Canvas :

• Remplacer tous les appels à l'API DOM par des liaisons de propriétés QML ou des méthodes d'éléments Canvas.
• Remplacer tous les gestionnaires d'événements HTML par l'élément MouseArea.
• Remplacer les appels aux fonctions setInterval/setTimeout par l'élément Timer ou par l'utilisation de requestAnimationFrame().
• Placez le code de peinture dans le gestionnaire onPaint et déclenchez la peinture en appelant les méthodes markDirty() ou requestPaint().
• Pour dessiner des images, chargez-les en appelant la méthode loadImage() du Canvas, puis demandez à les peindre 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 consomment des fournisseurs de textures.

Voir aussi Context2D, QQuickPaintedItem, et Qt Quick Exemples - Pointer Handlers.

Documentation sur les propriétés

available : bool [read-only]

Indique que Canvas est en mesure de fournir un contexte de dessin sur lequel opérer.

canvasSize : size

Indique la taille logique de la toile sur laquelle le contexte peint.

Par défaut, la taille du canevas est la même que celle de l'élément de canevas actuel.

En définissant les paramètres canvasSize, tileSize et canvasWindow, l'élément Canvas peut agir comme une grande toile virtuelle avec de nombreux rectangles de tuiles rendus séparément. Seules les tuiles situées à l'intérieur de la fenêtre du canevas sont peintes par le moteur de rendu Canvas.

Voir également tileSize et canvasWindow.

context : object [read-only]

Contient le contexte de dessin actif.

Si la toile est prête et qu'un appel à getContext() a été effectué avec succès ou que 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 nommé après être devenu 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

Détient la stratégie de rendu de la toile actuelle.

Cet indice est fourni avec renderTarget au contexte graphique pour déterminer la méthode de rendu. Une stratégie de rendu, renderTarget ou une combinaison peut ne pas être prise en charge par un contexte graphique, auquel cas le contexte choisira les options appropriées et Canvas signalera le changement aux propriétés.

Les tests de configuration ou d'exécution peuvent entraîner le rendu du graphe de scène QML dans le fil d'exécution de l'interface graphique. La sélection de Canvas.Cooperative, ne garantit pas que le rendu se produira dans un thread distinct de celui de l'interface graphique.

La valeur par défaut est Canvas.Immediate.

Voir également renderTarget.

renderTarget : enumeration

Détient la cible de rendu actuelle du canevas.

Cette indication est fournie avec renderStrategy au contexte graphique pour déterminer la méthode de rendu. Il se peut qu'un contexte graphique ne prenne pas en charge renderStrategy, renderTarget ou une combinaison, auquel cas le contexte choisira les options appropriées et Canvas signalera le changement 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 aussi loadImage().

paint(rect region)

Ce signal est émis lorsque le site region doit être rendu. Si un contexte est actif, il peut être référencé à partir de la propriété context.

Ce signal peut être déclenché par markDirty(), requestPaint() ou par un changement de la fenêtre courante du canevas.

painted()

Ce signal est émis après l'exécution de toutes les commandes de peinture contextuelle et le rendu du canevas.

Documentation de la méthode

void cancelRequestAnimationFrame(int handle)

Cette fonction annule le rappel d'animation référencé par handle.

object 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 renvoie un contexte qui met en œuvre 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 canevas a déjà été sollicité pour fournir un type de contexte différent et incompatible, null sera renvoyé.

Canvas ne prend en charge que le contexte 2d.

bool isImageError(url image)

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

Voir aussi loadImage().

bool isImageLoaded(url image)

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

Voir aussi loadImage().

bool isImageLoading(url image)

Renvoie true si le site image est en cours de chargement.

Voir aussi loadImage().

void loadImage(url image, size sourceSize = undefined)

Charge l'image image de manière asynchrone.

Lorsque l'image est 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 mise à l'échelle à cette taille pendant le chargement. Ceci est utile pour charger des images vectorielles (par exemple SVG) à la taille d'affichage prévue. Ce paramètre a été introduit dans Qt 6.7.

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

void markDirty(rect area)

Marque la zone area donnée comme sale, de sorte que lorsque cette zone est visible, le moteur de rendu de la toile la redessine. Cela déclenchera le signal paint.

Voir aussi paint et requestPaint().

int requestAnimationFrame(callback)

Cette fonction planifie l'invocation de callback avant de composer la scène Qt Quick.

void requestPaint()

Demander que toute la région visible soit redessinée.

Voir également markDirty().

bool save(string filename, size imageSize = undefined)

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

Voir également canvasWindow, canvasSize, et toDataURL().

string toDataURL(string mimeType)

Renvoie une URL de données pour l'image dans le canevas.

L'adresse mimeType par défaut est "image/png".

Voir aussi save().

void unloadImage(url image)

Décharge l'image image.

Une fois qu'une image est déchargée, elle ne peut plus être peinte par le contexte de la toile à moins qu'elle ne soit à nouveau chargée.

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