Sur cette page

QPalette Class

La classe QPalette contient des groupes de couleurs pour chaque état de widget. En savoir plus...

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 », « Désactivée » et « Inactive ». Tous les widgets de Qt contiennent une palette et l'utilisent pour s'afficher. Cela rend l'interface utilisateur facilement configurable et facilite le maintien d'une cohérence visuelle.

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 (et non les fenêtres) qui sont désactivés pour une raison quelconque.

Les fenêtres actives et inactives peuvent toutes deux contenir des widgets désactivés. (Les widgets désactivés sont souvent appelés « inaccessibles » ou « grisés ».)

Dans la plupart des styles, les groupes « Actif » et « Inactif » ont le même aspect.

Les couleurs et les pinceaux peuvent être définis pour des rôles particuliers dans n'importe quel groupe de couleurs d'une palette à l'aide des fonctions setColor() et setBrush(). Un groupe de couleurs contient un ensemble de couleurs utilisées par les widgets pour s'afficher. Nous recommandons aux widgets d’utiliser les rôles de groupe de couleurs de la palette, tels que « foreground » et « base », plutôt que des couleurs littérales comme « red » ou « turquoise ». Les rôles de couleur sont énumérés et définis dans la documentation 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. C’est ce que font les Qt Widgets lorsqu’ils sont dessinés.

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

Il existe également des accesseurs correspondants : color() et brush(), ainsi qu’une fonction pratique couramment utilisée pour récupérer l’ ColorRole de l’ ColorGroup e actuel : window(), windowText(), base(), etc.

Vous pouvez copier une palette à l’aide du constructeur de copie et vérifier si deux palettes sont identiques à l’aide de ` isCopyOf()`.

QPalette est optimisée grâce à l'utilisation du partage implicite; il est donc très efficace de passer des objets QPalette en arguments.

Avertissement : certains styles n’utilisent pas la palette pour tous les dessins, par exemple s’ils ont recours à 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
QPalette::Disabled1 
QPalette::Active0 
QPalette::Inactive2 
QPalette::NormalActivesynonyme de « Actif »

enum QPalette::ColorRole

Les rôles des couleurs

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

Les rôles principaux sont les suivants :

ConstanteValeurDescription
QPalette::Window10Une couleur d'arrière-plan générale.
QPalette::WindowText0Une couleur de premier plan générale.
QPalette::Base9Principalement utilisée comme couleur d’arrière-plan pour les widgets de saisie de texte, mais peut également servir à d’autres affichages, tels que l’arrière-plan des listes déroulantes des listes combinées et des poignées de barres d’outils. Elle est généralement blanche ou d’une autre couleur claire.
QPalette::AlternateBase16Utilisée comme couleur d'arrière-plan alternative dans les vues où les couleurs des lignes alternent (voir QAbstractItemView::setAlternatingRowColors()).
QPalette::ToolTipBase18Utilisée comme couleur d'arrière-plan pour QToolTip et QWhatsThis. Les info-bulles utilisent le groupe de couleurs « Inactif » de QPalette, car elles ne sont pas des fenêtres actives.
QPalette::ToolTipText19Utilisée comme couleur de premier plan pour QToolTip et QWhatsThis. Les infobulles utilisent le groupe de couleurs « Inactive » de QPalette, car elles ne sont pas des fenêtres actives.
QPalette::PlaceholderText20Utilisée comme couleur de placeholder pour divers widgets de saisie de texte. Cette valeur d'énumération a été introduite dans Qt 5.12
QPalette::Text6La couleur de premier plan utilisée avec Base. Elle est généralement identique à celle de WindowText; dans ce cas, elle doit offrir un bon contraste avec Window et Base.
QPalette::Button1La couleur d’arrière-plan générale des boutons. Cet arrière-plan peut être différent de Window, car certains styles nécessitent une couleur d’arrière-plan différente pour les boutons.
QPalette::ButtonText8Une couleur de premier plan utilisée avec la couleur de Button.
QPalette::BrightText7Une couleur de texte très différente de celle de WindowText, et qui offre un bon contraste avec, par exemple, Dark. Généralement utilisée pour le texte devant être affiché là où Text ou WindowText offriraient un contraste insuffisant, comme sur les boutons enfoncés. Notez que les couleurs de texte peuvent être utilisées pour d’autres éléments que les mots ; bien qu’elles soient généralement réservées au texte, il est assez courant d’utiliser les rôles de couleur de texte pour des lignes, des icônes, etc.

Certains rôles de couleur sont principalement utilisés pour les effets de biseau et d’ombre en 3D. Tous ces rôles sont normalement dérivés de Window, et leur utilisation dépend de cette relation. Par exemple, les boutons s’appuient sur ce lien pour rendre les biseaux esthétiques, et les barres de défilement Motif s’appuient sur Mid pour se distinguer légèrement de Window.

ConstanteValeurDescription
QPalette::Light2Couleur plus claire que celle de Button.
QPalette::Midlight3Entre Button et Light.
QPalette::Dark4Plus foncé que Button.
QPalette::Mid5Entre Button et Dark.
QPalette::Shadow11Une couleur très foncée. 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 permettant d'indiquer un élément sélectionné ou l'élément actif. Par défaut, la couleur de mise en évidence est Qt::darkBlue.
QPalette::Accent (since Qt 6.6)21Une couleur qui contraste généralement avec les couleurs de base, de fenêtre et de bouton, ou qui les complète. Elle correspond généralement au choix de personnalisation du bureau de l'utilisateur. La mise en forme des composants interactifs en est un cas d'utilisation typique. Sauf indication contraire, 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 surbrillance 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 des liens est Qt::blue.
QPalette::LinkVisited15Couleur de texte utilisée pour les liens hypertextes déjà visités. Par défaut, la couleur des liens visités est Qt::magenta.

Notez que nous n'utilisons pas les rôles « Link » et « LinkVisited » lors du rendu du texte enrichi dans Qt, et que nous vous recommandons d'utiliser le CSS et la fonction QTextDocument::setDefaultStyleSheet() pour modifier l'apparence des liens. Par 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::NoRole17Aucun rôle ; ce rôle spécial est souvent utilisé pour indiquer qu’aucun rôle n’a été attribué.

Documentation des fonctions membres

QPalette::QPalette()

Crée un objet « palette » vide, sans rôle de couleur défini.

Lorsqu'il est utilisé comme palette d'un objet « QWidget », les couleurs sont déterminées comme décrit par la fonction QWidget::setPalette().

Voir également QApplication::setPalette() et QApplication::palette().

QPalette::QPalette(Qt::GlobalColor button)

Crée une palette à partir de la couleur button. Les autres couleurs sont calculées automatiquement à partir de celle-ci. La couleur Window sera également celle du bouton.

QPalette::QPalette(const QColor &button)

Crée une palette à partir de la couleur button. Les autres couleurs sont calculées automatiquement en fonction de celle-ci. La couleur Window sera également celle du bouton.

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

Crée une palette à partir d'une couleur button et d'un window. Les autres couleurs sont calculées automatiquement à partir de ces deux 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)

Crée une palette. Vous pouvez lui transmettre soit des pinceaux, soit des images bitmap, soit des couleurs simples pour les fonctions suivantes : windowText, button, light, dark, mid, text, bright_text, base et window.

Voir également QBrush.

QPalette::QPalette(const QPalette &p)

Crée une copie de ` p`.

Ce constructeur est rapide grâce au partage implicite.

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

La fonction `move` construit une instance de `QPalette` en la faisant pointer vers le même objet que celui vers lequel pointait ` other `.

Une fois le déplacement effectué, vous ne pouvez plus qu'affecter une valeur à ` other` ou la détruire. Toute autre opération entraînera un comportement indéfini.

[noexcept] QPalette::~QPalette()

Supprime la palette.

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

Renvoie le pinceau d'accentuation du groupe de couleurs actuel.

Cette fonction a été introduite dans Qt 6.6.

Voir également ColorRole et brush().

const QBrush &QPalette::alternateBase() const

Renvoie le pinceau de base alternatif du groupe de couleurs actuel.

Voir également ColorRole et brush().

const QBrush &QPalette::base() const

Renvoie le pinceau de base du groupe de couleurs actuel.

Voir également ` ColorRole ` et ` brush()`.

const QBrush &QPalette::brightText() const

Renvoie le pinceau de texte clair de premier plan du groupe de couleurs actuel.

Voir également ColorRole et brush().

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

Renvoie le pinceau de la couleur spécifiée group, utilisé pour la couleur donnée role.

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

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

Renvoie le pinceau défini pour l'role de couleur donnée dans l'ColorGroup e actuel.

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

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

const QBrush &QPalette::button() const

Renvoie le pinceau « bouton » du groupe de couleurs actuel.

Voir également ColorRole et brush().

const QBrush &QPalette::buttonText() const

Renvoie le pinceau de premier plan du texte du bouton correspondant au groupe de couleurs actuel.

Voir également 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 méthode cacheKey() change lorsque la palette est modifiée.

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

Renvoie la couleur contenue dans l'group de couleur spécifiée, utilisée pour l'role de couleur donnée.

Voir également brush(), setColor() et ColorRole.

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

Renvoie la couleur qui a été définie pour l'role de couleur donnée dans l'ColorGroup.

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

Voir également brush() et ColorRole.

QPalette::ColorGroup QPalette::currentColorGroup() const

Renvoie le groupe de couleurs actuel de la palette.

Voir également setCurrentColorGroup().

const QBrush &QPalette::dark() const

Renvoie le pinceau foncé du groupe de couleurs actuel.

Voir également ColorRole et brush().

const QBrush &QPalette::highlight() const

Renvoie le pinceau de surlignage du groupe de couleurs actuel.

Voir également ` ColorRole ` et ` brush()`.

const QBrush &QPalette::highlightedText() const

Renvoie le pinceau de texte en surbrillance du groupe de couleurs actuel.

Voir également ColorRole et brush().

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

Renvoie « true » si les propriétés « ColorGroup » ( cg ) et « ColorRole » ( cr ) ont déjà été définies sur cette palette ; sinon, renvoie « false ».

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

La fonction ColorRole cr doit être inférieure à QPalette::NColorRoles.

Voir également 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 si l'une d'elles a été créée à partir de l'autre et qu'aucune n'a été modifiée par la suite ; sinon, renvoie « false ». Cette opération est beaucoup plus stricte que la comparaison d'égalité.

Voir également 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 le pinceau clair du groupe de couleurs actuel.

Voir également ColorRole et brush().

Renvoie le pinceau de texte des liens non visités du groupe de couleurs actuel.

Voir aussi ColorRole et brush().

const QBrush &QPalette::linkVisited() const

Renvoie le pinceau de texte « lien visité » du groupe de couleurs actuel.

Voir aussi ColorRole et brush().

const QBrush &QPalette::mid() const

Renvoie la nuance intermédiaire du groupe de couleurs actuel.

Voir également ColorRole et brush().

const QBrush &QPalette::midlight() const

Renvoie le pinceau « midlight » du groupe de couleurs actuel.

Voir également ColorRole et brush().

const QBrush &QPalette::placeholderText() const

Renvoie le pinceau de texte de remplacement du groupe de couleurs actuel.

Remarque : avant Qt 5.12, la couleur du texte de remplacement était codée en dur comme suit : 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 nouvel objet ` QPalette ` qui est l'union de cette instance et de ` other`. Les rôles de couleur définis dans cette instance ont la priorité. 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 le pinceau correspondant à la couleur indiquée role sur la valeur spécifiée brush pour tous les groupes de la palette.

Voir également brush(), setColor() et ColorRole.

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

Définit le pinceau de la couleur spécifiée group, utilisé pour la couleur donnée role, sur brush.

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

Voir également brush(), setColor() et ColorRole.

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

Définit la couleur de l'group de couleur spécifiée, utilisée pour la role de couleur donnée, sur la color unie spécifiée.

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

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

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

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

Voir également 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 le groupe à l'adresse cg. Vous pouvez passer soit des pinceaux, soit des images bitmap, soit des couleurs unies pour les éléments suivants : windowText, button, light, dark, mid, text, bright_text, base et window.

Voir également QBrush.

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

Définissez le groupe de couleurs actuel de la palette sur « cg ».

Voir aussi currentColorGroup().

const QBrush &QPalette::shadow() const

Renvoie le pinceau d'ombre du groupe de couleurs actuel.

Voir également ColorRole et brush().

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

Remplace cette instance de palette par other. Cette opération est très rapide et ne rencontre jamais d'échec.

const QBrush &QPalette::text() const

Renvoie le pinceau de texte de premier plan du groupe de couleurs actuel.

Voir également ColorRole et brush().

const QBrush &QPalette::toolTipBase() const

Renvoie le pinceau de base des infobulles du groupe de couleurs actuel. Ce pinceau est utilisé par QToolTip et QWhatsThis.

Remarque : les info- bulles utilisent le groupe de couleurs « Inactif » de QPalette, car elles ne constituent pas des fenêtres actives.

Voir également ColorRole et brush().

const QBrush &QPalette::toolTipText() const

Renvoie le pinceau de texte des info-bulles du groupe de couleurs actuel. Ce pinceau est utilisé par QToolTip et QWhatsThis.

Remarque : les infobulles utilisent le groupe de couleurs « Inactif » de QPalette, car elles ne sont pas des fenêtres actives.

Voir également ColorRole et brush().

const QBrush &QPalette::window() const

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

Voir également ColorRole et brush().

const QBrush &QPalette::windowText() const

Renvoie le pinceau de texte de fenêtre (premier plan général) du groupe de couleurs actuel.

Voir également ColorRole et brush().

QPalette::operator QVariant() const

Renvoie la palette sous la forme d'un 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).

Remarque : la valeur actuelle de ` ColorGroup ` n'est pas prise en compte lors de la comparaison des palettes

Voir aussi operator==().

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

Cette opération attribue other à cette instance de QPalette.

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

Attribue « 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).

Remarque : 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!=().

Éléments non membres associés

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

Écrit la palette « p » dans le flux « s » et renvoie une référence à ce flux.

Voir également Format des opérateurs QDataStream.

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

Lit une palette à partir du flux, la trans s e dans la palette p, puis renvoie une référence au flux.

Voir également le 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.