Syntaxe de la feuille de style

La terminologie et les règles syntaxiques des feuilles de style Qt sont presque identiques à celles de HTML CSS. Si vous connaissez déjà le CSS, vous pouvez probablement parcourir rapidement cette section.

Règles de style

Les feuilles de style sont constituées d'une séquence de règles de style. Une règle de style se compose d'un sélecteur et d'une déclaration. Le sélecteur spécifie les widgets concernés par la règle ; la déclaration spécifie les propriétés à définir sur le widget. Voici un exemple de règle de style :

QPushButton { color: red }

Dans la règle de style ci-dessus, QPushButton est le sélecteur et { color: red } est la déclaration. La règle spécifie que QPushButton et ses sous-classes (par exemple, MyPushButton) doivent utiliser le rouge comme couleur d'avant-plan.

La feuille de style Qt XML est généralement insensible à la casse (c'est-à-dire que color, Color, COLOR et cOloR renvoient à la même propriété). Les seules exceptions sont les noms de classes, object names, et les noms de propriétés Qt, qui sont sensibles à la casse.

Plusieurs sélecteurs peuvent être spécifiés pour la même déclaration, en utilisant des virgules (,) pour séparer les sélecteurs. Par exemple, la règle

QPushButton, QLineEdit, QComboBox { color: red }

est équivalente à cette séquence de trois règles :

QPushButton { color: red }
QLineEdit { color: red }
QComboBox { color: red }

La partie déclaration d'une règle de style est une liste de paires property: value entourées d'accolades ({}) et séparées par des points-virgules. Par exemple :

QPushButton { color: red; background-color: white }

Voir la section Liste des propriétés ci-dessous pour la liste des propriétés fournies par les widgets Qt.

Types de sélecteurs

Tous les exemples présentés jusqu'à présent utilisaient le type de sélecteur le plus simple, le sélecteur de type. Les feuilles de style Qt prennent en charge tous les sélecteurs définis dans CSS2. Le tableau ci-dessous résume les types de sélecteurs les plus utiles.

Sous-contrôles

Pour styliser des widgets complexes, il est nécessaire d'accéder à des sous-contrôles du widget, tels que le bouton déroulant d'un QComboBox ou les flèches vers le haut et vers le bas d'un QSpinBox. Les sélecteurs peuvent contenir des sous-contrôles qui permettent de restreindre l'application d'une règle à des sous-contrôles spécifiques du widget. Par exemple :

QComboBox::drop-down { image: url(dropdown.png) }

La règle ci-dessus donne un style au bouton déroulant de tous les QComboBoxes. Bien que la syntaxe du double point-virgule (::) rappelle les pseudo-éléments CSS3, les sous-contrôles Qt diffèrent conceptuellement de ceux-ci et ont une sémantique de cascade différente.

Les sous-contrôles sont toujours positionnés par rapport à un autre élément - un élément de référence. Cet élément de référence peut être le widget ou un autre sous-contrôle. Par exemple, le ::drop-down d'un QComboBox est placé, par défaut, dans le coin supérieur droit du rectangle Padding du QComboBox. Le ::drop-down est placé, par défaut, au centre du rectangle Contents du sous-contrôle ::drop-down. Voir la liste des widgets stylisables ci-dessous pour connaître les sous-contrôles à utiliser pour styliser un widget et leur position par défaut.

Le rectangle d'origine à utiliser peut être modifié à l'aide de la propriété subcontrol-origin. Par exemple, si nous voulons placer la liste déroulante dans le rectangle de marge du site QComboBox au lieu du rectangle de remplissage par défaut, nous pouvons le spécifier :

QComboBox {
    margin-right: 20px;
}
QComboBox::drop-down {
    subcontrol-origin: margin;
}

L'alignement de la liste déroulante dans le rectangle de marge est modifié à l'aide de la propriété subcontrol-position.

Les propriétés width et height peuvent être utilisées pour contrôler la taille du sous-contrôle. Notez que la définition d'une image définit implicitement la taille d'un sous-contrôle.

Le schéma de positionnement relatif(position: relative) permet de décaler la position du sous-contrôle par rapport à sa position initiale. Par exemple, lorsque le bouton déroulant du site QComboBox est enfoncé, nous pourrions souhaiter que la flèche à l'intérieur soit décalée pour donner un effet "enfoncé". Pour ce faire, nous pouvons spécifier :

QComboBox::down-arrow {
    image: url(down_arrow.png);
}
QComboBox::down-arrow:pressed {
    position: relative;
    top: 1px; left: 1px;
}

Le schéma de positionnement absolu(position: absolute) permet de modifier la position et la taille du sous-contrôle par rapport à l'élément de référence.

Une fois positionnés, ils sont traités de la même manière que les widgets et peuvent être stylisés à l'aide du modèle de boîte.

Voir la liste des sous-contrôles ci-dessous pour une liste des sous-contrôles pris en charge, et Personnaliser le sous-contrôle de l'indicateur de menu de QPushButton pour un exemple réaliste.

Pseudo-États

Les sélecteurs peuvent contenir des pseudo-états qui restreignent l'application de la règle en fonction de l'état du widget. Les pseudo-états apparaissent à la fin du sélecteur, séparés par deux points (:). Par exemple, la règle suivante s'applique lorsque la souris survole un QPushButton:

QPushButton:hover { color: white }

Les pseudo-états peuvent être annulés à l'aide de l'opérateur d'exclamation. Par exemple, la règle suivante s'applique lorsque la souris ne survole pas QRadioButton:

QRadioButton:!hover { color: red }

Les pseudo-états peuvent être enchaînés, auquel cas un ET logique est impliqué. Par exemple, la règle suivante s'applique lorsque la souris survole une case cochée QCheckBox:

QCheckBox:hover:checked { color: white }

Les pseudo-états négatifs peuvent apparaître dans les chaînes de pseudo-états. Par exemple, la règle suivante s'applique lorsque la souris survole une touche QPushButton qui n'est pas enfoncée :

QPushButton:hover:!pressed { color: blue; }

Si nécessaire, le OU logique peut être exprimé à l'aide de l'opérateur virgule :

QCheckBox:hover, QCheckBox:checked { color: white }

Les pseudo-états peuvent apparaître en combinaison avec des sous-contrôles. Par exemple, les pseudo-états peuvent apparaître en combinaison avec des sous-contrôles :

QComboBox::drop-down:hover { image: url(dropdown_bright.png) }

Voir la section Liste des pseudo-états ci-dessous pour la liste des pseudo-états fournis par les widgets Qt.

Résolution des conflits

Les conflits surviennent lorsque plusieurs règles de style spécifient les mêmes propriétés avec des valeurs différentes. Considérons la feuille de style suivante :

QPushButton#okButton { color: gray }
QPushButton { color: red }

Les deux règles correspondent aux instances de QPushButton appelées okButton et il y a un conflit pour la propriété color. Pour résoudre ce conflit, nous devons tenir compte de la spécificité des sélecteurs. Dans l'exemple ci-dessus, QPushButton#okButton est considéré comme plus spécifique que QPushButton, car il fait (généralement) référence à un seul objet et non à toutes les instances d'une classe.

De même, les sélecteurs avec pseudo-états sont plus spécifiques que ceux qui ne spécifient pas de pseudo-états. Ainsi, la feuille de style suivante spécifie que le texte d'une page QPushButton doit être blanc lorsque la souris la survole, et rouge dans le cas contraire :

QPushButton:hover { color: white }
QPushButton { color: red }

Voici une question délicate :

QPushButton:hover { color: white }
QPushButton:enabled { color: red }

Ici, les deux sélecteurs ont la même spécificité, donc si la souris survole le bouton alors qu'il est activé, la deuxième règle est prioritaire. Si nous voulons que le texte soit blanc dans ce cas, nous pouvons réorganiser les règles comme suit :

QPushButton:enabled { color: red }
QPushButton:hover { color: white }

Nous pouvons également rendre la première règle plus spécifique :

QPushButton:hover:enabled { color: white }
QPushButton:enabled { color: red }

Un problème similaire se pose avec les sélecteurs de type. Prenons l'exemple suivant :

QPushButton { color: red }
QAbstractButton { color: gray }

Les deux règles s'appliquent aux instances de QPushButton (puisque QPushButton hérite de QAbstractButton) et il y a un conflit pour la propriété color. Étant donné que QPushButton hérite de QAbstractButton, il serait tentant de supposer que QPushButton est plus spécifique que QAbstractButton. Cependant, pour les calculs de feuille de style, tous les sélecteurs de type ont la même spécificité, et la règle qui apparaît en dernier a la priorité. En d'autres termes, la couleur est définie sur gray pour tous les sites QAbstractButton, y compris QPushButton. Si nous voulons vraiment que le texte du site QPushButtonsoit rouge, nous pouvons toujours réorganiser les règles.

Pour déterminer la spécificité d'une règle, les feuilles de style Qt suivent la spécification CSS2:

La spécificité d'un sélecteur est calculée comme suit :

• compter le nombre d'attributs ID dans le sélecteur (= a)
• compter le nombre d'autres attributs et pseudo-classes dans le sélecteur (= b)
• compter le nombre de noms d'éléments dans le sélecteur (= c)
• ignorer les pseudo-éléments [c'est-à-dire les sous-contrôles].

La concaténation des trois nombres a-b-c (dans un système numérique à grande base) donne la spécificité.

Quelques exemples :

*             {}  /* a=0 b=0 c=0 -> specificity =   0 */
LI            {}  /* a=0 b=0 c=1 -> specificity =   1 */
UL LI         {}  /* a=0 b=0 c=2 -> specificity =   2 */
UL OL+LI      {}  /* a=0 b=0 c=3 -> specificity =   3 */
H1 + *[REL=up]{}  /* a=0 b=1 c=1 -> specificity =  11 */
UL OL LI.red  {}  /* a=0 b=1 c=3 -> specificity =  13 */
LI.red.level  {}  /* a=0 b=2 c=1 -> specificity =  21 */
#x34y         {}  /* a=1 b=0 c=0 -> specificity = 100 */

Cascade

Les feuilles de style peuvent être définies sur le site QApplication, sur les widgets parents et sur les widgets enfants. La feuille de style effective d'un widget arbitraire est obtenue en fusionnant les feuilles de style définies sur les ancêtres du widget (parent, grand-parent, etc.), ainsi que toute feuille de style définie sur le site QApplication.

En cas de conflit, la propre feuille de style du widget est toujours préférée à toute feuille de style héritée, quelle que soit la spécificité des règles conflictuelles. De même, la feuille de style du widget parent est préférée à celle du widget grand-parent, etc.

L'une des conséquences est que la définition d'une règle de style sur un widget lui donne automatiquement la priorité sur d'autres règles spécifiées dans les feuilles de style des widgets ancêtres ou dans la feuille de style QApplication. Prenons l'exemple suivant. Tout d'abord, nous définissons une feuille de style sur le widget QApplication:

qApp->setStyleSheet("QPushButton { color: white }");

Ensuite, nous définissons une feuille de style sur un objet QPushButton:

myPushButton->setStyleSheet("* { color: blue }");

La feuille de style sur l'objet QPushButton oblige l'objet QPushButton (et tout widget enfant) à avoir un texte bleu, malgré les règles plus spécifiques fournies par la feuille de style de l'ensemble de l'application.

Le résultat aurait été le même si nous avions écrit

myPushButton->setStyleSheet("color: blue");

sauf que si le site QPushButton a des enfants (ce qui est peu probable), la feuille de style n'aura aucun impact sur eux.

La cascade de feuilles de style est un sujet complexe. Reportez-vous à la spécification CSS2 pour plus de détails. Sachez que Qt XML n'implémente pas !important.

Héritage

Dans le CSS classique, lorsque la police et la couleur d'un élément ne sont pas explicitement définies, elles sont automatiquement héritées du parent. Par défaut, lors de l'utilisation des feuilles de style Qt, un widget n' hérite pas automatiquement de la police et de la couleur de son widget parent.

Prenons l'exemple d'un QPushButton à l'intérieur d'un QGroupBox:

qApp->setStyleSheet("QGroupBox { color: red; } ");

Le QPushButton n'a pas de jeu de couleurs explicite. Par conséquent, au lieu d'hériter de la couleur de son parent QGroupBox, il a la couleur du système. Si nous voulons définir la couleur d'un QGroupBox et de ses enfants, nous pouvons écrire :

qApp->setStyleSheet("QGroupBox, QGroupBox * { color: red; }");

En revanche, la définition d'une police et d'une palette à l'aide de QWidget::setFont() et QWidget::setPalette() se propage aux widgets enfants.

Si vous préférez que la police et la palette se propagent aux widgets enfants, vous pouvez définir le drapeau Qt::AA_UseStyleSheetPropagationInWidgetStyles, comme suit :

Utilisation :

QCoreApplication::setAttribute(Qt::AA_UseStyleSheetPropagationInWidgetStyles, true);

Lorsque la propagation de la police et de la palette de style widget est activée, les changements de police et de palette effectués par le biais des feuilles de style Qt se comporteront comme si l'utilisateur avait appelé manuellement les méthodes QWidget::setPalette() et QWidget::setFont() correspondantes sur tous les QWidgets ciblés par la feuille de style.

• Les modifications apportées par une feuille de style sont propagées. Elles sont transmises à tous les widgets correspondant à la feuille de style une seule fois, au moment où la modification est apportée.
• Les modifications apportées en appelant QWidget::setPalette() ou QWidget::setFont() sont héritées. Elles sont héritées par tous les enfants existants et futurs, lorsque la brosse ou la police respective n'a pas été explicitement définie.

Widgets à l'intérieur des espaces de nommage C

Le sélecteur de type peut être utilisé pour styliser des widgets d'un type particulier. Par exemple, le sélecteur de type peut être utilisé pour styliser les widgets d'un type particulier,

classe MonBoutonPoussoir : public QPushButton{ // ...} ;// ...void someFunction(){
    qApp->setStyleSheet("MyPushButton { background: yellow; }");
   //...

La feuille de style Qt utilise QObject::className() du widget pour déterminer quand appliquer le sélecteur de type. Lorsque les widgets personnalisés se trouvent dans des espaces de noms, QObject::className() renvoie <namespace>::<classname>. Cela entre en conflit avec la syntaxe des sous-contrôles. Pour résoudre ce problème, lorsque vous utilisez le sélecteur de type pour des widgets situés dans des espaces de noms, vous devez remplacer :: par --. Par exemple,

namespace ns { class MyPushButton : public QPushButton{ // ...} ; }// ...void someMethod(){
    qApp->setStyleSheet("ns--MyPushButton { background: yellow; }");
   //...

Définition des propriétés de QObject

À partir de la version 4.3, il est possible de définir n'importe quelle propriété de Q_PROPERTY à l'aide de la syntaxe qproperty-<nom de la propriété>.

Par exemple,

MyLabel { qproperty-pixmap: url(pixmap.png); }
MyGroupBox { qproperty-titleColor: rgb(100, 200, 100); }
QPushButton { qproperty-iconSize: 20px 20px; }

Si la propriété fait référence à un enum déclaré avec Q_ENUM, vous devez faire référence à ses constantes par leur nom, et non par leur valeur numérique.