Home · All Classes · Main Classes · Grouped Classes · Modules · Functions

Qt Style Sheets

Qt Style Sheets are a powerful mechanism that allows you to customize the appearance of widgets, in addition to what is already possible by subclassing QStyle. The concepts, terminology, and syntax of Qt Style Sheets are heavily inspired by HTML Cascading Style Sheets (CSS) but adapted to the world of widgets.

Topics:

• Overview
• The Style Sheet Syntax
• Style Rules
• Selector Types
• Sub-Controls
• Pseudo-States
• Conflict Resolution
• Cascading
• Customizing Qt Widgets Using Style Sheets
• List of Stylable Widgets
• List of Attributes
• List of Attribute Types
• List of Pseudo-States
• List of Sub-Controls
• The Box Model
• Examples
• Customizing the Foreground and Background Colors
• Customizing a QPushButton Using the Box Model
• Customizing the QPushButton's Menu Indicator Sub-Control
• Complex Selector Example

Overview

Styles sheets are textual specifications that can be set on the whole application using QApplication::setStyleSheet() or on a specific widget (and its children) using QWidget::setStyleSheet(). If several style sheets are set at different levels, Qt derives the effective style sheet from all of those that are set. This is called cascading.

For example, the following style sheet specifies that all QLineEdits should use yellow as their background color, and all QCheckBoxes should use red as the text color:

 QLineEdit { background: yellow }
 QCheckBox { color: red }

For this kind of customization, style sheets are much more powerful than QPalette. For example, it might be tempting to set the QPalette::Button role to red for a QPushButton to obtain a red push button. However, this wasn't guaranteed to work for all styles, because style authors are restricted by the different platforms' guidelines and (on Windows XP and Mac OS X) by the native theme engine.

Style sheets let you perform all kinds of customizations that are difficult or impossible to perform using QPalette alone. If you want yellow backgrounds for mandatory fields, red text for potentially destructive push buttons, or fancy check boxes, style sheets are the answer.

Style sheets are applied on top of the current widget style, meaning that your applications will still look native, but any style sheet constraints will be taken into consideration. Unlike palette fiddling, style sheets offer guarantees: If you set the background color of a QPushButton to be red, you can be assured that the button will have a red background in all styles, on all platforms. Qt Designer provides style sheet integration, making it easy to view the effects of a style sheet in different widget styles.

In addition, style sheets can be used to provide a distinctive look and feel for your application, without having to subclass QStyle. For example, you can specify arbitrary images for radio buttons and check boxes to make them stand out. Using this technique, you can also achieve minor customizations that would normally require subclassing several style classes, such as specifying a style hint. The Style Sheet example depicted below defines two distinctive style sheets that you can try out and modify at will.

When a style sheet is active, the QStyle returned by QWidget::style() is a wrapper "style sheet" style, not the platform-specific style. The wrapper style ensures that any active style sheet is respected and otherwise forwards the drawing operations to the underlying, platform-specific style (e.g., QWindowsXPStyle on Windows XP).

Warning: Qt style sheets are currently not supported for QMacStyle (the default style on Mac OS X). We plan to address this in Qt 4.3.

The Style Sheet Syntax

Qt Style Sheet terminology and syntactic rules are almost identical to those of HTML CSS. If you already know CSS, you can probably skim quickly through this section.

Style Rules

Style sheets consist of a sequence of style rules. A style rule is made up of a selector and a declaration. The selector specifies which widgets are affected by the rule; the declaration specifies which attributes should be set on the widget. For example:

 QPushButton { color: red }

In the above style rule, QPushButton is the selector and { color: red } is the declaration. The rule specifies that QPushButton and its subclasses (e.g., MyPushButton) should use red as their foreground color.

Qt Style Sheet is generally case insensitive (i.e., color, Color, COLOR, and cOloR refer to the same attribute). The only exceptions are class names, object names, and Qt property names, which are case sensitive.

Several selectors can be specified for the same declaration, using commas (,) to separate the selectors. For example, the rule

 QPushButton, QLineEdit, QComboBox { color: red }

is equivalent to this sequence of three rules:

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

The declaration part of a style rule is a list of attribute: value pairs, enclosed in braces ({}) and separated with semicolons. For example:

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

See the List of Attributes section below for the list of attributes provided by Qt widgets.

Selector Types

All the examples so far used the simplest type of selector, the Type Selector. Qt Style Sheets support all the selectors defined in CSS2. The table below summarizes the most useful types of selectors.

Sub-Controls

For styling complex widgets, it is necessary to access sub-controls of the widget, such as the drop-down button of a QComboBox or the up and down arrows of a QSpinBox. Selectors may contain sub-controls that make it possible to restrict the application of a rule to specific widget sub-controls. For example:

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

The above rule styles the drop-down button of all QComboBoxes. Although the double-colon (::) syntax is reminiscent of CSS3 Pseudo-Elements, Qt Sub-Controls differ conceptually from these and have different cascading semantics.

When customizing a sub-control, we can either specify an image (using the image attribute) or set the width and weight attributes. Otherwise, they are treated the same as widgets and can be styled using the the box model.

See the List of Sub-Controls below for a list of supported sub-controls, and Customizing the QPushButton's Menu Indicator Sub-Control for a realistic example.

Pseudo-States

Selectors may contain pseudo-states that denote that restrict the application of the rule based on the widget's state. Pseudo-states appear at the end of the selector, with a colon (:) in between. For example, the following rule applies when the mouse hovers over a QPushButton:

 QPushButton:hover { color: white }

Pseudo-states can be chained, in which case a logical AND is implied. For example, the following rule applies to when the mouse hovers over a checked QCheckBox:

 QCheckBox:hover:checked { color: white }

If needed, logical OR can be expressed using the comma operator:

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

Pseudo-states can appear in combination with sub-controls. For example:

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

See the List of Pseudo-States section below for the list of pseudo-states provided by Qt widgets.

Conflict Resolution

Conflicts arise when several style rules specify the same attributes with different values. Consider the following style sheet:

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

Both rules match QPushButton instances called okButton and there is a conflict for the color attribute. To resolve this conflict, we must take into account the specificity of the selectors. In the above example, QPushButton#okButton is considered more specific than QPushButton, because it (usually) refers to a single object, not to all instances of a class.

Similarly, selectors with pseudo-states are more specific that ones that do not specify pseudo-states. Thus, the following style sheet specifies that a QPushButton should have white text when the mouse is hovering over it, otherwise red text:

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

Here's a tricky one:

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

Here, both selectors have the same specificity, so if the mouse hovers over the button while it is enabled, the second rule takes precedence. If we want the text to be white in that case, we can reorder the rules like this:

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

Alternatively, we can make the first rule more specific:

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

A similar issue arises in conjunction with Type Selectors. Consider the following example:

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

Both rules apply to QPushButton instances (since QPushButton inherits QAbstractButton) and there is a conflict for the color attribute. Because QPushButton inherits QAbstractButton, it might be tempting to assume that QPushButton is more specific than QAbstractButton. However, for style sheet computations, all Type Selectors have the same specificity, and the rule that appears last takes precedence. In other words, color is set to gray for all QAbstractButtons, including QPushButtons. If we really want QPushButtons to have red text, we can always reorder the rules.

For determining the specificity of a rule, Qt Style Sheets follow the CSS2 Specification:

A selector's specificity is calculated as follows:

• count the number of ID attributes in the selector (= a)
• count the number of other attributes and pseudo-classes in the selector (= b)
• count the number of element names in the selector (= c)
• ignore pseudo-elements [i.e., sub-controls].

Concatenating the three numbers a-b-c (in a number system with a large base) gives the specificity.

Some examples:

 *             {}  /* 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 */

Cascading

Style sheets can be set on the QApplication, on parent widgets, and on child widgets. An arbitrary widget's effective style sheet is obtained by merging the style sheets set on the widget's ancestors (parent, grandparent, etc.), as well as any style sheet set on the QApplication.

When conflicts arise, the widget's own style sheet is always preferred to any inherited style sheet, irrespective of the specificity of the conflicting rules. Likewise, the parent widget's style sheet is preferred to the grandparent's, etc.

One consequence of this is that setting a style rule on a widget automatically gives it precedence over other rules specified in the ancestor widgets' style sheets or the QApplication style sheet. Consider the following example. First, we set a style sheet on the QApplication:

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

Then we set a style sheet on a QPushButton object:

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

The style sheet on the QPushButton forces the QPushButton (and any child widget) to have blue text, in spite of the more specific rule set provided by the application-wide style sheet.

The result would have been the same if we had written

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

except that if the QPushButton had children (which is unlikely), the style sheet would have no impact on them.

Style sheet cascading is a complex topic. Refer to the CSS2 Specification for the gory details. Be aware that Qt currently doesn't implement !important.

Customizing Qt Widgets Using Style Sheets

Qt Style Sheets support various attributes, pseudo-states, and sub-controls that make it possible to customize the look of widgets.

List of Stylable Widgets

The following table lists the Qt widgets that can be customized using style sheets:

List of Attributes

The table below lists all the attributes supported by Qt Style Sheets. Which values can be given to an attribute depend on the attribute's type. Unless otherwise specified, attributes below apply to all widgets. Attributes marked with an asterisk (*) are specific to Qt and have no equivalent in CSS2 or CSS3.

 QTreeView {
     alternate-background: blue;
     background: yellow;
 }

 QTextEdit { background: yellow }

 QLabel { background-color: yellow }
 QLineEdit { background-color: rgb(255, 0, 0) }

 QFrame { background-image: url(:/images/hydro.png) }

 QFrame {
     background: white url(:/images/ring.png);
     background-repeat: repeat-y;
     background-position: left;
 }

 QFrame {
     background: url(:/images/footer.png);
     background-position: bottom left;
 }

 QFrame {
     background-image: url(:/images/header.png);
     background-position: top left;
     background-origin: content;
 }

 QLineEdit { border: 1px solid white }

 QLineEdit {
     border-width: 1px;
     border-style: solid;
     border-color: white;
 }

 QLineEdit {
     border-width: 1px;
     border-style: solid;
     border-radius: 4px;
 }

 QLineEdit {
     border-width: 1px;
     border-style: solid;
     border-color: blue;
 }

 QLineEdit {
     border-width: 2px;
     border-style: solid;
     border-color: darkblue;
 }

 QSpinBox::down-button { bottom: 2px }

 * { button-layout: 2px }

 QPushButton { color: red }

 * { etch-disabled-text: 1px }

 QCheckBox { font: bold italic large "Times New Roman" }

 QCheckBox { font-family: "New Century Schoolbook" }

 QTextEdit { font-size: 12px }

 QTextEdit { font-style: italic }

 * { gridline-color: gray }

 QSpinBox::down-button { height: 10px }

 QSpinBox::down-button { image: url(:/images/spindown.png) }

 QSpinBox::down-button { left: 2px }

 * { lineedit-password-character: 9679 }

 QLineEdit { margin: 2px }

 QMessageBox { messagebox-text-interaction-flags: 5 }

 QComboBox { min-height: 24px }

 QComboBox { min-width: 72px }

 QToolTip { opacity: 223 }

 QLineEdit { padding: 3px }

 QSpinBox::down-button { right: 2px }

 QTextEdit { selection-background-color: darkblue }

 QTextEdit { selection-color: white }

 * { show-decoration-selected: 1 }

 QMenuBar { spacing: 10 }

 QSpinBox::up-button {
     image: url(:/images/spinup.png);
     subcontrol-origin: content;
     subcontrol-position: right top;
 }

 QSpinBox::down-button {
     image: url(:/images/spindown.png);
     subcontrol-origin: padding;
     subcontrol-position: right bottom;
 }

 QSpinBox::up-button { top: 2px }

 QSpinBox::up-button { width: 12px }

List of Attribute Types

The following table summarizes the syntax and meaning of the different attribute types.

 QTextEdit { background-position: bottom center }

 QDialog { etch-disabled-text: 1 }

 QLabel { border-color: red }                    /* red red red red */
 QLabel { border-color: red blue }               /* red blue red blue */
 QLabel { border-color: red blue green }         /* red blue green blue */
 QLabel { border-color: red blue green yellow }  /* red blue green yellow */

 QLabel { border-width: 1px }                    /* 1px 1px 1px 1px */
 QLabel { border-width: 1px 2px }                /* 1px 2px 1px 2px */
 QLabel { border-width: 1px 2px 3px }            /* 1px 2px 3px 2px */
 QLabel { border-width: 1px 2px 3px 4px }        /* 1px 2px 3px 4px */

 QLabel { border-color: red }                    /* opaque red */
 QLabel { border-color: #FF0000 }                /* opaque red */
 QLabel { border-color: rgba(255, 0, 0, 75%) }   /* 75% transparent red */
 QLabel { border-color: rgb(255, 0, 0) }         /* opaque red */
 QLabel { border-color: rgb(100%, 0%, 0%) }      /* opaque red */

List of Pseudo-States

The following pseudo-states are supported:

List of Sub-Controls

The following sub-controls are available:

See Customizing the QPushButton's Menu Indicator Sub-Control for an example of how to customize a sub-control.

The Box Model

Widgets and sub-controls that support the background, border, margin, and padding attributes follow the box model. The image below illustrates how these attributes relate to each other:

• The margin falls outside the border.
• The border is drawn between the margin and the padding.
• The padding falls inside the border, between the border and the actual contents.
• The content is what is left from the original widget or sub-control once we have removed the margin, the border, and the padding.

The margin, border-width, and padding attributes all default to zero. In that case, all four rectangles (margin, border, padding, and content) coincide exactly.

If a background is specified for a widget, by default it is drawn only for the area inside the border. This can be changed using the background-origin attribute.

Examples

In this section, we will see examples of how to style widgets using style sheets. Qt Designer is an excellent tool to preview style sheets. Just right-click anywhere on the form you're designing and click Edit styleSheet.

Customizing the Foreground and Background Colors

Let's start by setting yellow as the background color of all QLineEdits in an application. This could be achieved like this:

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

If we want the attribute to apply only to the QLineEdits that are children (or grandchildren or grand-grandchildren) of a specific dialog, we would rather do this:

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

If we want the attribute to apply only to one specific QLineEdit, we can give it a name using QObject::setObjectName() and use an ID Selector to refer to it:

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

Alternatively, we can set the background-color attribute directly on the QLineEdit, omitting the selector:

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

To ensure a good contrast, we should also specify a suitable color for the text:

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

It might be a good idea to change the colors used for selected text as well:

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

There are many situations where we need to present a form that has mandatory fields. To indicate to the user that the field is mandatory, one effective (albeit esthetically dubious) solution is to use yellow as the background color for those fields. It turns out this is very easy to implement using Qt Style Sheets. First, we would use the following application-wide style sheet:

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

This means that every widget whose mandatoryField property is set to true would have a yellow background.

Then, for each mandatory field widget, we would simply create a mandatoryField property on the fly and set it to true. For example:

 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);

Customizing a QPushButton Using the Box Model

This time, we will show how to create a red QPushButton. This QPushButton would presumably be connected to a very destructive piece of code.

First, we are tempted to use this style sheet:

 QPushButton#evilButton { background-color: red }

However, the result is a boring, flat button with no borders:

What happened is this:

• We have made a request that cannot be satisfied using the native styles alone (e.g., the Windows XP theme engine doesn't let us specify the background color of a button).
• Therefore, the button is rendered using style sheets.
• We haven't specified any values for border-width and border-style, so by default we obtain a 0-pixel wide border of style none.

Let's improve the situation by specifying a border:

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

Things look already a lot better. But the button looks a bit cramped. Let's specify some spacing between the border and the text using the padding. Additionally, we will enforce a minimum width, round the corners, and specify a larger font to make the button look nicer:

 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;
 }

The only issue remaining is that the button doesn't react when we press it. We can fix this by specifying a slightly different background color and use a different border style.

 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;
 }

Customizing the QPushButton's Menu Indicator Sub-Control

Sub-controls give access to the sub-elements of a widget. For example, a QPushButton associated with a menu (using QPushButton::setMenu()) has a menu indicator. Let's customize the menu indicator for the red push button:

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

By default, the menu indicator is located at the bottom-right corner of the padding rectangle. We can change this by specifying subcontrol-position and subcontrol-origin to anchor the indicator differently. We can also use top and left to move the indicator by a few pixels. For example:

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

This positions the myindicator.png to the center right of the QPushButton's padding rectangle (see subcontrol-origin for more information).

Complex Selector Example

Since red seems to be our favorite color, let's make the text in QLineEdit red by setting the following application-wide stylesheet:

 QLineEdit { color: red }

However, we would like to give a visual indication that a QLineEdit is read-only by making it appear gray:

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

At some point, our design team comes with the requirement that all QLineEdits in the registration form (with the object name registrationDialog) to be brown:

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

A few UI design meetings later, we decide that all our QDialogs should have brown colored QLineEdits:

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

Quiz: What happens if we have a read-only QLineEdit in a QDialog? [Hint: The Conflict Resolution section above explains what happens in cases like this.]

See also Style Sheet Example, Supported HTML Subset, and QStyle.