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

Référence des feuilles de style Gestion de la mise en page

Exemples de feuilles de style Qt

Nous allons maintenant voir quelques exemples pour vous aider à vous familiariser avec l'utilisation des feuilles de style Qt.

Utilisation des feuilles de style

Personnalisation des couleurs de premier plan et d’arrière-plan

Commençons par définir la couleur jaune comme couleur d'arrière-plan de tous les QLineEdits d’une application. Cela peut se faire comme suit :

qApp->setStyleSheet("QLineEdit { background-color: yellow }");

Si nous souhaitons que la propriété s'applique uniquement aux « QLineEdits » qui sont des enfants (ou petits-enfants, ou arrière-petits-enfants) d'une boîte de dialogue spécifique, nous ferons plutôt comme suit :

myDialog->setStyleSheet("QLineEdit { background-color: yellow }");

Si nous souhaitons que la propriété s’applique uniquement à une QLineEdit spécifique, nous pouvons lui attribuer un nom à l’aide de ` QObject::setObjectName()` et utiliser un sélecteur d’ID pour y faire référence :

myDialog->setStyleSheet("QLineEdit#nameEdit { background-color: yellow }");

Sinon, nous pouvons définir la propriété ` background-color ` directement sur l’ QLineEdit, en omettant le sélecteur :

nameEdit->setStyleSheet("background-color: yellow");

Pour garantir un bon contraste, nous devons également spécifier une couleur adaptée pour le texte :

nameEdit->setStyleSheet("color: blue; background-color: yellow");

Il peut être judicieux de modifier également les couleurs utilisées pour le texte sélectionné :

nameEdit->setStyleSheet("color: blue;"
                        "background-color: yellow;"
                        "selection-color: yellow;"
                        "selection-background-color: blue;");

Personnalisation à l’aide de propriétés dynamiques

Il existe de nombreuses situations où nous devons présenter un formulaire comportant des champs obligatoires. Pour indiquer à l’utilisateur qu’un champ est obligatoire, une solution efficace (bien que discutable sur le plan esthétique) consiste à utiliser le jaune comme couleur d’arrière-plan pour ces champs. Il s’avère que cela est très facile à mettre en œuvre à l’aide des feuilles de style Qt. Tout d’abord, nous utiliserions la feuille de style suivante à l’échelle de l’application :

*[mandatoryField="true"] { background-color: yellow }

Cela signifie que chaque widget dont la propriété Qt ` mandatoryField ` est définie sur `true` aura un fond jaune.

Ensuite, pour chaque widget de champ obligatoire, il suffirait de créer à la volée une propriété ` mandatoryField ` et de la définir sur `true`. Par exemple :

QLineEdit *nameEdit = new QLineEdit(this);
nameEdit->setProperty("mandatoryField", true);

QLineEdit *emailEdit = new QLineEdit(this);
emailEdit->setProperty("mandatoryField", true);

QSpinBox *ageSpinBox = new QSpinBox(this);
ageSpinBox->setProperty("mandatoryField", true);

Personnalisation d’un QPushButton à l’aide du modèle de boîte

Cette fois-ci, nous allons montrer comment créer un « QPushButton » rouge. Cet « QPushButton » serait vraisemblablement associé à un code très destructeur.

Dans un premier temps, nous serions tentés d’utiliser cette feuille de style :

QPushButton#evilButton { background-color: red }

Cependant, le résultat est un bouton terne et plat, sans bordures :

Bouton rouge plat

Voici ce qui s’est passé :

  • Nous avons formulé une demande qui ne peut pas être satisfaite en utilisant uniquement les styles natifs (par exemple, le moteur de thèmes natif de Windows ne nous permet pas de spécifier la couleur d’arrière-plan d’un bouton).
  • Par conséquent, le bouton est affiché à l’aide de feuilles de style.
  • Comme nous n'avons spécifié aucune valeur pour ` border-width ` et `border-style`, nous obtenons par défaut une bordure de 0 pixel de large, de style ` none`.

Améliorons la situation en définissant une bordure :

QPushButton#evilButton {
    background-color: red;
    border-style: outset;
    border-width: 2px;
    border-color: beige;
}

Bouton rouge avec un liseré beige

Le résultat est déjà bien meilleur. Mais le bouton semble un peu à l'étroit. Spécifions un espacement entre la bordure et le texte à l'aide de la propriété `padding`. De plus, nous allons imposer une largeur minimale, arrondir les coins et choisir une police plus grande pour rendre le bouton plus esthétique :

QPushButton#evilButton {
    background-color: red;
    border-style: outset;
    border-width: 2px;
    border-radius: 10px;
    border-color: beige;
    font: bold 14px;
    min-width: 10em;
    padding: 6px;
}

Bouton rouge avec un contour rond beige et un texte en gros caractères bien visibles

Le seul problème qui subsiste est que le bouton ne réagit pas lorsque l'on appuie dessus. Nous pouvons y remédier en spécifiant une couleur d'arrière-plan légèrement différente et en utilisant un style de bordure différent.

QPushButton#evilButton {
    background-color: red;
    border-style: outset;
    border-width: 2px;
    border-radius: 10px;
    border-color: beige;
    font: bold 14px;
    min-width: 10em;
    padding: 6px;
}
QPushButton#evilButton:pressed {
    background-color: rgb(224, 0, 0);
    border-style: inset;
}

Personnalisation du sous-contrôle « indicateur de menu » du QPushButton

Les sous-contrôles permettent d’accéder aux sous-éléments d’un widget. Par exemple, un bouton « QPushButton » associé à un menu (à l’aide de ` QPushButton::setMenu()`) dispose d’un indicateur de menu. Personnalisons l’indicateur de menu du bouton rouge :

QPushButton#evilButton::menu-indicator {
    image: url(myindicator.png);
}

Par défaut, l’indicateur de menu est situé dans le coin inférieur droit du rectangle de remplissage. Nous pouvons modifier cela en spécifiant `subcontrol-position ` et `subcontrol-origin` pour ancrer l’indicateur différemment. Nous pouvons également utiliser `top` et `left` pour déplacer l’indicateur de quelques pixels. Par exemple :

QPushButton::menu-indicator {
    image: url(myindicator.png);
    subcontrol-position: right center;
    subcontrol-origin: padding;
    left: -2px;
}

Cela positionne l’ myindicator.png au centre à droite du rectangle de remplissage de l’ QPushButton(voir subcontrol-origin pour plus d’informations).

Exemple de sélecteur complexe

Puisque le rouge semble être notre couleur préférée, rendons le texte de l’ QLineEdit rouge en définissant la feuille de style suivante à l’échelle de l’application :

QLineEdit { color: red }

Cependant, nous souhaitons indiquer visuellement qu’un QLineEdit est en lecture seule en lui donnant une couleur grise :

QLineEdit { color: red }
QLineEdit[readOnly="true"] { color: gray }

À un moment donné, notre équipe de conception nous demande que tous les « QLineEdits » du formulaire d’inscription (dont l’ object name est registrationDialog) soient de couleur marron :

QLineEdit { color: red }
QLineEdit[readOnly="true"] { color: gray }
#registrationDialog QLineEdit { color: brown }

Après quelques réunions de conception de l’interface utilisateur, nous décidons que tous nos champs « QDialog» doivent avoir des « QLineEdit» de couleur marron :

QLineEdit { color: red }
QLineEdit[readOnly="true"] { color: gray }
QDialog QLineEdit { color: brown }

Question : que se passe-t-il si nous avons un « QLineEdit » en lecture seule dans un « QDialog » ? [Indice : la section « Résolution des conflits » ci-dessus explique ce qui se passe dans ce genre de cas.]

Personnalisation de widgets spécifiques

Cette section fournit des exemples permettant de personnaliser des widgets spécifiques à l’aide de feuilles de style.

Personnalisation de QAbstractScrollArea

L'arrière-plan de n'importe quelle QAbstractScrollArea (vues d'éléments, QTextEdit et QTextBrowser) peut être défini à l'aide des propriétés d'arrière-plan. Par exemple, pour définir une image d'arrière-plan qui défile avec la barre de défilement :

QTextEdit, QListView {
    background-color: white;
    background-image: url(draft.png);
    background-attachment: scroll;
}

Si l’image d’arrière-plan doit être fixée à la fenêtre d’affichage :

QTextEdit, QListView {
    background-color: white;
    background-image: url(draft.png);
    background-attachment: fixed;
}

Personnalisation de QCheckBox

La mise en forme d’un QCheckBox est presque identique à celle d’un QRadioButton. La principale différence réside dans le fait qu’un QCheckBox à trois états possède un état indéterminé.

QCheckBox {
    spacing: 5px;
}

QCheckBox::indicator {
    width: 13px;
    height: 13px;
}

QCheckBox::indicator:unchecked {
    image: url(:/images/checkbox_unchecked.png);
}

QCheckBox::indicator:unchecked:hover {
    image: url(:/images/checkbox_unchecked_hover.png);
}

QCheckBox::indicator:unchecked:pressed {
    image: url(:/images/checkbox_unchecked_pressed.png);
}

QCheckBox::indicator:checked {
    image: url(:/images/checkbox_checked.png);
}

QCheckBox::indicator:checked:hover {
    image: url(:/images/checkbox_checked_hover.png);
}

QCheckBox::indicator:checked:pressed {
    image: url(:/images/checkbox_checked_pressed.png);
}

QCheckBox::indicator:indeterminate:hover {
    image: url(:/images/checkbox_indeterminate_hover.png);
}

QCheckBox::indicator:indeterminate:pressed {
    image: url(:/images/checkbox_indeterminate_pressed.png);
}

Personnalisation de QComboBox

Nous allons examiner un exemple dans lequel le bouton déroulant d’une QComboBox semble « fusionné » avec le cadre de la liste déroulante.

QComboBox {
    border: 1px solid gray;
    border-radius: 3px;
    padding: 1px 18px 1px 3px;
    min-width: 6em;
}

QComboBox:editable {
    background: white;
}

QComboBox:!editable, QComboBox::drop-down:editable {
     background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                 stop: 0 #E1E1E1, stop: 0.4 #DDDDDD,
                                 stop: 0.5 #D8D8D8, stop: 1.0 #D3D3D3);
}

/* QComboBox gets the "on" state when the popup is open */
QComboBox:!editable:on, QComboBox::drop-down:editable:on {
    background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                stop: 0 #D3D3D3, stop: 0.4 #D8D8D8,
                                stop: 0.5 #DDDDDD, stop: 1.0 #E1E1E1);
}

QComboBox:on { /* shift the text when the popup opens */
    padding-top: 3px;
    padding-left: 4px;
}

QComboBox::drop-down {
    subcontrol-origin: padding;
    subcontrol-position: top right;
    width: 15px;

    border-left-width: 1px;
    border-left-color: darkgray;
    border-left-style: solid; /* just a single line */
    border-top-right-radius: 3px; /* same radius as the QComboBox */
    border-bottom-right-radius: 3px;
}

QComboBox::down-arrow {
    image: url(/usr/share/icons/crystalsvg/16x16/actions/1downarrow.png);
}

QComboBox::down-arrow:on { /* shift the arrow when popup is open */
    top: 1px;
    left: 1px;
}

La liste déroulante de l’ QComboBox est un QAbstractItemView et son style est défini à l’aide du sélecteur de descendant :

QComboBox QAbstractItemView {
    border: 2px solid darkgray;
    selection-background-color: lightgray;
}

Personnalisation de QDockWidget

La barre de titre et les boutons d’un QDockWidget peuvent être personnalisés comme suit :

QDockWidget {
    border: 1px solid lightgray;
    titlebar-close-icon: url(close.png);
    titlebar-normal-icon: url(undock.png);
}

QDockWidget::title {
    text-align: left; /* align the text to the left */
    background: lightgray;
    padding-left: 5px;
}

QDockWidget::close-button, QDockWidget::float-button {
    border: 1px solid transparent;
    background: darkgray;
    padding: 0px;
}

QDockWidget::close-button:hover, QDockWidget::float-button:hover {
    background: gray;
}

QDockWidget::close-button:pressed, QDockWidget::float-button:pressed {
    padding: 1px -1px -1px 1px;
}

Si l’on souhaite déplacer les boutons du widget d’ancrage vers la gauche, la feuille de style suivante peut être utilisée :

QDockWidget {
    border: 1px solid lightgray;
    titlebar-close-icon: url(close.png);
    titlebar-normal-icon: url(float.png);
}

QDockWidget::title {
    text-align: left;
    background: lightgray;
    padding-left: 35px;
}

QDockWidget::close-button, QDockWidget::float-button {
    background: darkgray;
    padding: 0px;
    icon-size: 14px; /* maximum icon size */
}

QDockWidget::close-button:hover, QDockWidget::float-button:hover {
    background: gray;
}

QDockWidget::close-button:pressed, QDockWidget::float-button:pressed {
    padding: 1px -1px -1px 1px;
}

QDockWidget::close-button {
    subcontrol-position: top left;
    subcontrol-origin: margin;
    position: absolute;
    top: 0px; left: 0px; bottom: 0px;
    width: 14px;
}

QDockWidget::float-button {
    subcontrol-position: top left;
    subcontrol-origin: margin;
    position: absolute;
    top: 0px; left: 16px; bottom: 0px;
    width: 14px;
}

Remarque : pour personnaliser le séparateur (poignée de redimensionnement) d'une fenêtre « QDockWidget », utilisez QMainWindow::separator.

Personnalisation de QFrame

Le style d'un QFrame est défini à l'aide du modèle de boîte (Box Model).

QFrame, QLabel, QToolTip {
    border: 2px solid green;
    border-radius: 4px;
    padding: 2px;
    background-image: url(images/welcome.png);
}

Personnalisation de QGroupBox

Prenons un exemple qui déplace le titre de l’ QGroupBox au centre.

QGroupBox {
    background-color: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                      stop: 0 #E0E0E0, stop: 1 #FFFFFF);
    border: 2px solid gray;
    border-radius: 5px;
    margin-top: 1ex; /* leave space at the top for the title */
}

QGroupBox::title {
    subcontrol-origin: margin;
    subcontrol-position: top center; /* position at the top center */
    padding: 0 3px;
    background-color: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                      stop: 0 #FF0ECE, stop: 1 #FFFFFF);
}

Pour une QGroupBox à cocher, utilisez le sous-contrôle {#indicator-sub}{::indicator} et stylisez-le exactement comme un QCheckBox (c'est-à-dire)

QGroupBox::indicator {
    width: 13px;
    height: 13px;
}

QGroupBox::indicator:unchecked {
    image: url(:/images/checkbox_unchecked.png);
}

/* proceed with styling just like QCheckBox */

Personnalisation de QHeaderView

QHeaderView est personnalisé comme suit :

QHeaderView::section {
    background-color: qlineargradient(x1:0, y1:0, x2:0, y2:1,
                                      stop:0 #616161, stop: 0.5 #505050,
                                      stop: 0.6 #434343, stop:1 #656565);
    color: white;
    padding-left: 4px;
    border: 1px solid #6c6c6c;
}

QHeaderView::section:checked
{
    background-color: red;
}

/* style the sort indicator */
QHeaderView::down-arrow {
    image: url(down_arrow.png);
}

QHeaderView::up-arrow {
    image: url(up_arrow.png);
}

Personnalisation de QLineEdit

Le cadre d’un champ de saisie de type « QLineEdit » est stylisé à l’aide du modèle de boîte (Box Model). Pour créer un champ de saisie aux coins arrondis, on peut définir :

QLineEdit {
    border: 2px solid gray;
    border-radius: 10px;
    padding: 0 8px;
    background: yellow;
    selection-background-color: darkgray;
}

Le caractère de mot de passe des champs de saisie en ligne dotés du mode « écho » d’ QLineEdit::Password peut être défini à l’aide de :

QLineEdit[echoMode="2"] {
    lineedit-password-character: 9679;
}

L'arrière-plan d'un QLineEdit en lecture seule peut être modifié comme suit :

QLineEdit:read-only {
    background: lightblue;
}

Personnalisation de QListView

La couleur d’arrière-plan des lignes en alternance peut être personnalisée à l’aide de la feuille de style suivante :

QListView {
    alternate-background-color: yellow;
}

Pour afficher un arrière-plan spécial lorsque l’on survole des éléments, on peut utiliser le sous-contrôle ::item. Par exemple,

QListView {
    show-decoration-selected: 1; /* make the selection span the entire width of the view */
}

QListView::item:alternate {
    background: #EEEEEE;
}

QListView::item:selected {
    border: 1px solid #6a6ea9;
}

QListView::item:selected:!active {
    background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                stop: 0 #ABAFE5, stop: 1 #8588B2);
}

QListView::item:selected:active {
    background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                stop: 0 #6a6ea9, stop: 1 #888dd9);
}

QListView::item:hover {
    background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                stop: 0 #FAFBFE, stop: 1 #DCDEF1);
}

Personnalisation de QMainWindow

Le séparateur d’une QMainWindow peut être stylisé comme suit :

QMainWindow::separator {
    background: yellow;
    width: 10px; /* when vertical */
    height: 10px; /* when horizontal */
}

QMainWindow::separator:hover {
    background: red;
}

Personnalisation de QMenu

Les éléments individuels d'un QMenu sont stylisés à l'aide du sous-contrôle « item » comme suit :

QMenu {
    background-color: #ABABAB; /* sets background of the menu */
    border: 1px solid black;
}

QMenu::item {
    /* sets background of menu item. set this to something non-transparent
        if you want menu color and menu item color to be different */
    background-color: transparent;
}

QMenu::item:selected { /* when user selects item using mouse or keyboard */
    background-color: #654321;
}

Pour une personnalisation plus avancée, utilisez une feuille de style comme suit :

QMenu {
    background-color: white;
    margin: 2px; /* some spacing around the menu */
}

QMenu::item {
    padding: 2px 25px 2px 20px;
    border: 1px solid transparent; /* reserve space for selection border */
}

QMenu::item:selected {
    border-color: darkblue;
    background: rgba(100, 100, 100, 150);
}

QMenu::icon:checked { /* appearance of a 'checked' icon */
    background: gray;
    border: 1px inset gray;
    position: absolute;
    top: 1px;
    right: 1px;
    bottom: 1px;
    left: 1px;
}

QMenu::separator {
    height: 2px;
    background: lightblue;
    margin-left: 10px;
    margin-right: 5px;
}

QMenu::indicator {
    width: 13px;
    height: 13px;
}

/* non-exclusive indicator = check box style indicator (see QActionGroup::setExclusive) */
QMenu::indicator:non-exclusive:unchecked {
    image: url(:/images/checkbox_unchecked.png);
}

QMenu::indicator:non-exclusive:unchecked:selected {
    image: url(:/images/checkbox_unchecked_hover.png);
}

QMenu::indicator:non-exclusive:checked {
    image: url(:/images/checkbox_checked.png);
}

QMenu::indicator:non-exclusive:checked:selected {
    image: url(:/images/checkbox_checked_hover.png);
}

/* exclusive indicator = radio button style indicator (see QActionGroup::setExclusive) */
QMenu::indicator:exclusive:unchecked {
    image: url(:/images/radiobutton_unchecked.png);
}

QMenu::indicator:exclusive:unchecked:selected {
    image: url(:/images/radiobutton_unchecked_hover.png);
}

QMenu::indicator:exclusive:checked {
    image: url(:/images/radiobutton_checked.png);
}

QMenu::indicator:exclusive:checked:selected {
    image: url(:/images/radiobutton_checked_hover.png);
}

Personnalisation de QMenuBar

QMenuBar se personnalise comme suit :

QMenuBar {
    background-color: qlineargradient(x1:0, y1:0, x2:0, y2:1,
                                      stop:0 lightgray, stop:1 darkgray);
    spacing: 3px; /* spacing between menu bar items */
}

QMenuBar::item {
    padding: 1px 4px;
    background: transparent;
    border-radius: 4px;
}

QMenuBar::item:selected { /* when selected using mouse or keyboard */
    background: #a8a8a8;
}

QMenuBar::item:pressed {
    background: #888888;
}

Personnalisation de QProgressBar

La bordure, le segment et l'alignement du texte de la barre de progression ( QProgressBar) peuvent être personnalisés à l'aide de feuilles de style. Cependant, si une propriété ou un sous-contrôle est personnalisé, toutes les autres propriétés ou sous-contrôles doivent également l'être.

Barre de progression indiquant 30 %

Par exemple, nous changeons la bordure en gris et la barre de progression en bleu céruléen.

QProgressBar {
    border: 2px solid grey;
    border-radius: 5px;
}

QProgressBar::chunk {
    background-color: #05B8CC;
    width: 20px;
}

Il reste alors l’alignement du texte, que nous personnalisons en centrant le texte sur la barre de progression.

QProgressBar {
    border: 2px solid grey;
    border-radius: 5px;
    text-align: center;
}

Une marge peut être ajoutée pour rendre les segments plus visibles.

Barre de progression à crans

Dans la capture d'écran ci-dessus, nous utilisons une marge de 0,5 pixel.

QProgressBar::chunk {
    background-color: #CD96CD;
    width: 10px;
    margin: 0.5px;
}

Personnalisation de QPushButton

Un « QPushButton » est stylisé comme suit :

QPushButton {
    border: 2px solid #8f8f91;
    border-radius: 6px;
    background-color: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                      stop: 0 #f6f7fa, stop: 1 #dadbde);
    min-width: 80px;
}

QPushButton:pressed {
    background-color: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                      stop: 0 #dadbde, stop: 1 #f6f7fa);
}

QPushButton:flat {
    border: none; /* no border for a flat push button */
}

QPushButton:default {
    border-color: navy; /* make the default button prominent */
}

Pour un QPushButton doté d'un menu, utilisez le sous-contrôle ::menu-indicator.

QPushButton:open { /* when the button has its menu open */
    background-color: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                      stop: 0 #dadbde, stop: 1 #f6f7fa);
}

QPushButton::menu-indicator {
    image: url(menu_indicator.png);
    subcontrol-origin: padding;
    subcontrol-position: bottom right;
}

QPushButton::menu-indicator:pressed, QPushButton::menu-indicator:open {
    position: relative;
    top: 2px; left: 2px; /* shift the arrow by 2 px */
}

Les boutons « checkable » ( QPushButton ) ont le pseudo-état :checked défini.

Personnalisation de QRadioButton

L'indicateur d'un QRadioButton peut être modifié à l'aide de :

QRadioButton::indicator {
    width: 13px;
    height: 13px;
}

QRadioButton::indicator::unchecked {
    image: url(:/images/radiobutton_unchecked.png);
}

QRadioButton::indicator:unchecked:hover {
    image: url(:/images/radiobutton_unchecked_hover.png);
}

QRadioButton::indicator:unchecked:pressed {
    image: url(:/images/radiobutton_unchecked_pressed.png);
}

QRadioButton::indicator::checked {
    image: url(:/images/radiobutton_checked.png);
}

QRadioButton::indicator:checked:hover {
    image: url(:/images/radiobutton_checked_hover.png);
}

QRadioButton::indicator:checked:pressed {
    image: url(:/images/radiobutton_checked_pressed.png);
}

Personnalisation de QScrollBar

Le style de l'QScrollBar peut être défini à l'aide de ses sous-contrôles, tels que handle, add-line, sub-line, etc. Notez que si une propriété ou un sous-contrôle est personnalisé, toutes les autres propriétés ou sous-contrôles doivent également l'être.

Barre de défilement stylisée verte

La barre de défilement ci-dessus a été stylisée en couleur aigue-marine avec une bordure grise unie.

QScrollBar:horizontal {
    border: 2px solid grey;
    background: #32CC99;
    height: 15px;
    margin: 0px 20px 0 20px;
}
QScrollBar::handle:horizontal {
    background: white;
    min-width: 20px;
}
QScrollBar::add-line:horizontal {
    border: 2px solid grey;
    background: #32CC99;
    width: 20px;
    subcontrol-position: right;
    subcontrol-origin: margin;
}

QScrollBar::sub-line:horizontal {
    border: 2px solid grey;
    background: #32CC99;
    width: 20px;
    subcontrol-position: left;
    subcontrol-origin: margin;
}

Les flèches gauche et droite présentent une bordure grise unie sur fond blanc. Vous pouvez également intégrer l’image d’une flèche.

QScrollBar::left-arrow:horizontal, QScrollBar::right-arrow:horizontal {
    border: 2px solid grey;
    width: 3px;
    height: 3px;
    background: white;
}

QScrollBar::add-page:horizontal, QScrollBar::sub-page:horizontal {
    background: none;
}

Si vous souhaitez que les boutons de défilement de la barre de défilement soient placés côte à côte (plutôt qu’aux extrémités) comme sous macOS, vous pouvez utiliser la feuille de style suivante :

QScrollBar:horizontal {
    border: 2px solid green;
    background: cyan;
    height: 15px;
    margin: 0px 40px 0 0px;
}

QScrollBar::handle:horizontal {
    background: gray;
    min-width: 20px;
}

QScrollBar::add-line:horizontal {
    background: blue;
    width: 16px;
    subcontrol-position: right;
    subcontrol-origin: margin;
    border: 2px solid black;
}

QScrollBar::sub-line:horizontal {
    background: magenta;
    width: 16px;
    subcontrol-position: top right;
    subcontrol-origin: margin;
    border: 2px solid black;
    position: absolute;
    right: 20px;
}

QScrollBar::left-arrow:horizontal, QScrollBar::right-arrow:horizontal {
    width: 3px;
    height: 3px;
    background: pink;
}

QScrollBar::add-page:horizontal, QScrollBar::sub-page:horizontal {
    background: none;
}

La barre de défilement utilisant la feuille de style ci-dessus se présente comme suit :

Barre de défilement colorée

Pour personnaliser une barre de défilement verticale, utilisez une feuille de style similaire à celle-ci :

 QScrollBar:vertical {
     border: 2px solid grey;
     background: #32CC99;
     width: 15px;
     margin: 22px 0 22px 0;
 }
 QScrollBar::handle:vertical {
     background: white;
     min-height: 20px;
 }
 QScrollBar::add-line:vertical {
     border: 2px solid grey;
     background: #32CC99;
     height: 20px;
     subcontrol-position: bottom;
     subcontrol-origin: margin;
 }

 QScrollBar::sub-line:vertical {
     border: 2px solid grey;
     background: #32CC99;
     height: 20px;
     subcontrol-position: top;
     subcontrol-origin: margin;
 }
 QScrollBar::up-arrow:vertical, QScrollBar::down-arrow:vertical {
     border: 2px solid grey;
     width: 3px;
     height: 3px;
     background: white;
 }

 QScrollBar::add-page:vertical, QScrollBar::sub-page:vertical {
     background: none;
 }

Personnalisation de QSizeGrip

QSizeGrip se personnalise généralement en définissant simplement une image.

QSizeGrip {
    image: url(:/images/sizegrip.png);
    width: 16px;
    height: 16px;
}

Personnalisation de QSlider

Vous pouvez styliser un curseur horizontal comme ci-dessous :

QSlider::groove:horizontal {
    border: 1px solid #999999;
    height: 8px; /* the groove expands to the size of the slider by default. by giving it a height, it has a fixed size */
    background: qlineargradient(x1:0, y1:0, x2:0, y2:1, stop:0 #B1B1B1, stop:1 #c4c4c4);
    margin: 2px 0;
}

QSlider::handle:horizontal {
    background: qlineargradient(x1:0, y1:0, x2:1, y2:1, stop:0 #b4b4b4, stop:1 #8f8f8f);
    border: 1px solid #5c5c5c;
    width: 18px;
    margin: -2px 0; /* handle is placed by default on the contents rect of the groove. Expand outside the groove */
    border-radius: 3px;
}

Si vous souhaitez modifier la couleur des parties du curseur situées avant et après la poignée, vous pouvez utiliser les sous-contrôles « add-page » et « sub-page ». Par exemple, pour un curseur vertical :

QSlider::groove:vertical {
    background: red;
    position: absolute; /* absolutely position 4px from the left and right of the widget. setting margins on the widget should work too... */
    left: 4px; right: 4px;
}

QSlider::handle:vertical {
    height: 10px;
    background: green;
    margin: 0 -4px; /* expand outside the groove */
}

QSlider::add-page:vertical {
    background: white;
}

QSlider::sub-page:vertical {
    background: pink;
}

Personnalisation de QSpinBox

QSpinBox peut être entièrement personnalisé comme ci-dessous (la feuille de style comporte des commentaires en ligne) :

QSpinBox {
    padding-right: 15px; /* make room for the arrows */
    border-image: url(:/images/frame.png) 4;
    border-width: 3;
}

QSpinBox::up-button {
    subcontrol-origin: border;
    subcontrol-position: top right; /* position at the top right corner */

    width: 16px; /* 16 + 2*1px border-width = 15px padding + 3px parent border */
    border-image: url(:/images/spinup.png) 1;
    border-width: 1px;
}

QSpinBox::up-button:hover {
    border-image: url(:/images/spinup_hover.png) 1;
}

QSpinBox::up-button:pressed {
    border-image: url(:/images/spinup_pressed.png) 1;
}

QSpinBox::up-arrow {
    image: url(:/images/up_arrow.png);
    width: 7px;
    height: 7px;
}

QSpinBox::up-arrow:disabled, QSpinBox::up-arrow:off { /* off state when value is max */
   image: url(:/images/up_arrow_disabled.png);
}

QSpinBox::down-button {
    subcontrol-origin: border;
    subcontrol-position: bottom right; /* position at bottom right corner */

    width: 16px;
    border-image: url(:/images/spindown.png) 1;
    border-width: 1px;
    border-top-width: 0;
}

QSpinBox::down-button:hover {
    border-image: url(:/images/spindown_hover.png) 1;
}

QSpinBox::down-button:pressed {
    border-image: url(:/images/spindown_pressed.png) 1;
}

QSpinBox::down-arrow {
    image: url(:/images/down_arrow.png);
    width: 7px;
    height: 7px;
}

QSpinBox::down-arrow:disabled,
QSpinBox::down-arrow:off { /* off state when value in min */
   image: url(:/images/down_arrow_disabled.png);
}

Personnalisation de QSplitter

Un « QSplitter » dérive d’un « QFrame » et peut donc être stylisé comme un « QFrame ». La poignée est personnalisée à l’aide du sous-contrôle ::handle.

QSplitter::handle {
    image: url(images/splitter.png);
}

QSplitter::handle:horizontal {
    width: 2px;
}

QSplitter::handle:vertical {
    height: 2px;
}

QSplitter::handle:pressed {
    url(images/splitter_pressed.png);
}

Personnalisation de QStatusBar

On peut définir un arrière-plan pour la barre d'état et une bordure pour les éléments qu'elle contient comme suit :

QStatusBar {
    background: brown;
}

QStatusBar::item {
    border: 1px solid red;
    border-radius: 3px;
}

Notez que les widgets qui ont été ajoutés à l'QStatusBar peuvent être stylisés à l'aide de la déclaration de descendant (c'est-à-dire)

QStatusBar QLabel {
    border: 3px solid white;
}

Personnalisation de QTabWidget et QTabBar

Image représentant plusieurs onglets

Pour la capture d’écran ci-dessus, nous avons besoin d’une feuille de style comme suit :

QTabWidget::pane { /* The tab widget frame */
    border-top: 2px solid #C2C7CB;
}

QTabWidget::tab-bar {
    left: 5px; /* move to the right by 5px */
}

/* Style the tab using the tab sub-control. Note that
    it reads QTabBar _not_ QTabWidget */
QTabBar::tab {
    background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                stop: 0 #E1E1E1, stop: 0.4 #DDDDDD,
                                stop: 0.5 #D8D8D8, stop: 1.0 #D3D3D3);
    border: 2px solid #C4C4C3;
    border-bottom-color: #C2C7CB; /* same as the pane color */
    border-top-left-radius: 4px;
    border-top-right-radius: 4px;
    min-width: 8ex;
    padding: 2px;
}

QTabBar::tab:selected, QTabBar::tab:hover {
    background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                stop: 0 #fafafa, stop: 0.4 #f4f4f4,
                                stop: 0.5 #e7e7e7, stop: 1.0 #fafafa);
}

QTabBar::tab:selected {
    border-color: #9B9B9B;
    border-bottom-color: #C2C7CB; /* same as pane color */
}

QTabBar::tab:!selected {
    margin-top: 2px; /* make non-selected tabs look smaller */
}

Souvent, nous souhaitons que les onglets se chevauchent pour obtenir l’aspect illustré ci-dessous :

Image représentant des onglets superposés

Pour obtenir un widget d'onglet comme celui ci-dessus, nous utilisons des marges négatives. Les valeurs négatives rapprochent l'élément de ses voisins par rapport à la position par défaut. La feuille de style obtenue se présente ainsi :

QTabWidget::pane { /* The tab widget frame */
    border-top: 2px solid #C2C7CB;
}

QTabWidget::tab-bar {
    left: 5px; /* move to the right by 5px */
}

/* Style the tab using the tab sub-control. Note that
    it reads QTabBar _not_ QTabWidget */
QTabBar::tab {
    background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                stop: 0 #E1E1E1, stop: 0.4 #DDDDDD,
                                stop: 0.5 #D8D8D8, stop: 1.0 #D3D3D3);
    border: 2px solid #C4C4C3;
    border-bottom-color: #C2C7CB; /* same as the pane color */
    border-top-left-radius: 4px;
    border-top-right-radius: 4px;
    min-width: 8ex;
    padding: 2px;
}

QTabBar::tab:selected, QTabBar::tab:hover {
    background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                stop: 0 #fafafa, stop: 0.4 #f4f4f4,
                                stop: 0.5 #e7e7e7, stop: 1.0 #fafafa);
}

QTabBar::tab:selected {
    border-color: #9B9B9B;
    border-bottom-color: #C2C7CB; /* same as pane color */
}

QTabBar::tab:!selected {
    margin-top: 2px; /* make non-selected tabs look smaller */
}

/* make use of negative margins for overlapping tabs */
QTabBar::tab:selected {
    /* expand/overlap to the left and right by 4px */
    margin-left: -4px;
    margin-right: -4px;
}

QTabBar::tab:first:selected {
    margin-left: 0; /* the first selected tab has nothing to overlap with on the left */
}

QTabBar::tab:last:selected {
    margin-right: 0; /* the last selected tab has nothing to overlap with on the right */
}

QTabBar::tab:only-one {
    margin: 0; /* if there is only one tab, we don't want overlapping margins */
}

Pour centrer la barre d’onglets (comme ci-dessous), la feuille de style suivante est nécessaire :

Plusieurs onglets centrés dans le widget

QTabWidget::pane { /* The tab widget frame */
    border-top: 2px solid #C2C7CB;
    position: absolute;
    top: -0.5em;
}

QTabWidget::tab-bar {
    alignment: center;
}

/* Style the tab using the tab sub-control. Note that
    it reads QTabBar _not_ QTabWidget */
QTabBar::tab {
    background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                stop: 0 #E1E1E1, stop: 0.4 #DDDDDD,
                                stop: 0.5 #D8D8D8, stop: 1.0 #D3D3D3);
    border: 2px solid #C4C4C3;
    border-bottom-color: #C2C7CB; /* same as the pane color */
    border-top-left-radius: 4px;
    border-top-right-radius: 4px;
    min-width: 8ex;
    padding: 2px;
}

QTabBar::tab:selected, QTabBar::tab:hover {
    background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                stop: 0 #fafafa, stop: 0.4 #f4f4f4,
                                stop: 0.5 #e7e7e7, stop: 1.0 #fafafa);
}

QTabBar::tab:selected {
    border-color: #9B9B9B;
    border-bottom-color: #C2C7CB; /* same as pane color */
}

L'indicateur de défilement et les boutons de défilement peuvent être personnalisés comme suit :

QTabBar::tear {
    image: url(tear_indicator.png);
}

QTabBar::scroller { /* the width of the scroll buttons */
    width: 20px;
}

QTabBar QToolButton { /* the scroll buttons are tool buttons */
    border-image: url(scrollbutton.png) 2;
    border-width: 2px;
}

QTabBar QToolButton::right-arrow { /* the arrow mark in the tool buttons */
    image: url(rightarrow.png);
}

QTabBar QToolButton::left-arrow {
    image: url(leftarrow.png);
}

Vous pouvez personnaliser le bouton de fermeture comme suit :

QTabBar::close-button {
    image: url(close.png)
    subcontrol-position: left;
}
QTabBar::close-button:hover {
    image: url(close-hover.png)
}

Personnalisation de QTableView

Supposons que nous souhaitions que l'élément sélectionné dans l QTableView e ait pour arrière-plan une couleur rose bonbon s'estompant vers le blanc.

Affichage sous forme de tableau avec un style personnalisé

C'est possible grâce à la propriété ` selection-background-color `. La syntaxe à utiliser est la suivante :

QTableView {
    selection-background-color: qlineargradient(x1: 0, y1: 0, x2: 0.5, y2: 0.5,
                                stop: 0 #FF92BB, stop: 1 white);
}

Le widget d’angle peut être personnalisé à l’aide de la feuille de style suivante

QTableView QTableCornerButton::section {
    background: red;
    border: 2px outset red;
}

L'background-color ur de la case à cocher d'QTableView peut également être personnalisée. Dans l'extrait de code suivant, l' ur de l'indicateur à l'état non coché est personnalisée :

QTableView::indicator:unchecked {
    background-color: #d7d6d5
}

Personnalisation de QToolBar

L'arrière-plan et la poignée d'une QToolBar se personnalisent comme suit :

QToolBar {
    background: red;
    spacing: 3px; /* spacing between items in the tool bar */
}

QToolBar::handle {
    image: url(handle.png);
}

Personnalisation de QToolBox

Les onglets de la boîte à outils ( QToolBox ) sont personnalisés à l'aide du sous-contrôle « tab ».

QToolBox::tab {
    background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                stop: 0 #E1E1E1, stop: 0.4 #DDDDDD,
                                stop: 0.5 #D8D8D8, stop: 1.0 #D3D3D3);
    border-radius: 5px;
    color: darkgray;
}

QToolBox::tab:selected { /* italicize selected tabs */
    font: italic;
    color: white;
}

Personnalisation de QToolButton

Il existe trois types de QToolButtons.

QToolButton { /* all types of tool button */
    border: 2px solid #8f8f91;
    border-radius: 6px;
    background-color: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                      stop: 0 #f6f7fa, stop: 1 #dadbde);
}

QToolButton[popupMode="1"] { /* only for MenuButtonPopup */
    padding-right: 20px; /* make way for the popup button */
}

QToolButton:pressed {
    background-color: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1,
                                      stop: 0 #dadbde, stop: 1 #f6f7fa);
}

/* the subcontrols below are used only in the MenuButtonPopup mode */
QToolButton::menu-button {
    border: 2px solid gray;
    border-top-right-radius: 6px;
    border-bottom-right-radius: 6px;
    /* 16px width + 4px for border = 20px allocated above */
    width: 16px;
}

QToolButton::menu-arrow {
    image: url(downarrow.png);
}

QToolButton::menu-arrow:open {
    top: 1px; left: 1px; /* shift it a bit */
}

Personnalisation de QToolTip

QToolTip se personnalise exactement comme un « QLabel ». De plus, sur les plateformes qui le prennent en charge, la propriété « opacity » peut être définie pour ajuster l’opacité.

Par exemple,

QToolTip {
    border: 2px solid darkkhaki;
    padding: 5px;
    border-radius: 3px;
    opacity: 200;
}

Personnalisation de QTreeView

La couleur d’arrière-plan des lignes en alternance peut être personnalisée à l’aide de la feuille de style suivante :

QTreeView {
    alternate-background-color: yellow;
}

Pour créer un arrière-plan particulier lorsque l’on survole des éléments, on peut utiliser le sous-contrôle ::item. Par exemple,

QTreeView {
    show-decoration-selected: 1;
}

QTreeView::item {
     border: 1px solid #d9d9d9;
    border-top-color: transparent;
    border-bottom-color: transparent;
}

QTreeView::item:hover {
    background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #e7effd, stop: 1 #cbdaf1);
    border: 1px solid #bfcde4;
}

QTreeView::item:selected {
    border: 1px solid #567dbc;
}

QTreeView::item:selected:active{
    background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #6ea1f1, stop: 1 #567dbc);
}

QTreeView::item:selected:!active {
    background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #6b9be8, stop: 1 #577fbf);
}

Les branches d’un QTreeView sont stylisées à l’aide du sous-contrôle ::branch. La feuille de style suivante attribue des couleurs aux différents états lors du tracé d’une branche.

QTreeView::branch {
        background: palette(base);
}

QTreeView::branch:has-siblings:!adjoins-item {
        background: cyan;
}

QTreeView::branch:has-siblings:adjoins-item {
        background: red;
}

QTreeView::branch:!has-children:!has-siblings:adjoins-item {
        background: blue;
}

QTreeView::branch:closed:has-children:has-siblings {
        background: pink;
}

QTreeView::branch:has-children:!has-siblings:closed {
        background: gray;
}

QTreeView::branch:open:has-children:has-siblings {
        background: magenta;
}

QTreeView::branch:open:has-children:!has-siblings {
        background: green;
}

Bien que très colorée, cette illustration pourrait être complétée par un exemple plus concret à l'aide des images suivantes :

Ligne verticaleLigne de jonction pour les listesLigne marquant la fin de la listeFlèche pointant vers la droiteFlèche pointant vers le bas
vline.pngbranch-more.pngbranch-end.pngbranch-closed.pngbranch-open.png
QTreeView::branch:has-siblings:!adjoins-item {
    border-image: url(vline.png) 0;
}

QTreeView::branch:has-siblings:adjoins-item {
    border-image: url(branch-more.png) 0;
}

QTreeView::branch:!has-children:!has-siblings:adjoins-item {
    border-image: url(branch-end.png) 0;
}

QTreeView::branch:has-children:!has-siblings:closed,
QTreeView::branch:closed:has-children:has-siblings {
        border-image: none;
        image: url(branch-closed.png);
}

QTreeView::branch:open:has-children:!has-siblings,
QTreeView::branch:open:has-children:has-siblings  {
        border-image: none;
        image: url(branch-open.png);
}

L'arborescence obtenue se présente comme suit :

Arborescence avec des branches stylisées

Erreurs courantes

Cette section répertorie certaines erreurs courantes liées à l'utilisation des feuilles de style.

QPushButton et images

Lorsqu’on applique un style à un QPushButton, il est souvent souhaitable d’utiliser une image comme graphisme du bouton. On a souvent tendance à utiliser la propriété background-image, mais celle-ci présente plusieurs inconvénients : par exemple, l’arrière-plan apparaîtra souvent masqué derrière la décoration du bouton, car il n’est pas considéré comme un arrière-plan. De plus, si le bouton est redimensionné, l’arrière-plan entier sera étiré ou mis en mosaïque, ce qui n’est pas toujours esthétique.

Il est préférable d’utiliser la propriété `border-image`, car elle affiche toujours l’image, quel que soit l’arrière-plan (vous pouvez la combiner avec un arrière-plan s’il comporte des valeurs alpha), et elle dispose de paramètres spécifiques pour gérer le redimensionnement des boutons.

Considérez l'extrait de code suivant :

        QPushButton {
            color: grey;
            border-image: url(/home/kamlie/code/button.png) 3 10 3 10;
            border-top: 3px transparent;
            border-bottom: 3px transparent;
            border-right: 10px transparent;
            border-left: 10px transparent;
        }

Cela produira un bouton ressemblant à ceci :

Bouton avec un arrière-plan

Les chiffres après l’URL indiquent respectivement les valeurs en pixels pour le haut, la droite, le bas et la gauche. Ces valeurs correspondent à la bordure et ne doivent pas s’étirer lorsque la taille change. Chaque fois que vous redimensionnez le bouton, la partie centrale de l’image s’étire dans les deux sens, tandis que les pixels spécifiés dans la feuille de style restent fixes. Cela donne aux bordures du bouton un aspect plus naturel, comme ceci :

Bouton avec des dimensions de bordure définies

Avec des bordures

Bouton sans dimensions de bordure spécifiées

Sans bordures

Voir également «Approches de mise en forme pour Qt Widgets », « Sous-ensemble HTML pris en charge » et « QStyle ».

Référence des feuilles de style Gestion de la mise en page

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