Back to Qt.io
Contact Us Blog Download Qt
Sur cette page

QCanvasGradient Class

QCanvasGradient est la classe de base de tous les pinceaux dégradés d'QCanvasPainter. En savoir plus...

En-tête : #include <QCanvasGradient>
CMake : find_package(Qt6 REQUIRED COMPONENTS CanvasPainter)
target_link_libraries(mytarget PRIVATE Qt6::CanvasPainter)
Depuis : Qt 6.11
Hérité par :

QCanvasBoxGradient, QCanvasConicalGradient, QCanvasLinearGradient, et QCanvasRadialGradient

Fonctions publiques

QCanvasGradient()
(since 6.12) void addColorStop(qreal position, QColor color)
QColor endColor() const
void setColorAt(qreal position, QColor color)
void setEndColor(QColor color)
(since 6.12) void setImage(const QCanvasImage &image, int index = 0)
void setStartColor(QColor color)
void setStops(const QCanvasGradientStops &stops)
QColor startColor() const
QCanvasGradientStops stops() const
QCanvasBrush::BrushType type() const
operator QCanvasBrush() const &
operator QVariant() const

Fonctions protégées

QCanvasGradient(const QCanvasGradient &)
QCanvasGradient(QCanvasGradient &&)
~QCanvasGradient()
QCanvasGradient &operator=(QCanvasGradient &&)
QCanvasGradient &operator=(const QCanvasGradient &)
QCanvasGradientStops
bool operator!=(const QCanvasGradient &lhs, const QCanvasGradient &rhs)
QDataStream &operator<<(QDataStream &stream, const QCanvasGradient &gradient)
QDataStream &operator<<(QDataStream &stream, const QCanvasGradientStop &stop)
bool operator==(const QCanvasGradient &lhs, const QCanvasGradient &rhs)
QDataStream &operator>>(QDataStream &stream, QCanvasGradient &gradient)
QDataStream &operator>>(QDataStream &stream, QCanvasGradientStop &stop)

Description détaillée

QCanvasGradient est la classe de base de tous les pinceaux dégradés d'QCanvasPainter. Il existe actuellement quatre types de dégradés : QCanvasLinearGradient, QCanvasRadialGradient, QCanvasConicalGradient et QCanvasBoxGradient.

Si aucun arrêt n’est spécifié avec setStartColor, setEndColor, setColorAt ou setStops, le dégradé est rendu en noir transparent (0,0,0,0). Si un seul arrêt est spécifié, le dégradé est rempli de cette couleur.

QCanvasPainter utilise deux approches différentes pour dessiner les dégradés.

  • Avec un maximum de 2 arrêts, les couleurs sont transmises au shader sous la forme de 2 uniformes de type vec4. Cela rend l’animation des dégradés à 2 arrêts très performante, sans étape supplémentaire intermédiaire.
  • Avec plus de deux arrêts, les couleurs sont transmises au shader sous la forme d’une texture unidimensionnelle. Par défaut, la taille de la texture est de 1 × 256 pixels, ce qui est optimisé pour la qualité et les performances. Les textures sont mises en cache ; ainsi, lorsque les arrêts ou les couleurs du dégradé ne changent pas, la texture précédente peut être réutilisée même si d’autres propriétés du dégradé (telles que la position, l’angle, etc.) changent. Bien que l’animation des dégradés à plusieurs arrêts soit rapide, elle entraîne des chargements de textures ; il convient donc de se demander si cela en vaut la peine.

Il existe quelques variables d’environnement permettant de contrôler l’utilisation des textures de dégradés :

  • QCPAINTER_DISABLE_TEXTURE_USAGE_TRACKING - Par défaut, l’utilisation des textures de dégradé est suivie et maintenue en dessous du nombre maximal autorisé. Définissez cette variable d’environnement pour désactiver le suivi et conserver toutes les textures de dégradé en mémoire.
  • QCPAINTER_MAX_TEXTURES – Par défaut, le nombre maximal de textures est de 1024. Définissez cette variable d’environnement sur le nombre maximal de textures souhaité. Les textures de dégradés temporaires actuellement inutilisées sont automatiquement supprimées lorsque le nombre maximal est atteint.

    Remarque : cela n’a aucun effet lorsque le suivi de l’utilisation des textures a été désactivé.

Documentation des fonctions membres

[delete] QCanvasGradient::QCanvasGradient()

Construit par défaut une instance de ` QCanvasGradient`. Cette fonction est supprimée.

[constexpr noexcept protected default] QCanvasGradient::QCanvasGradient(const QCanvasGradient &)

Crée une instance de ` QCanvasGradient` par copie.

[constexpr noexcept protected default] QCanvasGradient::QCanvasGradient(QCanvasGradient &&)

Crée par construction une instance de ` QCanvasGradient`.

[constexpr noexcept protected default] QCanvasGradient::~QCanvasGradient()

Supprime l'instance de ` QCanvasGradient`.

[since 6.12] void QCanvasGradient::addColorStop(qreal position, QColor color)

Crée un point d'arrêt à l'position indiquée, avec l'color spécifiée. La position indiquée doit être comprise entre 0 et 1.

Cette méthode est fournie pour des raisons de compatibilité avec l'CanvasGradient HTML. Elle est équivalente à setColorAt().

Cette fonction a été introduite dans Qt 6.12.

Voir également setStops() et stops().

QColor QCanvasGradient::endColor() const

Renvoie la couleur finale du dégradé ou la couleur correspondant à la position la plus éloignée. Si aucune étape n'a été définie, renvoie du noir transparent (0, 0, 0, 0).

Voir aussi setEndColor().

void QCanvasGradient::setColorAt(qreal position, QColor color)

Crée un point d'arrêt à l'position indiquée avec l'color spécifiée. La position fournie doit être comprise entre 0 et 1.

Voir également setStops() et stops().

void QCanvasGradient::setEndColor(QColor color)

Définit la couleur de fin du dégradé sur color. Cela revient à appeler la fonction setColorAt() avec la position 1.

Voir également endColor().

[since 6.12] void QCanvasGradient::setImage(const QCanvasImage &image, int index = 0)

Utilise la fonction ` image ` comme source de dégradé à la coordonnée y ` index`. Il s'agit d'une alternative à la définition des arrêts de dégradé à l'aide, par exemple, de ` setStops()` ou ` setColorAt()`. La largeur par défaut prévue de l’image est de 256 pixels, mais elle peut être ajustée en définissant la variable QCPAINTER_GRADIENT_SIZE. Le paramètre index est facultatif et n’est pas nécessaire lorsque la hauteur de l’image est de 1 pixel. La valeur maximale de l’index doit être égale à la hauteur de l’image moins 1.

Raisons possibles d’utiliser cette méthode plutôt que de définir des arrêts :

  • Création légèrement plus rapide, car les étapes ne doivent pas être analysées. De plus, plusieurs dégradés peuvent être inclus dans une seule image à l'aide de ` index`.
  • Possibilité d’utiliser directement un dégradé issu d’un design ou d’une image, au lieu de le convertir en un ensemble de points d’arrêt.
  • Possibilité d’utiliser des dégradés non linéaires, comme par exemple une courbe gaussienne.

Remarque : si les arrêts et l’image ont tous deux été définis, ce sont les arrêts qui seront utilisés.

Voici un exemple simple d’utilisation d’une image en dégradé 256x1:

Fine bande horizontale passant du bleu au rouge puis à l'orange
Carré présentant un dégradé radial allant du blanc au centre vers le rouge et le violet sur les bords
static QImage image(":/gradient1.png");
QCanvasImage gradImage = p->addImage(image);
QRectF rect(0, 0, 200, 200);
QCanvasRadialGradient rg(rect.center(), 20, 150);
rg.setImage(gradImage);
p->setFillStyle(rg);
p->fillRect(rect);

Cette fonction a été introduite dans Qt 6.12.

Voir également setStops().

void QCanvasGradient::setStartColor(QColor color)

Définit la couleur de départ du dégradé sur color. Cela revient à appeler la fonction setColorAt() avec la position 0.

Voir également startColor().

void QCanvasGradient::setStops(const QCanvasGradientStops &stops)

Remplace l'ensemble actuel de points d'arrêt par l'stops.

Les règles relatives à la liste des arrêts sont les suivantes :

  • La liste doit contenir au moins 2 points d'arrêt.
  • Les positions des points d’arrêt doivent être comprises entre 0 et 1, et doivent être triées de la plus basse à la plus élevée.
  • La première position doit être à 0,0 et la dernière à 1,0.

Voir également setColorAt() et stops().

QColor QCanvasGradient::startColor() const

Renvoie la couleur de départ du dégradé ou la couleur correspondant à la position la plus petite. Si aucune étape n'a été définie, renvoie du noir transparent (0, 0, 0, 0).

Voir également setStartColor().

QCanvasGradientStops QCanvasGradient::stops() const

Renvoie les points d'arrêt de ce dégradé.

Voir également setStops() et setColorAt().

QCanvasBrush::BrushType QCanvasGradient::type() const

Renvoie le type du dégradé.

QCanvasGradient::operator QCanvasBrush() const &

Renvoie le dégradé sous la forme d'un objet ` QCanvasBrush`.

Cette fonction surcharge l'opérateur QCanvasGradient::operator QCanvasBrush() &&.

QCanvasGradient::operator QVariant() const

Renvoie le gradient sous la forme d’un objet de type « QVariant ».

[constexpr noexcept protected default] QCanvasGradient &QCanvasGradient::operator=(QCanvasGradient &&)

Cette opération attribue l'other à cette instance QCanvasGradient.

[constexpr noexcept protected default] QCanvasGradient &QCanvasGradient::operator=(const QCanvasGradient &)

Copie et attribue other à cette instance de QCanvasGradient.

Éléments non membres associés

QCanvasGradientStops

Définition de type pour QList<QCanvasGradientStop>.

[noexcept] bool operator!=(const QCanvasGradient &lhs, const QCanvasGradient &rhs)

Renvoie ` true ` si le gradient ` lhs ` est différent de ` rhs` ; ` false ` dans le cas contraire.

Voir également operator==().

QDataStream &operator<<(QDataStream &stream, const QCanvasGradient &gradient)

Écrit l'gradient on fournie dans l'stream on indiquée et renvoie une référence à l'stream on.

Voir également Sérialisation des types de données Qt.

QDataStream &operator<<(QDataStream &stream, const QCanvasGradientStop &stop)

Écrit l'stop de gradient dans l'stream indiquée et renvoie une référence à l'stream.

Voir également Sérialisation des types de données Qt.

[noexcept] bool operator==(const QCanvasGradient &lhs, const QCanvasGradient &rhs)

Renvoie « true » si le gradient lhs est égal à rhs; « false » dans le cas contraire.

Voir aussi operator!=().

QDataStream &operator>>(QDataStream &stream, QCanvasGradient &gradient)

Lit l'gradient on fournie à partir de l'stream on indiquée et renvoie une référence à l'stream on.

Voir également Sérialisation des types de données Qt.

QDataStream &operator>>(QDataStream &stream, QCanvasGradientStop &stop)

Lit une stop de gradient à partir de l'stream fournie et renvoie une référence à l'stream.

Voir également Sérialisation des types de données Qt.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.