1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the documentation of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*!

    43     \page stylesheet.html

    44     \title Qt Style Sheets

    45     \brief How to use style sheets to customize the appearance of widgets.

    46 

    47     \ingroup frameworks-technologies

    48 

    49     \previouspage {Implementing Styles and Style Aware Widgets}{Styles}

    50     \contentspage Widgets and Layouts

    51     \nextpage The Style Sheet Syntax

    52 

    53     \keyword style sheet

    54     \keyword stylesheet

    55 

    56     Qt Style Sheets are a powerful mechanism that allows you to

    57     customize the appearance of widgets, in addition to what is

    58     already possible by subclassing QStyle. The concepts,

    59     terminology, and syntax of Qt Style Sheets are heavily inspired

    60     by HTML \l{http://www.w3.org/Style/CSS/}{Cascading Style Sheets

    61     (CSS)} but adapted to the world of widgets.

    62 

    63     Topics:

    64 

    65     \list

    66     \i \l{Overview}

    67     \i \l{The Style Sheet Syntax}

    68     \i \l{Qt Designer Integration}

    69     \i \l{Customizing Qt Widgets Using Style Sheets}

    70     \i \l{Qt Style Sheets Reference}

    71     \i \l{Qt Style Sheets Examples}

    72     \endlist

    73 

    74     \target overview

    75     \section1 Overview

    76 

    77     Styles sheets are textual specifications that can be set on the

    78     whole application using QApplication::setStyleSheet() or on a

    79     specific widget (and its children) using

    80     QWidget::setStyleSheet(). If several style sheets are set at

    81     different levels, Qt derives the effective style sheet from all

    82     of those that are set. This is called cascading.

    83 

    84     For example, the following style sheet specifies that all

    85     \l{QLineEdit}s should use yellow as their background color, and

    86     all \l{QCheckBox}es should use red as the text color:

    87 

    88     \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 0

    89 

    90     For this kind of customization, style sheets are much more

    91     powerful than QPalette. For example, it might be tempting to set

    92     the QPalette::Button role to red for a QPushButton to obtain a

    93     red push button. However, this wasn't guaranteed to work for all

    94     styles, because style authors are restricted by the different

    95     platforms' guidelines and (on Windows XP and Mac OS X) by the

    96     native theme engine.

    97 

    98     Style sheets let you perform all kinds of customizations that are

    99     difficult or impossible to perform using QPalette alone. If you

   100     want yellow backgrounds for mandatory fields, red text for

   101     potentially destructive push buttons, or fancy check boxes, style

   102     sheets are the answer.

   103 

   104     Style sheets are applied on top of the current \l{QStyle}{widget

   105     style}, meaning that your applications will look as native as

   106     possible, but any style sheet constraints will be taken into

   107     consideration. Unlike palette fiddling, style sheets offer

   108     guarantees: If you set the background color of a QPushButton to be

   109     red, you can be assured that the button will have a red background

   110     in all styles, on all platforms. In addition, \l{Qt Designer}

   111     provides style sheet integration, making it easy to view the effects

   112     of a style sheet in different \l{QStyle}{widget styles}.

   113 

   114     In addition, style sheets can be used to provide a distinctive

   115     look and feel for your application, without having to subclass

   116     QStyle. For example, you can specify arbitrary images for radio

   117     buttons and check boxes to make them stand out. Using this

   118     technique, you can also achieve minor customizations that would

   119     normally require subclassing several style classes, such as

   120     specifying a \l{QStyle::styleHint()}{style hint}. The

   121     \l{widgets/stylesheet}{Style Sheet} example depicted below defines

   122     two distinctive style sheets that you can try out and modify at

   123     will.

   124 

   125     \table

   126     \row \o \inlineimage stylesheet-coffee-xp.png

   127          \o \inlineimage stylesheet-pagefold.png

   128     \row \o Coffee theme running on Windows XP

   129          \o Pagefold theme running on Windows XP

   130     \endtable

   131 

   132     \table

   133     \row \o \inlineimage stylesheet-coffee-cleanlooks.png

   134          \o \inlineimage stylesheet-pagefold-mac.png

   135     \row \o Coffee theme running on Ubuntu Linux

   136          \o Pagefold theme running on Mac OS X

   137     \endtable

   138 

   139     When a style sheet is active, the QStyle returned by QWidget::style()

   140     is a wrapper "style sheet" style, \e not the platform-specific style. The

   141     wrapper style ensures that any active style sheet is respected and

   142     otherwise forwards the drawing operations to the underlying,

   143     platform-specific style (e.g., QWindowsXPStyle on Windows XP).

   144 

   145     Since Qt 4.5, Qt style sheets fully supports Mac OS X.

   146 

   147     \warning Qt style sheets are currently not supported for custom QStyle

   148     subclasses. We plan to address this in some future release.

   149 */

   150 

   151 /*!

   152     \page stylesheet-syntax.html

   153     \contentspage {Qt Style Sheet}{Contents}

   154     \previouspage Qt Style Sheet

   155     \nextpage Qt Designer Integration

   156     \title The Style Sheet Syntax

   157 

   158     Qt Style Sheet terminology and syntactic rules are almost

   159     identical to those of HTML CSS. If you already know CSS, you can

   160     probably skim quickly through this section.

   161 

   162     \tableofcontents

   163 

   164     \section1 Style Rules

   165 

   166     Style sheets consist of a sequence of style rules. A \e{style

   167     rule} is made up of a selector and a declaration. The

   168     \e{selector} specifies which widgets are affected by the rule;

   169     the \e{declaration} specifies which properties should be set on

   170     the widget. For example:

   171 

   172     \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 1

   173 

   174     In the above style rule, \c QPushButton is the selector and \c{{

   175     color: red }} is the declaration. The rule specifies that

   176     QPushButton and its subclasses (e.g., \c MyPushButton) should use

   177     red as their foreground color.

   178 

   179     Qt Style Sheet is generally case insensitive (i.e., \c color,

   180     \c Color, \c COLOR, and \c cOloR refer to the same property).

   181     The only exceptions are class names,

   182     \l{QObject::setObjectName()}{object names}, and Qt property

   183     names, which are case sensitive.

   184 

   185     Several selectors can be specified for the same declaration,

   186     using commas (\c{,}) to separate the selectors. For example,

   187     the rule

   188 

   189     \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 2

   190 

   191     is equivalent to this sequence of three rules:

   192 

   193     \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 3

   194 

   195     The declaration part of a style rule is a list of

   196     \tt{\e{property}: \e{value}} pairs, enclosed in braces (\c{{}})

   197     and separated with semicolons. For example:

   198 

   199     \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 4

   200 

   201     See the \l{List of Properties} section below for the list of

   202     properties provided by Qt widgets.

   203 

   204     \section1 Selector Types

   205 

   206     All the examples so far used the simplest type of selector, the

   207     Type Selector. Qt Style Sheets support all the

   208     \l{http://www.w3.org/TR/REC-CSS2/selector.html#q1}{selectors

   209     defined in CSS2}. The table below summarizes the most useful

   210     types of selectors.

   211 

   212     \table 100%

   213     \header

   214         \o Selector

   215         \o Example

   216         \o Explanation

   217 

   218     \row

   219         \o Universal Selector

   220         \o \c *

   221         \o Matches all widgets.

   222 

   223     \row

   224         \o Type Selector

   225         \o \c QPushButton

   226         \o Matches instances of QPushButton and of its subclasses.

   227 

   228     \row

   229         \o Property Selector

   230         \o \c{QPushButton[flat="false"]}

   231         \o Matches instances of QPushButton that are not

   232            \l{QPushButton::}{flat}. You may use this selector to test

   233            for any Qt \l{Qt's Property System}{property} that supports

   234            QVariant::toString() (see the \l{QVariant::}{toString()}

   235            function documentation for details). In addition, the

   236            special \c class property is supported, for the name of the

   237            class.

   238 

   239            This selector may also be used to test dynamic properties.

   240            For more information on customization using dynamic properties,

   241            refer to \l{Customizing Using Dynamic Properties}.

   242 

   243            Instead of \c =, you can also use \c ~= to test whether a

   244            Qt property of type QStringList contains a given QString.

   245 

   246            \warning If the value of the Qt property changes after the

   247            style sheet has been set, it might be necessary to force a

   248            style sheet recomputation. One way to achieve this is to

   249            unset the style sheet and set it again.

   250 

   251     \row

   252         \o Class Selector

   253         \o \c .QPushButton

   254         \o Matches instances of QPushButton, but not of its subclasses.

   255 

   256            This is equivalent to \c{*[class~="QPushButton"]}.

   257 

   258     \row

   259         \o ID \target ID Selector

   260            Selector

   261         \o \c{QPushButton#okButton}

   262         \o Matches all QPushButton instances whose

   263            \l{QObject::objectName}{object name} is \c okButton.

   264 

   265     \row

   266         \o Descendant Selector

   267         \o \c{QDialog QPushButton}

   268         \o Matches all instances of QPushButton that are descendants

   269            (children, grandchildren, etc.) of a QDialog.

   270 

   271     \row

   272         \o Child Selector

   273         \o \c{QDialog > QPushButton}

   274         \o Matches all instances of QPushButton that are direct

   275            children of a QDialog.

   276     \endtable

   277 

   278     \section1 Sub-Controls

   279 

   280     For styling complex widgets, it is necessary to access subcontrols of the

   281     widget, such as the drop-down button of a QComboBox or the up and down

   282     arrows of a QSpinBox. Selectors may contain \e{subcontrols} that make it

   283     possible to restrict the application of a rule to specific widget

   284     subcontrols. For example:

   285 

   286     \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 5

   287 

   288     The above rule styles the drop-down button of all \l{QComboBox}es.

   289     Although the double-colon (\c{::}) syntax is reminiscent of CSS3

   290     Pseudo-Elements, Qt Sub-Controls differ conceptually from these and have

   291     different cascading semantics.

   292 

   293     Sub-controls are always positioned with respect to another element - a

   294     reference element. This reference element could be the widget or another

   295     Sub-control. For example, the \l{Qt Style Sheets Reference#drop-down-sub}

   296     {::drop-down} of a QComboBox is placed, by default, in the top right corner

   297     of the Padding rectangle of the QComboBox. The

   298     \l{Qt Style Sheets Reference#drop-down-sub}{::drop-down} is placed,

   299     by default, in the Center of the Contents rectangle of the

   300     \l{Qt Style Sheets Reference#drop-down-sub}{::drop-down} Sub-control. See

   301     the \l{List of Stylable Widgets} below for the Sub-controls to use to

   302     style a widget and their default positions.

   303 

   304     The origin rectangle to be used can be changed using the

   305     \l{Qt Style Sheets Reference#subcontrol-origin-prop}{subcontrol-origin}

   306     property. For example, if we want to place the drop-down in the margin

   307     rectangle of the QComboBox instead of the default Padding rectangle, we

   308     can specify:

   309 

   310     \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 6

   311 

   312     The alignment of the drop-down within the Margin rectangle is changed

   313     using \l{Qt Style Sheets Reference#subcontrol-position-prop}

   314     {subcontrol-position} property.

   315 

   316     The \l{Qt Style Sheets Reference#width-prop}{width} and

   317     \l{Qt Style Sheets Reference#height-prop}{height} properties can be used

   318     to control the size of the Sub-control. Note that setting a

   319     \l{Qt Style Sheets Reference#image-prop}{image} implicitly sets the size

   320     of a Sub-control.

   321 

   322     The relative positioning scheme

   323     (\l{Qt Style Sheets Reference#position-prop}{position} : relative),

   324     allows the position of the Sub-Control to be offset from its initial

   325     position. For example, when the QComboBox's drop-down button is

   326     pressed, we might like the arrow inside to be offset to give a

   327     "pressed" effect. To achieve this, we can specify:

   328 

   329     \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 7

   330 

   331     The absolute positioning scheme

   332     (\l{Qt Style Sheets Reference#position-prop}{position} : absolute),

   333     allows the position and size of the Sub-control to be changed with

   334     respect to the reference element.

   335 

   336     Once positioned, they are treated the same as widgets and can be styled

   337     using the \l{box model}.

   338 

   339     See the \l{List of Sub-Controls} below for a list of supported

   340     sub-controls, and \l{Customizing the QPushButton's Menu Indicator

   341     Sub-Control} for a realistic example.

   342 

   343     \note With complex widgets such as QComboBox and QScrollBar, if one

   344     property or sub-control is customized, \bold{all} the other properties or

   345     sub-controls must be customized as well.

   346 

   347     \section1 Pseudo-States

   348 

   349     Selectors may contain \e{pseudo-states} that denote that restrict

   350     the application of the rule based on the widget's state.

   351     Pseudo-states appear at the end of the selector, with a colon

   352     (\c{:}) in between. For example, the following rule applies when

   353     the mouse hovers over a QPushButton:

   354 

   355     \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 8

   356 

   357     Pseudo-states can be negated using the exclamation operator. For

   358     example, the following rule applies when the mouse does not hover

   359     over a QRadioButton:

   360 

   361     \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 9

   362 

   363     Pseudo-states can be chained, in which case a logical AND is

   364     implied. For example, the following rule applies to when the

   365     mouse hovers over a checked QCheckBox:

   366 

   367     \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 10

   368 

   369     Negated Pseudo-states may appear in Pseudo-state chains. For example,

   370     the following rule applies when the mouse hovers over a QPushButton

   371     that is not pressed:

   372 

   373     \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 11

   374 

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

   376 

   377     \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 12

   378 

   379     Pseudo-states can appear in combination with subcontrols. For

   380     example:

   381 

   382     \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 13

   383 

   384     See the \l{List of Pseudo-States} section below for the list of

   385     pseudo-states provided by Qt widgets.

   386 

   387     \section1 Conflict Resolution

   388 

   389     Conflicts arise when several style rules specify the same

   390     properties with different values. Consider the following style

   391     sheet:

   392 

   393     \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 14

   394 

   395     Both rules match QPushButton instances called \c okButton and

   396     there is a conflict for the \c color property. To resolve this

   397     conflict, we must take into account the \e specificity of the

   398     selectors. In the above example, \c{QPushButton#okButton} is

   399     considered more specific than \c QPushButton, because it

   400     (usually) refers to a single object, not to all instances of a

   401     class.

   402 

   403     Similarly, selectors with pseudo-states are more specific than

   404     ones that do not specify pseudo-states. Thus, the following style

   405     sheet specifies that a \l{QPushButton} should have white text

   406     when the mouse is hovering over it, otherwise red text:

   407 

   408     \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 15

   409 

   410     Here's a tricky one:

   411 

   412     \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 16

   413 

   414     Here, both selectors have the same specificity, so if the mouse

   415     hovers over the button while it is enabled, the second rule takes

   416     precedence. If we want the text to be white in that case, we can

   417     reorder the rules like this:

   418 

   419     \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 17

   420 

   421     Alternatively, we can make the first rule more specific:

   422 

   423     \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 18

   424 

   425     A similar issue arises in conjunction with Type Selectors.

   426     Consider the following example:

   427 

   428     \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 19

   429 

   430     Both rules apply to QPushButton instances (since QPushButton

   431     inherits QAbstractButton) and there is a conflict for the

   432     \l{Qt Style Sheets Reference#color-prop}{color} property. Because QPushButton

   433     inherits QAbstractButton, it might be tempting to assume that

   434     \c QPushButton is more specific than \c QAbstractButton. However,

   435     for style sheet computations, all Type Selectors have the same

   436     specificity, and the rule that appears last takes precedence. In

   437     other words, \l{Qt Style Sheets Reference#color-prop}{color} is set to \c gray

   438     for all \l{QAbstractButton}s, including \l{QPushButton}s. If we really

   439     want \l{QPushButton}s to have red text, we can always reorder the

   440     rules.

   441 

   442     For determining the specificity of a rule, Qt Style Sheets follow

   443     the

   444     \l{http://www.w3.org/TR/REC-CSS2/cascade.html#specificity}{CSS2

   445     Specification}:

   446 

   447     \quotation

   448     \e{A selector's specificity is calculated as follows:}

   449 

   450     \list

   451     \o \e{count the number of ID attributes in the selector (= a)}

   452     \o \e{count the number of other attributes and pseudo-classes in the selector (= b)}

   453     \o \e{count the number of element names in the selector (= c)}

   454     \o \e{ignore pseudo-elements [i.e., \l{subcontrols}].}

   455     \endlist

   456 

   457     \e{Concatenating the three numbers a-b-c (in a number system with a

   458     large base) gives the specificity.}

   459 

   460     \e{Some examples:}

   461 

   462     \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 20

   463     \endquotation

   464 

   465     \section1 Cascading

   466 

   467     Style sheets can be set on the QApplication, on parent widgets,

   468     and on child widgets. An arbitrary widget's effective style sheet

   469     is obtained by merging the style sheets set on the widget's

   470     ancestors (parent, grandparent, etc.), as well as any style sheet

   471     set on the QApplication.

   472 

   473     When conflicts arise, the widget's own style sheet is always

   474     preferred to any inherited style sheet, irrespective of the

   475     specificity of the conflicting rules. Likewise, the parent

   476     widget's style sheet is preferred to the grandparent's, etc.

   477 

   478     One consequence of this is that setting a style rule on a widget

   479     automatically gives it precedence over other rules specified in

   480     the ancestor widgets' style sheets or the QApplication style

   481     sheet. Consider the following example. First, we set a style

   482     sheet on the QApplication:

   483 

   484     \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 21

   485 

   486     Then we set a style sheet on a QPushButton object:

   487 

   488     \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 22

   489 

   490     The style sheet on the QPushButton forces the QPushButton (and

   491     any child widget) to have blue text, in spite of the more

   492     specific rule set provided by the application-wide style sheet.

   493 

   494     The result would have been the same if we had written

   495 

   496     \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 23

   497 

   498     except that if the QPushButton had children (which is unlikely),

   499     the style sheet would have no impact on them.

   500 

   501     Style sheet cascading is a complex topic. Refer to the

   502     \l{http://www.w3.org/TR/CSS2/cascade.html#cascade}{CSS2

   503     Specification} for the gory details. Be aware that Qt currently

   504     doesn't implement \c{!important}.

   505 

   506     \section1 Inheritance

   507 

   508     In classic CSS, when font and color of an item is not explicitly set,

   509     it gets automatically inherited from the parent. When using Qt Style Sheets,

   510     a widget does \bold{not} automatically inherit its font and color setting

   511     from its parent widget.

   512 

   513     For example, consider a QPushButton inside a QGroupBox:

   514 

   515     \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 24

   516 

   517     The QPushButton does not have an explicit color set. Hence, instead

   518     of inheriting color of its parent QGroupBox, it has the system color.

   519     If we want to set the color on a QGroupBox and its children,

   520     we can write:

   521 

   522     \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 25

   523 

   524     In contrast, setting a font and propagate using QWidget::setFont() and

   525     QWidget::setPalette() propagates to child widgets.

   526 

   527     \section1 Widgets inside C++ namespaces

   528 

   529     The Type Selector can be used to style widgets of a particular type. For

   530     example,

   531 

   532     \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 26

   533 

   534     Qt Style Sheet uses QObject::className() of the widget to determine

   535     when to apply the Type Selector. When custom widgets are inside namespaces,

   536     the QObject::className() returns <namespace>::<classname>. This conflicts

   537     with the syntax for \l{Sub-Controls}. To overcome this problem,

   538     when using the Type Selector for widgets inside namespaces, we must

   539     replace the "::" with "--". For example,

   540 

   541     \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 27

   542 

   543     \section1 Setting QObject properties

   544 

   545     From 4.3 and above, any designable Q_PROPERTY

   546     can be set using the qproperty-<property name> syntax.

   547 

   548     For example,

   549     \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 28

   550 

   551     If the property references an enum declared with Q_ENUMS, you should

   552     reference its constants by name, i.e., not their numeric value.

   553 

   554 */

   555 

   556 /*!

   557     \page stylesheet-designer.html

   558     \contentspage {Qt Style Sheet}{Contents}

   559     \previouspage The Style Sheet Syntax

   560     \nextpage Customizing Qt Widgets Using Style Sheets

   561     \title Qt Designer Integration

   562 

   563     \l{Qt Designer}{Qt Designer} is an excellent tool

   564     to preview style sheets. You can right-click on any widget in Designer

   565     and select \gui{Change styleSheet...} to set the style sheet.

   566 

   567     \image designer-stylesheet-options.png

   568 

   569     In Qt 4.2 and later, \l{Qt Designer}{Qt Designer} also includes a

   570     style sheet syntax highlighter and validator. The validator indicates

   571     if the syntax is valid or invalid, at the bottom left of the \gui{Edit

   572     Style Sheet} dialog.

   573 

   574     \image designer-validator-highlighter.png

   575 

   576     When you click \gui{OK} or \gui{Apply}, \QD will automatically display

   577     the widget with its new stylesheet.

   578 

   579     \image designer-stylesheet-usage.png

   580     */

   581 

   582 /*!

   583     \page stylesheet-customizing.html

   584     \contentspage {Qt Style Sheet}{Contents}

   585     \previouspage Qt Designer Integration

   586     \nextpage Qt Style Sheets Reference

   587     \title Customizing Qt Widgets Using Style Sheets

   588 

   589     When using style sheets, every widget is treated as a box with four

   590     concentric rectangles: the margin rectangle, the border rectangle, the

   591     padding rectangle, and the content rectangle. The box model describes

   592     this in further detail.

   593 

   594     \tableofcontents

   595 

   596     \target box model

   597     \section1 The Box Model

   598 

   599     The four concentric rectangles appear conceptually as below:

   600 

   601     \image stylesheet-boxmodel.png

   602 

   603     \list

   604     \o The margin falls outside the border.

   605     \o The border is drawn between the margin and the padding.

   606     \o The padding falls inside the border, between the border and

   607        the actual contents.

   608     \o The content is what is left from the original widget or

   609        subcontrol once we have removed the margin, the border, and

   610        the padding.

   611     \endlist

   612 

   613     The \l{Qt Style Sheets Reference#margin-prop}{margin},

   614     \l{Qt Style Sheets Reference#border-width-prop}

   615     {border-width}, and

   616     \l{Qt Style Sheets Reference#padding-prop}{padding}

   617     properties all default to zero. In that case, all four rectangles

   618     (\c margin, \c border, \c padding, and \c content) coincide exactly.

   619 

   620     You can specify a background for the widget using the

   621     \l{Qt Style Sheets Reference#background-image-prop}{background-image}

   622     property. By default, the background-image is drawn only for the area

   623     inside the border. This can be changed using the

   624     \l{Qt Style Sheets Reference#background-clip-prop}{background-clip}

   625     property. You can use

   626     \l{Qt Style Sheets Reference#background-repeat-prop}{background-repeat}

   627     and

   628     \l{Qt Style Sheets Reference#background-origin-prop}{background-origin}

   629     to control the repetition and origin of the background image.

   630 

   631     A background-image does not scale with the size of the widget. To provide

   632     a "skin" or background that scales along with the widget size, one must

   633     use

   634     \l{Qt Style Sheets Reference#border-image-prop}{border-image}. Since the

   635     border-image property provides an alternate background, it is not required

   636     to specify a background-image when border-image is specified. In the case,

   637     when both of them are specified, the border-image draws over the

   638     background-image.

   639 

   640     In addition, the \l{Qt Style Sheets Reference#image-prop}{image} property

   641     may be used to draw an image over the border-image. The image specified does

   642     not tile or stretch and when its size does not match the size of the widget,

   643     its alignment is specified using the

   644     \l{Qt Style Sheets Reference#image-position-prop}{image-position}

   645     property. Unlike background-image and border-image, one may specify a

   646     SVG in the image property, in which case the image is scaled automatically

   647     according to the widget size.

   648 

   649     The steps to render a rule are as follows:

   650         \list

   651         \o Set clip for entire rendering operation (border-radius)

   652         \o Draw the background (background-image)

   653         \o Draw the border (border-image, border)

   654         \o Draw overlay image (image)

   655         \endlist

   656 

   657     \target sub controls

   658     \section1 Sub-controls

   659 

   660     A widget is considered as a hierarchy (tree) of subcontrols drawn on top

   661     of each other. For example, the QComboBox draws the drop-down sub-control

   662     followed by the down-arrow sub-control. A QComboBox is thus rendered as

   663     follows:

   664         \list

   665         \o Render the QComboBox { } rule

   666         \o Render the QComboBox::drop-down { } rule

   667         \o Render the QComboBox::down-arrow { } rule

   668         \endlist

   669 

   670     Sub-controls share a parent-child relationship. In the case of QComboBox,

   671     the parent of down-arrow is the drop-down and the parent of drop-down is

   672     the widget itself. Sub-controls are positioned within their parent using

   673     the \l{Qt Style Sheets Reference#subcontrol-position-prop}

   674     {subcontrol-position} and

   675     \l{Qt Style Sheets Reference#subcontrol-origin-prop}{subcontrol-origin}

   676     properties.

   677 

   678     Once positioned, sub-controls can be styled using the \l{box model}.

   679 

   680     \note With complex widgets such as QComboBox and QScrollBar, if one

   681     property or sub-control is customized, \bold{all} the other properties or

   682     sub-controls must be customized as well.

   683 

   684 */

   685 

   686 /*!

   687     \page stylesheet-reference.html

   688     \contentspage {Qt Style Sheet}{Contents}

   689     \previouspage Customizing Qt Widgets Using Style Sheets

   690     \nextpage Qt Style Sheets Examples

   691     \title Qt Style Sheets Reference

   692 

   693     Qt Style Sheets support various properties, pseudo-states, and

   694     subcontrols that make it possible to customize the look of

   695     widgets.

   696 

   697     \tableofcontents

   698 

   699     \section1 List of Stylable Widgets

   700 

   701     The following table lists the Qt widgets that can be customized

   702     using style sheets:

   703 

   704     \table 100%

   705     \header

   706         \o Widget

   707         \o How to Style

   708 

   709     \row

   710         \o QAbstractScrollArea \target qabstractscrollarea-widget

   711         \o Supports the \l{box model}.

   712 

   713            All derivatives of QAbstractScrollArea, including QTextEdit,

   714            and QAbstractItemView (all item view classes), support

   715            scrollable backgrounds using

   716            \l{Qt Style Sheets Reference#background-attachment-prop}

   717            {background-attachment}. Setting the background-attachment to

   718            \c{fixed} provides a background-image that does not scroll with the

   719            viewport. Setting the background-attachment to \c{scroll}, scrolls

   720            the background-image when the scroll bars move.

   721 

   722            See \l{Qt Style Sheets Examples#Customizing QAbstractScrollArea}

   723            {Customizing QAbstractScrollArea} for an example.

   724 

   725     \row

   726         \o QCheckBox \target qcheckbox-widget

   727         \o Supports the \l{box model}. The check indicator can be

   728            styled using the \l{#indicator-sub}{::indicator}

   729            subcontrol. By default, the indicator is placed in the Top

   730            Left corner of the Contents rectangle of the widget.

   731 

   732            The \l{#spacing-prop}{spacing} property

   733            specifies the spacing between the check indicator and

   734            the text.

   735 

   736            See \l{Qt Style Sheets Examples#Customizing QCheckBox}

   737            {Customizing QCheckBox} for an example.

   738 

   739     \row

   740         \o QColumnView \target qcolumnview-widget

   741         \o The grip can be styled be using the \l{image-prop}{image} property.

   742            The arrow indicators can by styled using the

   743            \l{left-arrow-sub}{::left-arrow} subcontrol and the

   744            \l{right-arrow-sub}{::right-arrow} subcontrol.

   745 

   746     \row

   747         \o QComboBox \target qcombobox-widget

   748         \o The frame around the combobox can be styled using the

   749            \l{box model}. The drop-down button can be styled using

   750            the \l{#drop-down-sub}{::drop-down} subcontrol. By default, the

   751            drop-down button is placed in the top right corner of the padding

   752            rectangle of the widget. The arrow mark inside the drop-down button

   753            can be styled using the \l{#down-arrow-sub}{::down-arrow}

   754            subcontrol. By default, the arrow is placed in the center of the

   755            contents rectangle of the drop-down subcontrol.

   756 

   757            See \l{Qt Style Sheets Examples#Customizing QComboBox}{Customizing QComboBox}

   758            for an example.

   759 

   760     \row

   761         \o QDateEdit \target qdateedit-widget

   762         \o See \l{#qspinbox-widget}{QSpinBox}.

   763 

   764     \row

   765         \o QDateTimeEdit \target qdatetimeedit-widget

   766         \o See \l{#qspinbox-widget}{QSpinBox}.

   767 

   768     \row

   769         \o QDialog \target qdialog-widget

   770         \o Supports only the \l{Qt Style Sheets Reference#background-prop}{background},

   771            \l{#background-clip-prop}{background-clip} and

   772            \l{#background-origin-prop}{background-origin} properties.

   773 

   774            \warning Make sure you define the Q_OBJECT macro for your custom

   775            widget.

   776 

   777     \row

   778         \o QDialogButtonBox \target qdialogbuttonbox-widget

   779         \o The layout of buttons can be altered using the

   780            \l{#button-layout-prop}{button-layout} property.

   781 

   782     \row

   783         \o QDockWidget \target qdockwidget-widget

   784         \o Supports styling of the title bar and the title bar buttons when docked.

   785 

   786         The dock widget border can be styled using the \l{#border-prop}{border}

   787         property. The \l{#title-sub}{::title} subcontrol can be used to customize

   788         the title bar. The close and float buttons are positioned with respect

   789         to the \l{title-sub}{::title} subcontrol using the

   790         \l{#close-button-sub}{::close-button} and

   791         \l{#float-button-sub}{::float-button} respectively.

   792 

   793         When the title bar is vertical, the \l{#vertical-ps}{:vertical} pseudo

   794         class is set. In addition, depending on QDockWidget::DockWidgetFeature,

   795         the \l{#closable-ps}{:closable}, \l{#floatable-ps}{:floatable} and

   796         \l{#movable-ps}{:movable} pseudo states are set.

   797 

   798         \note Use QMainWindow::separator to style the resize handle.

   799 

   800         \warning The style sheet has no effect when the QDockWidget is undocked

   801         as Qt uses native top level windows when undocked.

   802 

   803         See \l{Qt Style Sheets Examples#Customizing QDockWidget}

   804         {Customizing QDockWidget} for an example.

   805 

   806     \row

   807         \o QDoubleSpinBox \target qdoublespinbox-widget

   808         \o See \l{#qspinbox-widget}{QSpinBox}.

   809 

   810     \row

   811         \o QFrame \target qframe-widget

   812         \o Supports the \l{box model}.

   813 

   814            Since 4.3, setting a stylesheet on a QLabel automatically

   815            sets the QFrame::frameStyle property to QFrame::StyledPanel.

   816 

   817            See \l{Qt Style Sheets Examples#Customizing QFrame}{Customizing QFrame}

   818            for an example.

   819 

   820     \row

   821         \o QGroupBox \target qgroupbox-widget

   822         \o Supports the \l{box model}. The title can be styled using the

   823            \l{#title-sub}{::title} subcontrol. By default, the title is placed

   824            depending on QGroupBox::textAlignment.

   825 

   826            In the case of a checkable QGroupBox, the title includes the

   827            check indicator. The indicator is styled using the

   828            the \l{#indicator-sub}{::indicator} subcontrol. The

   829            \l{#spacing-prop}{spacing} property can be used to control

   830            the spacing between the text and indicator.

   831 

   832            See \l{Qt Style Sheets Examples#Customizing QGroupBox}{Customizing QGroupBox}

   833            for an example.

   834 

   835     \row

   836         \o QHeaderView \target qheaderview-widget

   837         \o Supports the \l{box model}. The sections of the header view are

   838            styled using the \l{#section-sub}{::section} sub control. The

   839            \c{section} Sub-control supports the \l{#middle-ps}{:middle},

   840            \l{#first-ps}{:first}, \l{#last-ps}{:last},

   841            \l{#only-one-ps}{:only-one}, \l{#next-selected-ps}{:next-selected},

   842            \l{#previous-selected-ps}{:previous-selected},

   843            \l{#selected-ps}{:selected},

   844            and \l{#checked-ps}{:checked} pseudo states.

   845 

   846            Sort indicator in can be styled using the

   847            \l{#up-arrow-sub}{::up-arrow} and the

   848            \l{#down-arrow-sub}{::down-arrow} Sub-control.

   849 

   850            See \l{Qt Style Sheets Examples#Customizing QHeaderView}{Customizing QHeaderView}

   851            for an example.

   852 

   853     \row

   854         \o QLabel \target qlabel-widget

   855         \o Supports the \l{box model}. Does not support the

   856            \l{#hover-ps}{:hover} pseudo-state.

   857 

   858            Since 4.3, setting a stylesheet on a QLabel automatically

   859            sets the QFrame::frameStyle property to QFrame::StyledPanel.

   860 

   861            See \l{Qt Style Sheets Examples#Customizing QFrame}{Customizing QFrame} for an

   862            example (a QLabel derives from QFrame).

   863 

   864     \row

   865         \o QLineEdit \target qlineedit-widget

   866         \o Support the \l{box model}.

   867 

   868            The color and background of the selected item is styled using

   869            \l{#selection-color-prop}{selection-color} and

   870            \l{#selection-background-color-prop}{selection-background-color}

   871            respectively.

   872 

   873            The password character can be styled using the

   874            \l{#lineedit-password-character-prop}{lineedit-password-character}

   875            property.

   876 

   877            See \l{Qt Style Sheets Examples#Customizing QLineEdit}{Customizing QLineEdit}

   878            for an example.

   879 

   880     \row

   881         \o QListView \target qlistview-widget

   882         \o Supports the \l{box model}. When

   883            \l{QAbstractItemView::alternatingRowColors}{alternating row colors}

   884            is enabled, the alternating colors can be styled using the

   885            \l{#alternate-background-color-prop}{alternate-background-color}

   886            property.

   887 

   888            The color and background of the selected item is styled using

   889            \l{#selection-color-prop}{selection-color} and

   890            \l{#selection-background-color-prop}{selection-background-color}

   891            respectively.

   892 

   893            The selection behavior is controlled by the

   894            \l{#show-decoration-selected-prop}{show-decoration-selected} property.

   895 

   896            Use the \l{#item-sub}{::item} subcontrol for more fine grained

   897            control over the items in the QListView.

   898 

   899            See \l{qabstractscrollarea-widget}{QAbsractScrollArea} to

   900            style scrollable backgrounds.

   901 

   902            See \l{Qt Style Sheets Examples#Customizing QListView}

   903            {Customzing QListView} for an example.

   904 

   905     \row

   906         \o QListWidget \target qlistwidget-widget

   907         \o See \l{#qlistview-widget}{QListView}.

   908 

   909     \row

   910         \o QMainWindow \target qmainwindow-widget

   911         \o Supports styling of the separator

   912 

   913            The separator in a QMainWindow when using QDockWidget is styled

   914            using the \l{#separator-sub}{::separator} subcontrol.

   915 

   916            See \l{Qt Style Sheets Examples#Customizing QMainWindow}{Customizing QMainWindow}

   917            for an example.

   918 

   919     \row

   920         \o QMenu \target qmenu-widget

   921         \o Supports the \l{box model}.

   922 

   923            Individual items are styled using the \l{#item-sub}{::item}

   924            subcontrol. In addition to the usually supported pseudo states,

   925            \c{item} subcontrol supports the

   926            \l{#selected-ps}{:selected}, \l{#default-ps}{:default},

   927            \l{#exclusive-ps}{:exclusive} and the

   928            \l{#non-exclusive-ps}{non-exclusive} pseudo states.

   929 

   930            The indicator of checkable menu items is styled using the

   931            \l{#indicator-sub}{::indicator} subcontrol.

   932 

   933            The separator is styled using the \l{#separator-sub}{::separator}

   934            subcontrol.

   935 

   936            For items with a sub menu, the arrow marks are styled using the

   937            \l{::right-arrow-sub}{right-arrow} and

   938            \l{::left-arrow-sub}{left-arrow}.

   939 

   940             The scroller is styled using the \l{#scroller-sub}{::scroller}.

   941 

   942             The tear-off is styled using the \l{#tear-off-sub}{::tear-off}.

   943 

   944            See \l{Qt Style Sheets Examples#Customizing QMenu}{Customizing QMenu}

   945            for an example.

   946 

   947     \row

   948         \o QMenuBar \target qmenubar-widget

   949         \o Supports the \l{box model}. The \l{#spacing-prop}{spacing}

   950            property specifies the spacing between menu items.

   951            Individual items are styled using the \l{#item-sub}{::item}

   952            subcontrol.

   953 

   954            \warning When running on Qt/Mac, the menu bar is usually embedded into the

   955            system-wide menu bar. In this case, the style sheet will have no effect.

   956 

   957            See \l{Qt Style Sheets Examples#Customizing QMenuBar}{Customizing QMenuBar}

   958            for an example.

   959 

   960     \row

   961         \o QMessageBox \target qmessagebox-widget

   962         \o The \l{#messagebox-text-interaction-flags-prop}

   963            {messagebox-text-interaction-flags} property can be used to alter

   964            the interaction with text in the message box.

   965 

   966     \row

   967         \o QProgressBar \target qprogressbar-widget

   968         \o Supports the \l{box model}. The chunks of the progress bar

   969            can be styled using the \l{#chunk-sub}{::chunk} subcontrol.

   970            The chunk is displayed on the Contents rectangle of the widget.

   971 

   972            If the progress bar displays text, use the \l{text-align-prop}{text-align}

   973            property to position the text.

   974 

   975            Indeterminate progress bars have the

   976            \l{#indeterminate-ps}{:indeterminate} pseudo state set.

   977 

   978            See \l{Qt Style Sheets Examples#Customizing QProgressBar}{Customizing QProgressBar}

   979            for an example.

   980 

   981     \row

   982         \o QPushButton \target qpushbutton-widget

   983         \o Supports the \l{box model}. Supports the \l{#default-ps}{:default},

   984            \l{#flat-ps}{:flat}, \l{#checked-ps}{:checked} pseudo states.

   985 

   986            For QPushButton with a menu, the menu indicator is styled

   987            using the \l{#menu-indicator-sub}{::menu-indicator}

   988            subcontrol. Appearance of checkable push buttons can be

   989            customized using the \l{#open-ps}{:open} and

   990            \l{#closed-ps}{:closed} pseudo-states.

   991 

   992            \warning If you only set a background-color on a QPushButton, the background

   993            may not appear unless you set the border property to some value. This is

   994            because, by default, the QPushButton draws a native border which completely

   995            overlaps the background-color. For example,

   996 

   997            \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 30

   998 

   999            See \l{Qt Style Sheets Examples#Customizing QPushButton}{Customizing QPushButton}

  1000            for an example.

  1001 

  1002     \row

  1003         \o QRadioButton \target qradiobutton-widget

  1004         \o Supports the \l{box model}. The check indicator can be

  1005            styled using the \l{#indicator-sub}{::indicator}

  1006            subcontrol. By default, the indicator is placed in the Top

  1007            Left corner of the Contents rectangle of the widget.

  1008 

  1009            The \l{#spacing-prop}{spacing} property

  1010            specifies the spacing between the check indicator and

  1011            the text.

  1012 

  1013            See \l{Qt Style Sheets Examples#Customizing QRadioButton}

  1014            {Customizing QRadioButton} for an example.

  1015 

  1016     \row

  1017         \o QScrollBar \target qscrollbar-widget

  1018         \o Supports the \l{box model}. The Contents rectangle of the widget

  1019            is considered to be the groove over which the slider moves. The extent

  1020            of the QScrollBar (i.e the width or the height depending on the orientation)

  1021            is set using the \l{#width-prop}{width} or \l{#height-prop}{height} property

  1022            respectively. To determine the orientation, use the

  1023            \l{#horizontal-ps}{:horizontal} and the \l{vertical-ps}{:vertical}

  1024            pseudo states.

  1025 

  1026            The slider can be styled using the \l{#handle-sub}{::handle} subcontrol.

  1027            Setting the \l{#min-width-prop}{min-width} or \l{#min-height-prop}{min-height}

  1028            provides size contraints for the slider depending on the orientation.

  1029 

  1030            The \l{add-line-sub}{::add-line} subcontrol can be used to style the

  1031            button to add a line. By default, the add-line subcontrol is placed in

  1032            top right corner of the Border rectangle of the widget. Depending on the

  1033            orientation the \l{#right-arrow-sub}{::right-arrow} or

  1034            \l{#down-arrow-sub}{::down-arrow}. By default, the arrows are placed in

  1035            the center of the Contents rectangle of the add-line subcontrol.

  1036 

  1037            The \l{sub-line-sub}{::sub-line} subcontrol can be used to style the

  1038            button to subtract a line. By default, the sub-line subcontrol is placed in

  1039            bottom right corner of the Border rectangle of the widget. Depending on the

  1040            orientation the \l{#left-arrow-sub}{::left-arrow} or

  1041            \l{#up-arrow-sub}{::up-arrow}. By default, the arrows are placed in

  1042            the center of the Contents rectangle of the sub-line subcontrol.

  1043 

  1044            The \l{sub-page-sub}{::sub-page} subcontrol can be used to style the

  1045            region of the slider that subtracts a page. The \l{add-page-sub}{::add-page}

  1046            subcontrol can be used to style the region of the slider that adds a page.

  1047 

  1048            See \l{Qt Style Sheets Examples#Customizing QScrollBar}{Customizing QScrollBar}

  1049            for an example.

  1050 

  1051     \row

  1052         \o QSizeGrip \target qsizegrip-widget

  1053         \o Supports the \l{#width-prop}{width},

  1054            \l{#height-prop}{height}, and \l{#image-prop}{image}

  1055            properties.

  1056 

  1057            See \l{Qt Style Sheets Examples#Customizing QSizeGrip}{Customizing QSizeGrip}

  1058            for an example.

  1059 

  1060     \row

  1061         \o QSlider \target qslider-widget

  1062         \o Supports the \l{box model}. For horizontal slides, the

  1063            \l{min-width-prop}{min-width} and \l{height-prop}{height}

  1064            properties must be provided. For vertical sliders, the

  1065            \l{min-height-prop}{min-height} and \l{width-prop}{width}

  1066            properties must be provided.

  1067 

  1068            The groove of the slider is styled

  1069            using the \l{#groove-sub}{::groove}. The groove is

  1070            positioned by default in the Contents rectangle of the widget.

  1071            The thumb of the slider is styled using \l{#handle-sub}{::handle}

  1072            subcontrol. The subcontrol moves in the Contents rectangle of

  1073            the groove subcontrol.

  1074 

  1075            See \l{Qt Style Sheets Examples#Customizing QSlider}{Customizing QSlider}

  1076            for an example.

  1077 

  1078     \row

  1079         \o QSpinBox \target qspinbox-widget

  1080         \o The frame of the spin box can be styled using the \l{box

  1081            model}.

  1082 

  1083            The up button and arrow can be styled using the

  1084            \l{#up-button-sub}{::up-button} and

  1085            \l{#up-arrow-sub}{::up-arrow} subcontrols. By default,

  1086            the up-button is placed in the top right corner in the

  1087            Padding rectangle of the widget. Without an explicit size,

  1088            it occupies half the height of its reference rectangle.

  1089            The up-arrow is placed in the center of the Contents

  1090            rectangle of the up-button.

  1091 

  1092            The down button and arrow can be styled using the

  1093            \l{#down-button-sub}{::down-button} and

  1094            \l{#down-arrow-sub}{::down-arrow} subcontrols. By default,

  1095            the down-button is placed in the bottom right corner in the

  1096            Padding rectangle of the widget. Without an explicit size,

  1097            it occupies half the height of its reference rectangle.

  1098            The bottom-arrow is placed in the center of the Contents

  1099            rectangle of the bottom-button.

  1100 

  1101            See \l{Qt Style Sheets Examples#Customizing QSpinBox}{Customizing QSpinBox}

  1102            for an example.

  1103 

  1104     \row

  1105         \o QSplitter \target qsplitter-widget

  1106         \o Supports the \l{box model}. The handle of the splitter

  1107            is styled using the \l{#handle-sub}{::handle} subcontrol.

  1108 

  1109            See \l{Qt Style Sheets Examples#Customizing QSplitter}{Customizing QSplitter}

  1110            for an example.

  1111 

  1112     \row

  1113         \o QStatusBar \target qstatusbar-widget

  1114         \o Supports only the \l{Qt Style Sheets Reference#background-prop}

  1115            {background} property.

  1116            The frame for individual items can be style using the

  1117            \l{#item-sub}{::item} subcontrol.

  1118 

  1119            See \l{Qt Style Sheets Examples#Customizing QStatusBar}{Customizing QStatusBar}

  1120            for an example.

  1121 

  1122     \row

  1123         \o QTabBar \target qtabbar-widget

  1124         \o Individual tabs may be styled using the \l{#tab-sub}{::tab}  subcontrol.

  1125            Close buttons using the \l{#close-button-sub}{::close-button}

  1126            The tabs support the

  1127            \l{#only-one-ps}{:only-one}, \l{#first-ps}{:first},

  1128            \l{#last-ps}{:last}, \l{#middle-ps}{:middle},

  1129            \l{#previous-selected-ps}{:previous--selected},

  1130            \l{#next-selected-ps}{:next-selected},

  1131            \l{#selected-ps}{:selected} pseudo states.

  1132 

  1133             The \l{#top-ps}{:top}, \l{#left-ps}{:left}, \l{#right-ps}{:right},

  1134             \l{#bottom-ps}{:bottom} pseudo states depending on the orientation

  1135             of the tabs.