Sur cette page

QPalette Class

La classe QPalette contient des groupes de couleurs pour chaque état du widget. Plus d'informations...

En-tête : #include <QPalette>
CMake : find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake : QT += gui

Types publics

enum ColorGroup { Disabled, Active, Inactive, Normal }
enum ColorRole { Window, WindowText, Base, AlternateBase, ToolTipBase, …, NoRole }

Fonctions publiques

QPalette()
QPalette(Qt::GlobalColor button)
QPalette(const QColor &button)
QPalette(const QColor &button, const QColor &window)
QPalette(const QBrush &windowText, const QBrush &button, const QBrush &light, const QBrush &dark, const QBrush &mid, const QBrush &text, const QBrush &bright_text, const QBrush &base, const QBrush &window)
QPalette(const QPalette &p)
QPalette(QPalette &&other)
~QPalette()
(since 6.6) const QBrush &accent() const
const QBrush &alternateBase() const
const QBrush &base() const
const QBrush &brightText() const
const QBrush &brush(QPalette::ColorGroup group, QPalette::ColorRole role) const
const QBrush &brush(QPalette::ColorRole role) const
const QBrush &button() const
const QBrush &buttonText() const
qint64 cacheKey() const
const QColor &color(QPalette::ColorGroup group, QPalette::ColorRole role) const
const QColor &color(QPalette::ColorRole role) const
QPalette::ColorGroup currentColorGroup() const
const QBrush &dark() const
const QBrush &highlight() const
const QBrush &highlightedText() const
bool isBrushSet(QPalette::ColorGroup cg, QPalette::ColorRole cr) const
bool isCopyOf(const QPalette &p) const
bool isEqual(QPalette::ColorGroup cg1, QPalette::ColorGroup cg2) const
const QBrush &light() const
const QBrush &link() const
const QBrush &linkVisited() const
const QBrush &mid() const
const QBrush &midlight() const
const QBrush &placeholderText() const
QPalette resolve(const QPalette &other) const
void setBrush(QPalette::ColorRole role, const QBrush &brush)
void setBrush(QPalette::ColorGroup group, QPalette::ColorRole role, const QBrush &brush)
void setColor(QPalette::ColorGroup group, QPalette::ColorRole role, const QColor &color)
void setColor(QPalette::ColorRole role, const QColor &color)
void setColorGroup(QPalette::ColorGroup cg, const QBrush &windowText, const QBrush &button, const QBrush &light, const QBrush &dark, const QBrush &mid, const QBrush &text, const QBrush &bright_text, const QBrush &base, const QBrush &window)
void setCurrentColorGroup(QPalette::ColorGroup cg)
const QBrush &shadow() const
void swap(QPalette &other)
const QBrush &text() const
const QBrush &toolTipBase() const
const QBrush &toolTipText() const
const QBrush &window() const
const QBrush &windowText() const
operator QVariant() const
bool operator!=(const QPalette &p) const
QPalette &operator=(QPalette &&other)
QPalette &operator=(const QPalette &p)
(since 6.6) bool operator==(const QPalette &p) const
QDataStream &operator<<(QDataStream &s, const QPalette &p)
QDataStream &operator>>(QDataStream &s, QPalette &p)

Description détaillée

Une palette se compose de trois groupes de couleurs : Active, Disabled et Inactive. Tous les widgets de Qt Widgets contiennent une palette et utilisent leur palette pour se dessiner. Cela rend l'interface utilisateur facilement configurable et plus facile à maintenir cohérente.

Si vous créez un nouveau widget, nous vous recommandons vivement d'utiliser les couleurs de la palette plutôt que de coder en dur des couleurs spécifiques.

Les groupes de couleurs :

  • Le groupe Actif est utilisé pour la fenêtre qui a le focus clavier.
  • Le groupe Inactif est utilisé pour les autres fenêtres.
  • Le groupe Désactivé est utilisé pour les widgets (pas les fenêtres) qui sont désactivés pour une raison quelconque.

Les fenêtres actives et inactives peuvent contenir des widgets désactivés. (Les widgets désactivés sont souvent qualifiés d'inaccessibles ou de grisés).

Dans la plupart des styles, les fenêtres actives et inactives se ressemblent.

Les couleurs et les brosses peuvent être définies pour des rôles particuliers dans n'importe quel groupe de couleurs d'une palette à l'aide de setColor() et setBrush(). Un groupe de couleurs contient un ensemble de couleurs utilisées par les widgets pour se dessiner. Nous recommandons que les widgets utilisent les rôles des groupes de couleurs de la palette tels que "foreground" et "base" plutôt que des couleurs littérales telles que "rouge" ou "turquoise". Les rôles de couleur sont énumérés et définis dans la documentation de ColorRole.

Nous vous recommandons vivement d'utiliser la palette par défaut du style actuel (renvoyée par QGuiApplication::palette()) et de la modifier si nécessaire. Ceci est fait par les widgets de Qt Widgets lorsqu'ils sont dessinés.

Pour modifier un groupe de couleurs, vous appelez les fonctions setColor() et setBrush(), selon que vous souhaitez une couleur pure ou un motif pixmap.

Il existe également des fonctions d'acquisition color() et brush() correspondantes, ainsi qu'une fonction de commodité couramment utilisée pour obtenir le ColorRole pour le ColorGroup actuel : window(), windowText(), base(), etc.

Vous pouvez copier une palette à l'aide du constructeur copy et tester si deux palettes sont identiques à l'aide de isCopyOf().

QPalette est optimisé par l'utilisation du partage implicite, il est donc très efficace de passer des objets QPalette comme arguments.

Attention : Certains styles n'utilisent pas la palette pour tous les dessins, par exemple s'ils utilisent des moteurs de thèmes natifs. C'est le cas des styles Windows Vista et macOS.

Voir également QApplication::setPalette(), QWidget::setPalette() et QColor.

Documentation sur les types de membres

enum QPalette::ColorGroup

ConstanteValeurDescription de l'activité
QPalette::Disabled1
QPalette::Active0
QPalette::Inactive2
QPalette::NormalActivesynonyme de Actif

enum QPalette::ColorRole

Rôles des couleurs

L'énumération ColorRole définit les différents rôles symboliques des couleurs utilisés dans les interfaces graphiques actuelles.

Les rôles principaux sont les suivants

ConstanteValeurDescription de la couleur
QPalette::Window10Une couleur d'arrière-plan générale.
QPalette::WindowText0Couleur générale de premier plan.
QPalette::Base9Utilisée principalement comme couleur d'arrière-plan pour les widgets de saisie de texte, elle peut également être utilisée pour d'autres tableaux, tels que l'arrière-plan des listes déroulantes des combobox et des poignées des barres d'outils. Il s'agit généralement du blanc ou d'une autre couleur claire.
QPalette::AlternateBase16Utilisée comme couleur d'arrière-plan alternative dans les vues avec des couleurs de ligne alternées (voir QAbstractItemView::setAlternatingRowColors()).
QPalette::ToolTipBase18Utilisée comme couleur d'arrière-plan pour QToolTip et QWhatsThis. Les bulles d'aide utilisent le groupe de couleurs Inactif de QPalette, car les bulles d'aide ne sont pas des fenêtres actives.
QPalette::ToolTipText19Utilisée comme couleur d'avant-plan pour QToolTip et QWhatsThis. Les info-bulles utilisent le groupe de couleurs inactives de QPalette, car les info-bulles ne sont pas des fenêtres actives.
QPalette::PlaceholderText20Utilisée comme couleur d'espacement pour divers widgets de saisie de texte. Cette valeur d'énumération a été introduite dans Qt 5.12
QPalette::Text6La couleur d'avant-plan utilisée avec Base. C'est généralement la même que celle de WindowText, auquel cas elle doit offrir un bon contraste avec Window et Base.
QPalette::Button1La couleur générale de l'arrière-plan du bouton. Cet arrière-plan peut être différent de celui de Window, car certains styles exigent une couleur d'arrière-plan différente pour les boutons.
QPalette::ButtonText8Une couleur d'avant-plan utilisée avec la couleur de Button.
QPalette::BrightText7Une couleur de texte très différente de celle de WindowText et qui contraste bien avec, par exemple, Dark. Elle est généralement utilisée pour le texte qui doit être dessiné là où Text ou WindowText donnerait un mauvais contraste, comme sur les boutons-poussoirs enfoncés. Les couleurs de texte sont généralement utilisées pour le texte, mais il est assez courant d'utiliser les rôles de couleur de texte pour les lignes, les icônes, etc.

Certains rôles de couleur sont utilisés principalement pour les effets de biseau et d'ombre en 3D. Toutes ces couleurs sont normalement dérivées de Window et utilisées en fonction de cette relation. Par exemple, les boutons en dépendent pour que les biseaux soient attrayants, et les barres de défilement Motif dépendent de Mid pour être légèrement différentes de Window.

ConstanteValeurDescription
QPalette::Light2Couleur plus claire que celle de Button.
QPalette::Midlight3Entre Button et Light.
QPalette::Dark4Plus sombre que Button.
QPalette::Mid5Entre Button et Dark.
QPalette::Shadow11Une couleur très sombre. Par défaut, la couleur de l'ombre est Qt::black.

Les éléments sélectionnés (marqués) ont deux rôles :

ConstanteValeurDescription
QPalette::Highlight12Une couleur pour indiquer un élément sélectionné ou l'élément courant. Par défaut, la couleur de mise en évidence est Qt::darkBlue.
QPalette::Accent (since Qt 6.6)21Une couleur qui contraste ou complète généralement les couleurs de la base, de la fenêtre et des boutons. Elle représente généralement le choix de l'utilisateur en matière de personnalisation du bureau. Le style des composants interactifs est un cas d'utilisation typique. Si elle n'est pas explicitement définie, la valeur par défaut est Highlight.
QPalette::HighlightedText13Une couleur de texte qui contraste avec Highlight. Par défaut, la couleur du texte mis en évidence est Qt::white.

Il existe deux rôles de couleur liés aux hyperliens :

ConstanteValeurDescription
QPalette::Link14Couleur de texte utilisée pour les liens hypertextes non visités. Par défaut, la couleur du lien est Qt::blue.
QPalette::LinkVisited15Couleur de texte utilisée pour les hyperliens déjà visités. Par défaut, la couleur du lien visité est Qt::magenta.

Notez que nous n'utilisons pas les rôles Link et LinkVisited lors du rendu de texte riche dans Qt, et que nous vous recommandons d'utiliser CSS et la fonction QTextDocument::setDefaultStyleSheet() pour modifier l'apparence des liens. En voici un exemple :

    QTextBrowser browser;
    QColor linkColor(Qt::red);
    QString sheet = QString::fromLatin1("a { text-decoration: underline; color: %1 }").arg(linkColor.name());
    browser.document()->setDefaultStyleSheet(sheet);
ConstanteValeurDescription
QPalette::NoRole17Pas de rôle ; ce rôle spécial est souvent utilisé pour indiquer qu'un rôle n'a pas été attribué.

Documentation sur les fonctions des membres

QPalette::QPalette()

Construit un objet palette vide sans rôle de couleur défini.

Lorsqu'il est utilisé comme palette d'un site QWidget, les couleurs sont résolues comme décrit par QWidget::setPalette().

Voir aussi QApplication::setPalette() et QApplication::palette().

QPalette::QPalette(Qt::GlobalColor button)

Construit une palette à partir de la couleur button. Les autres couleurs sont automatiquement calculées sur la base de cette couleur. Window sera également la couleur du bouton.

QPalette::QPalette(const QColor &button)

Construit une palette à partir de la couleur button. Les autres couleurs sont automatiquement calculées sur la base de cette couleur. Window sera également la couleur du bouton.

QPalette::QPalette(const QColor &button, const QColor &window)

Construit une palette à partir d'une couleur button et d'une couleur window. Les autres couleurs sont automatiquement calculées sur la base de ces couleurs.

QPalette::QPalette(const QBrush &windowText, const QBrush &button, const QBrush &light, const QBrush &dark, const QBrush &mid, const QBrush &text, const QBrush &bright_text, const QBrush &base, const QBrush &window)

Construit une palette. Vous pouvez passer des brosses, des pixmaps ou des couleurs simples pour windowText, button, light, dark, mid, text, bright_text, base et window.

Voir aussi QBrush.

QPalette::QPalette(const QPalette &p)

Construit une copie de p.

Ce constructeur est rapide grâce au partage implicite.

[noexcept] QPalette::QPalette(QPalette &&other)

Move-construit une instance de QPalette, en la faisant pointer sur le même objet que celui vers lequel other pointait.

Après avoir été déplacé, vous ne pouvez qu'assigner ou détruire other. Toute autre opération entraînera un comportement indéfini.

[noexcept] QPalette::~QPalette()

Détruit la palette.

[since 6.6] const QBrush &QPalette::accent() const

Renvoie la brosse d'accentuation du groupe de couleurs actuel.

Cette fonction a été introduite dans Qt 6.6.

Voir aussi ColorRole et brush().

const QBrush &QPalette::alternateBase() const

Renvoie la brosse de base alternative du groupe de couleurs actuel.

Voir aussi ColorRole et brush().

const QBrush &QPalette::base() const

Renvoie la brosse de base du groupe de couleurs actuel.

Voir aussi ColorRole et brush().

const QBrush &QPalette::brightText() const

Renvoie la brosse d'avant-plan du texte clair du groupe de couleurs actuel.

Voir aussi ColorRole et brush().

const QBrush &QPalette::brush(QPalette::ColorGroup group, QPalette::ColorRole role) const

Renvoie la brosse dans la couleur spécifiée group, utilisée pour la couleur donnée role.

Voir aussi color(), setBrush(), et ColorRole.

const QBrush &QPalette::brush(QPalette::ColorRole role) const

Renvoie la brosse qui a été définie pour la couleur donnée role dans le site actuel ColorGroup.

Il s'agit d'une fonction surchargée.

Voir aussi color(), setBrush(), et ColorRole.

const QBrush &QPalette::button() const

Renvoie la brosse du bouton du groupe de couleurs actuel.

Voir aussi ColorRole et brush().

const QBrush &QPalette::buttonText() const

Renvoie la brosse d'avant-plan du texte du bouton du groupe de couleurs actuel.

Voir aussi ColorRole et brush().

qint64 QPalette::cacheKey() const

Renvoie un nombre qui identifie le contenu de cet objet QPalette. Des objets QPalette distincts peuvent avoir la même clé s'ils font référence au même contenu.

La clé cacheKey() change lorsque la palette est modifiée.

const QColor &QPalette::color(QPalette::ColorGroup group, QPalette::ColorRole role) const

Renvoie la couleur dans la couleur spécifiée group, utilisée pour la couleur donnée role.

Voir aussi brush(), setColor(), et ColorRole.

const QColor &QPalette::color(QPalette::ColorRole role) const

Renvoie la couleur qui a été définie pour la couleur donnée role dans le site actuel ColorGroup.

Il s'agit d'une fonction surchargée.

Voir aussi brush() et ColorRole.

QPalette::ColorGroup QPalette::currentColorGroup() const

Renvoie le groupe de couleurs actuel de la palette.

Voir aussi setCurrentColorGroup().

const QBrush &QPalette::dark() const

Renvoie la brosse foncée du groupe de couleurs actuel.

Voir aussi ColorRole et brush().

const QBrush &QPalette::highlight() const

Renvoie la brosse de mise en évidence du groupe de couleurs actuel.

Voir aussi ColorRole et brush().

const QBrush &QPalette::highlightedText() const

Renvoie la brosse de texte en surbrillance du groupe de couleurs actuel.

Voir aussi ColorRole et brush().

bool QPalette::isBrushSet(QPalette::ColorGroup cg, QPalette::ColorRole cr) const

Renvoie true si les valeurs ColorGroup cg et ColorRole cr ont été définies précédemment sur cette palette ; sinon, renvoie false.

La valeur de ColorGroup cg doit être inférieure à celle de QPalette::NColorGroups, mais vous pouvez utiliser QPalette::Current. Dans ce cas, le groupe de couleurs actuel précédemment défini sera utilisé.

La valeur de ColorRole cr doit être inférieure à celle de QPalette::NColorRoles.

Voir aussi setBrush() et currentColorGroup().

bool QPalette::isCopyOf(const QPalette &p) const

Renvoie true si cette palette et p sont des copies l'une de l'autre, c'est-à-dire que l'une d'entre elles a été créée en tant que copie de l'autre et qu'aucune n'a été modifiée par la suite ; sinon, renvoie false. C'est beaucoup plus strict que l'égalité.

Voir aussi operator=() et operator==().

bool QPalette::isEqual(QPalette::ColorGroup cg1, QPalette::ColorGroup cg2) const

Renvoie true (généralement rapidement) si le groupe de couleurs cg1 est égal à cg2; sinon, renvoie false.

const QBrush &QPalette::light() const

Renvoie la brosse claire du groupe de couleurs actuel.

Voir aussi ColorRole et brush().

Renvoie la brosse de texte du lien non visité du groupe de couleurs actuel.

Voir aussi ColorRole et brush().

const QBrush &QPalette::linkVisited() const

Renvoie la brosse du texte du lien visité du groupe de couleurs actuel.

Voir aussi ColorRole et brush().

const QBrush &QPalette::mid() const

Renvoie la brosse centrale du groupe de couleurs actuel.

Voir aussi ColorRole et brush().

const QBrush &QPalette::midlight() const

Renvoie la brosse de lumière moyenne du groupe de couleurs actuel.

Voir aussi ColorRole et brush().

const QBrush &QPalette::placeholderText() const

Renvoie la brosse de texte de l'espace réservé du groupe de couleurs actuel.

Note : Avant Qt 5.12, la couleur du texte de l'espace réservé était codée en dur comme QPalette::text().color() avec un alpha de 128 appliqué. Dans Qt 6, il s'agit d'une couleur indépendante.

Voir également ColorRole et brush().

QPalette QPalette::resolve(const QPalette &other) const

Renvoie un nouveau QPalette qui est l'union de cette instance et de other. Les rôles de couleur définis dans cette instance sont prioritaires. Les rôles qui ne sont pas définis dans cette instance seront repris de other.

Voir également isBrushSet.

void QPalette::setBrush(QPalette::ColorRole role, const QBrush &brush)

Définit la brosse pour la couleur donnée role à la couleur spécifiée brush pour tous les groupes de la palette.

Voir aussi brush(), setColor(), et ColorRole.

void QPalette::setBrush(QPalette::ColorGroup group, QPalette::ColorRole role, const QBrush &brush)

Définit la brosse de la couleur spécifiée group, utilisée pour la couleur donnée role, à brush.

Il s'agit d'une fonction surchargée.

Voir aussi brush(), setColor() et ColorRole.

void QPalette::setColor(QPalette::ColorGroup group, QPalette::ColorRole role, const QColor &color)

Définit la couleur dans la couleur spécifiée group, utilisée pour la couleur donnée role, à l'aplat spécifié color.

Voir également setBrush(), color() et ColorRole.

void QPalette::setColor(QPalette::ColorRole role, const QColor &color)

Définit la couleur utilisée pour la couleur donnée role, dans tous les groupes de couleurs, à l'aplat spécifié color.

Il s'agit d'une fonction surchargée.

Voir aussi brush(), setColor() et ColorRole.

void QPalette::setColorGroup(QPalette::ColorGroup cg, const QBrush &windowText, const QBrush &button, const QBrush &light, const QBrush &dark, const QBrush &mid, const QBrush &text, const QBrush &bright_text, const QBrush &base, const QBrush &window)

Définit un groupe à l'adresse cg. Vous pouvez passer des brosses, des pixmaps ou des couleurs simples pour windowText, button, light, dark, mid, text, bright_text, base et window.

Voir également QBrush.

void QPalette::setCurrentColorGroup(QPalette::ColorGroup cg)

Définit le groupe de couleurs actuel de la palette sur cg.

Voir aussi currentColorGroup().

const QBrush &QPalette::shadow() const

Renvoie la brosse d'ombre du groupe de couleurs actuel.

Voir aussi ColorRole et brush().

[noexcept] void QPalette::swap(QPalette &other)

Remplace cette instance de palette par other. Cette opération est très rapide et n'échoue jamais.

const QBrush &QPalette::text() const

Renvoie la brosse d'avant-plan du texte du groupe de couleurs actuel.

Voir aussi ColorRole et brush().

const QBrush &QPalette::toolTipBase() const

Renvoie la brosse de base de la pointe de l'outil du groupe de couleurs actuel. Cette brosse est utilisée par QToolTip et QWhatsThis.

Remarque : les bulles d'aide utilisent le groupe de couleurs Inactif de QPalette, car les bulles d'aide ne sont pas des fenêtres actives.

Voir également ColorRole et brush().

const QBrush &QPalette::toolTipText() const

Renvoie la brosse de texte de la pointe de l'outil du groupe de couleurs actuel. Cette brosse est utilisée par QToolTip et QWhatsThis.

Remarque : les bulles d'aide utilisent le groupe de couleurs Inactif de QPalette, car les bulles d'aide ne sont pas des fenêtres actives.

Voir également ColorRole et brush().

const QBrush &QPalette::window() const

Renvoie la brosse de la fenêtre (arrière-plan général) du groupe de couleurs actuel.

Voir aussi ColorRole et brush().

const QBrush &QPalette::windowText() const

Renvoie la brosse du texte de la fenêtre (avant-plan général) du groupe de couleurs actuel.

Voir aussi ColorRole et brush().

QPalette::operator QVariant() const

Retourne la palette sous forme de QVariant

bool QPalette::operator!=(const QPalette &p) const

Renvoie true (lentement) si cette palette est différente de p; sinon, renvoie false (généralement rapidement).

Note : Le site actuel ColorGroup n'est pas pris en compte lors de la comparaison des palettes

Voir aussi operator==().

[noexcept] QPalette &QPalette::operator=(QPalette &&other)

Move-assigne other à cette instance QPalette.

QPalette &QPalette::operator=(const QPalette &p)

Affecte p à cette palette et renvoie une référence à cette palette.

Cette opération est rapide grâce au partage implicite.

[since 6.6] bool QPalette::operator==(const QPalette &p) const

Renvoie true (généralement rapidement) si cette palette est égale à p; sinon, renvoie false (lentement).

Note : Les éléments suivants ne sont pas pris en compte lors de la comparaison des palettes :

Cette fonction a été introduite dans Qt 6.6.

Voir aussi operator!=().

Non-membres apparentés

QDataStream &operator<<(QDataStream &s, const QPalette &p)

Écrit la palette p dans le flux s et renvoie une référence au flux.

Voir aussi Format des opérateurs QDataStream.

QDataStream &operator>>(QDataStream &s, QPalette &p)

Lit une palette dans le flux, s dans la palette p, et renvoie une référence au flux.

Voir aussi Format des opérateurs QDataStream.

© 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.