source: trunk/doc/src/widgets-and-layouts/stylesheet.qdoc@ 624

/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain additional
** rights.  These rights are described in the Nokia Qt LGPL Exception
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page stylesheet.html
    \title Qt Style Sheets
    \brief How to use style sheets to customize the appearance of widgets.

    \ingroup frameworks-technologies

    \previouspage {Implementing Styles and Style Aware Widgets}{Styles}
    \contentspage Widgets and Layouts
    \nextpage The Style Sheet Syntax

    \keyword style sheet
    \keyword stylesheet

    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 \l{http://www.w3.org/Style/CSS/}{Cascading Style Sheets
    (CSS)} but adapted to the world of widgets.

    Topics:

    \list
    \i \l{Overview}
    \i \l{The Style Sheet Syntax}
    \i \l{Qt Designer Integration}
    \i \l{Customizing Qt Widgets Using Style Sheets}
    \i \l{Qt Style Sheets Reference}
    \i \l{Qt Style Sheets Examples}
    \endlist

    \target overview
    \section1 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
    \l{QLineEdit}s should use yellow as their background color, and
    all \l{QCheckBox}es should use red as the text color:

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

    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 \l{QStyle}{widget
    style}, meaning that your applications will look as native as
    possible, 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. In addition, \l{Qt Designer}
    provides style sheet integration, making it easy to view the effects
    of a style sheet in different \l{QStyle}{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 \l{QStyle::styleHint()}{style hint}. The
    \l{widgets/stylesheet}{Style Sheet} example depicted below defines
    two distinctive style sheets that you can try out and modify at
    will.

    \table
    \row \o \inlineimage stylesheet-coffee-xp.png
         \o \inlineimage stylesheet-pagefold.png
    \row \o Coffee theme running on Windows XP
         \o Pagefold theme running on Windows XP
    \endtable

    \table
    \row \o \inlineimage stylesheet-coffee-cleanlooks.png
         \o \inlineimage stylesheet-pagefold-mac.png
    \row \o Coffee theme running on Ubuntu Linux
         \o Pagefold theme running on Mac OS X
    \endtable

    When a style sheet is active, the QStyle returned by QWidget::style()
    is a wrapper "style sheet" style, \e 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).

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

    \warning Qt style sheets are currently not supported for custom QStyle
    subclasses. We plan to address this in some future release.
*/

/*!
    \page stylesheet-syntax.html
    \contentspage {Qt Style Sheet}{Contents}
    \previouspage Qt Style Sheet
    \nextpage Qt Designer Integration
    \title 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.

    \tableofcontents

    \section1 Style Rules

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

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

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

    Qt Style Sheet is generally case insensitive (i.e., \c color,
    \c Color, \c COLOR, and \c cOloR refer to the same property).
    The only exceptions are class names,
    \l{QObject::setObjectName()}{object names}, and Qt property
    names, which are case sensitive.

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

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

    is equivalent to this sequence of three rules:

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

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

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

    See the \l{List of Properties} section below for the list of
    properties provided by Qt widgets.

    \section1 Selector Types

    All the examples so far used the simplest type of selector, the
    Type Selector. Qt Style Sheets support all the
    \l{http://www.w3.org/TR/REC-CSS2/selector.html#q1}{selectors
    defined in CSS2}. The table below summarizes the most useful
    types of selectors.

    \table 100%
    \header
        \o Selector
        \o Example
        \o Explanation

    \row
        \o Universal Selector
        \o \c *
        \o Matches all widgets.

    \row
        \o Type Selector
        \o \c QPushButton
        \o Matches instances of QPushButton and of its subclasses.

    \row
        \o Property Selector
        \o \c{QPushButton[flat="false"]}
        \o Matches instances of QPushButton that are not
           \l{QPushButton::}{flat}. You may use this selector to test
           for any Qt \l{Qt's Property System}{property} that supports
           QVariant::toString() (see the \l{QVariant::}{toString()}
           function documentation for details). In addition, the
           special \c class property is supported, for the name of the
           class.

           This selector may also be used to test dynamic properties.
           For more information on customization using dynamic properties,
           refer to \l{Customizing Using Dynamic Properties}.

           Instead of \c =, you can also use \c ~= to test whether a
           Qt property of type QStringList contains a given QString.

           \warning If the value of the Qt property changes after the
           style sheet has been set, it might be necessary to force a
           style sheet recomputation. One way to achieve this is to
           unset the style sheet and set it again.

    \row
        \o Class Selector
        \o \c .QPushButton
        \o Matches instances of QPushButton, but not of its subclasses.

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

    \row
        \o ID \target ID Selector
           Selector
        \o \c{QPushButton#okButton}
        \o Matches all QPushButton instances whose
           \l{QObject::objectName}{object name} is \c okButton.

    \row
        \o Descendant Selector
        \o \c{QDialog QPushButton}
        \o Matches all instances of QPushButton that are descendants
           (children, grandchildren, etc.) of a QDialog.

    \row
        \o Child Selector
        \o \c{QDialog > QPushButton}
        \o Matches all instances of QPushButton that are direct
           children of a QDialog.
    \endtable

    \section1 Sub-Controls

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

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

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

    Sub-controls are always positioned with respect to another element - a
    reference element. This reference element could be the widget or another
    Sub-control. For example, the \l{Qt Style Sheets Reference#drop-down-sub}
    {::drop-down} of a QComboBox is placed, by default, in the top right corner
    of the Padding rectangle of the QComboBox. The
    \l{Qt Style Sheets Reference#drop-down-sub}{::drop-down} is placed,
    by default, in the Center of the Contents rectangle of the
    \l{Qt Style Sheets Reference#drop-down-sub}{::drop-down} Sub-control. See
    the \l{List of Stylable Widgets} below for the Sub-controls to use to
    style a widget and their default positions.

    The origin rectangle to be used can be changed using the
    \l{Qt Style Sheets Reference#subcontrol-origin-prop}{subcontrol-origin}
    property. For example, if we want to place the drop-down in the margin
    rectangle of the QComboBox instead of the default Padding rectangle, we
    can specify:

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

    The alignment of the drop-down within the Margin rectangle is changed
    using \l{Qt Style Sheets Reference#subcontrol-position-prop}
    {subcontrol-position} property.

    The \l{Qt Style Sheets Reference#width-prop}{width} and
    \l{Qt Style Sheets Reference#height-prop}{height} properties can be used
    to control the size of the Sub-control. Note that setting a
    \l{Qt Style Sheets Reference#image-prop}{image} implicitly sets the size
    of a Sub-control.

    The relative positioning scheme
    (\l{Qt Style Sheets Reference#position-prop}{position} : relative),
    allows the position of the Sub-Control to be offset from its initial
    position. For example, when the QComboBox's drop-down button is
    pressed, we might like the arrow inside to be offset to give a
    "pressed" effect. To achieve this, we can specify:

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

    The absolute positioning scheme
    (\l{Qt Style Sheets Reference#position-prop}{position} : absolute),
    allows the position and size of the Sub-control to be changed with
    respect to the reference element.

    Once positioned, they are treated the same as widgets and can be styled
    using the \l{box model}.

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

    \note With complex widgets such as QComboBox and QScrollBar, if one
    property or sub-control is customized, \bold{all} the other properties or
    sub-controls must be customized as well.

    \section1 Pseudo-States

    Selectors may contain \e{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
    (\c{:}) in between. For example, the following rule applies when
    the mouse hovers over a QPushButton:

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

    Pseudo-states can be negated using the exclamation operator. For
    example, the following rule applies when the mouse does not hover
    over a QRadioButton:

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

    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:

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

    Negated Pseudo-states may appear in Pseudo-state chains. For example,
    the following rule applies when the mouse hovers over a QPushButton
    that is not pressed:

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

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

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

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

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

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

    \section1 Conflict Resolution

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

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

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

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

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

    Here's a tricky one:

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

    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:

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

    Alternatively, we can make the first rule more specific:

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

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

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

    Both rules apply to QPushButton instances (since QPushButton
    inherits QAbstractButton) and there is a conflict for the
    \l{Qt Style Sheets Reference#color-prop}{color} property. Because QPushButton
    inherits QAbstractButton, it might be tempting to assume that
    \c QPushButton is more specific than \c QAbstractButton. However,
    for style sheet computations, all Type Selectors have the same
    specificity, and the rule that appears last takes precedence. In
    other words, \l{Qt Style Sheets Reference#color-prop}{color} is set to \c gray
    for all \l{QAbstractButton}s, including \l{QPushButton}s. If we really
    want \l{QPushButton}s to have red text, we can always reorder the
    rules.

    For determining the specificity of a rule, Qt Style Sheets follow
    the
    \l{http://www.w3.org/TR/REC-CSS2/cascade.html#specificity}{CSS2
    Specification}:

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

    \list
    \o \e{count the number of ID attributes in the selector (= a)}
    \o \e{count the number of other attributes and pseudo-classes in the selector (= b)}
    \o \e{count the number of element names in the selector (= c)}
    \o \e{ignore pseudo-elements [i.e., \l{subcontrols}].}
    \endlist

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

    \e{Some examples:}

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

    \section1 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:

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

    Then we set a style sheet on a QPushButton object:

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

    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

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

    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
    \l{http://www.w3.org/TR/CSS2/cascade.html#cascade}{CSS2
    Specification} for the gory details. Be aware that Qt currently
    doesn't implement \c{!important}.

    \section1 Inheritance

    In classic CSS, when font and color of an item is not explicitly set,
    it gets automatically inherited from the parent. When using Qt Style Sheets,
    a widget does \bold{not} automatically inherit its font and color setting
    from its parent widget.

    For example, consider a QPushButton inside a QGroupBox:

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

    The QPushButton does not have an explicit color set. Hence, instead
    of inheriting color of its parent QGroupBox, it has the system color.
    If we want to set the color on a QGroupBox and its children,
    we can write:

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

    In contrast, setting a font and propagate using QWidget::setFont() and
    QWidget::setPalette() propagates to child widgets.

    \section1 Widgets inside C++ namespaces

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

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

    Qt Style Sheet uses QObject::className() of the widget to determine
    when to apply the Type Selector. When custom widgets are inside namespaces,
    the QObject::className() returns <namespace>::<classname>. This conflicts
    with the syntax for \l{Sub-Controls}. To overcome this problem,
    when using the Type Selector for widgets inside namespaces, we must
    replace the "::" with "--". For example,

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

    \section1 Setting QObject properties

    From 4.3 and above, any designable Q_PROPERTY
    can be set using the qproperty-<property name> syntax.

    For example,
    \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 28

    If the property references an enum declared with Q_ENUMS, you should
    reference its constants by name, i.e., not their numeric value.

*/

/*!
    \page stylesheet-designer.html
    \contentspage {Qt Style Sheet}{Contents}
    \previouspage The Style Sheet Syntax
    \nextpage Customizing Qt Widgets Using Style Sheets
    \title Qt Designer Integration

    \l{Qt Designer}{Qt Designer} is an excellent tool
    to preview style sheets. You can right-click on any widget in Designer
    and select \gui{Change styleSheet...} to set the style sheet.

    \image designer-stylesheet-options.png

    In Qt 4.2 and later, \l{Qt Designer}{Qt Designer} also includes a
    style sheet syntax highlighter and validator. The validator indicates
    if the syntax is valid or invalid, at the bottom left of the \gui{Edit
    Style Sheet} dialog.

    \image designer-validator-highlighter.png

    When you click \gui{OK} or \gui{Apply}, \QD will automatically display
    the widget with its new stylesheet.

    \image designer-stylesheet-usage.png
    */

/*!
    \page stylesheet-customizing.html
    \contentspage {Qt Style Sheet}{Contents}
    \previouspage Qt Designer Integration
    \nextpage Qt Style Sheets Reference
    \title Customizing Qt Widgets Using Style Sheets

    When using style sheets, every widget is treated as a box with four
    concentric rectangles: the margin rectangle, the border rectangle, the
    padding rectangle, and the content rectangle. The box model describes
    this in further detail.

    \tableofcontents

    \target box model
    \section1 The Box Model

    The four concentric rectangles appear conceptually as below:

    \image stylesheet-boxmodel.png

    \list
    \o The margin falls outside the border.
    \o The border is drawn between the margin and the padding.
    \o The padding falls inside the border, between the border and
       the actual contents.
    \o The content is what is left from the original widget or
       subcontrol once we have removed the margin, the border, and
       the padding.
    \endlist

    The \l{Qt Style Sheets Reference#margin-prop}{margin},
    \l{Qt Style Sheets Reference#border-width-prop}
    {border-width}, and
    \l{Qt Style Sheets Reference#padding-prop}{padding}
    properties all default to zero. In that case, all four rectangles
    (\c margin, \c border, \c padding, and \c content) coincide exactly.

    You can specify a background for the widget using the
    \l{Qt Style Sheets Reference#background-image-prop}{background-image}
    property. By default, the background-image is drawn only for the area
    inside the border. This can be changed using the
    \l{Qt Style Sheets Reference#background-clip-prop}{background-clip}
    property. You can use
    \l{Qt Style Sheets Reference#background-repeat-prop}{background-repeat}
    and
    \l{Qt Style Sheets Reference#background-origin-prop}{background-origin}
    to control the repetition and origin of the background image.

    A background-image does not scale with the size of the widget. To provide
    a "skin" or background that scales along with the widget size, one must
    use
    \l{Qt Style Sheets Reference#border-image-prop}{border-image}. Since the
    border-image property provides an alternate background, it is not required
    to specify a background-image when border-image is specified. In the case,
    when both of them are specified, the border-image draws over the
    background-image.

    In addition, the \l{Qt Style Sheets Reference#image-prop}{image} property
    may be used to draw an image over the border-image. The image specified does
    not tile or stretch and when its size does not match the size of the widget,
    its alignment is specified using the
    \l{Qt Style Sheets Reference#image-position-prop}{image-position}
    property. Unlike background-image and border-image, one may specify a
    SVG in the image property, in which case the image is scaled automatically
    according to the widget size.

    The steps to render a rule are as follows:
        \list
        \o Set clip for entire rendering operation (border-radius)
        \o Draw the background (background-image)
        \o Draw the border (border-image, border)
        \o Draw overlay image (image)
        \endlist

    \target sub controls
    \section1 Sub-controls

    A widget is considered as a hierarchy (tree) of subcontrols drawn on top
    of each other. For example, the QComboBox draws the drop-down sub-control
    followed by the down-arrow sub-control. A QComboBox is thus rendered as
    follows:
        \list
        \o Render the QComboBox { } rule
        \o Render the QComboBox::drop-down { } rule
        \o Render the QComboBox::down-arrow { } rule
        \endlist

    Sub-controls share a parent-child relationship. In the case of QComboBox,
    the parent of down-arrow is the drop-down and the parent of drop-down is
    the widget itself. Sub-controls are positioned within their parent using
    the \l{Qt Style Sheets Reference#subcontrol-position-prop}
    {subcontrol-position} and
    \l{Qt Style Sheets Reference#subcontrol-origin-prop}{subcontrol-origin}
    properties.

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

    \note With complex widgets such as QComboBox and QScrollBar, if one
    property or sub-control is customized, \bold{all} the other properties or
    sub-controls must be customized as well.

*/

/*!
    \page stylesheet-reference.html
    \contentspage {Qt Style Sheet}{Contents}
    \previouspage Customizing Qt Widgets Using Style Sheets
    \nextpage Qt Style Sheets Examples
    \title Qt Style Sheets Reference

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

    \tableofcontents

    \section1 List of Stylable Widgets

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

    \table 100%
    \header
        \o Widget
        \o How to Style

    \row
        \o QAbstractScrollArea \target qabstractscrollarea-widget
        \o Supports the \l{box model}.

           All derivatives of QAbstractScrollArea, including QTextEdit,
           and QAbstractItemView (all item view classes), support
           scrollable backgrounds using
           \l{Qt Style Sheets Reference#background-attachment-prop}
           {background-attachment}. Setting the background-attachment to
           \c{fixed} provides a background-image that does not scroll with the
           viewport. Setting the background-attachment to \c{scroll}, scrolls
           the background-image when the scroll bars move.

           See \l{Qt Style Sheets Examples#Customizing QAbstractScrollArea}
           {Customizing QAbstractScrollArea} for an example.

    \row
        \o QCheckBox \target qcheckbox-widget
        \o Supports the \l{box model}. The check indicator can be
           styled using the \l{#indicator-sub}{::indicator}
           subcontrol. By default, the indicator is placed in the Top
           Left corner of the Contents rectangle of the widget.

           The \l{#spacing-prop}{spacing} property
           specifies the spacing between the check indicator and
           the text.

           See \l{Qt Style Sheets Examples#Customizing QCheckBox}
           {Customizing QCheckBox} for an example.

    \row
        \o QColumnView \target qcolumnview-widget
        \o The grip can be styled be using the \l{image-prop}{image} property.
           The arrow indicators can by styled using the
           \l{left-arrow-sub}{::left-arrow} subcontrol and the
           \l{right-arrow-sub}{::right-arrow} subcontrol.

    \row
        \o QComboBox \target qcombobox-widget
        \o The frame around the combobox can be styled using the
           \l{box model}. The drop-down button can be styled using
           the \l{#drop-down-sub}{::drop-down} subcontrol. By default, the
           drop-down button is placed in the top right corner of the padding
           rectangle of the widget. The arrow mark inside the drop-down button
           can be styled using the \l{#down-arrow-sub}{::down-arrow}
           subcontrol. By default, the arrow is placed in the center of the
           contents rectangle of the drop-down subcontrol.

           See \l{Qt Style Sheets Examples#Customizing QComboBox}{Customizing QComboBox}
           for an example.

    \row
        \o QDateEdit \target qdateedit-widget
        \o See \l{#qspinbox-widget}{QSpinBox}.

    \row
        \o QDateTimeEdit \target qdatetimeedit-widget
        \o See \l{#qspinbox-widget}{QSpinBox}.

    \row
        \o QDialog \target qdialog-widget
        \o Supports only the \l{Qt Style Sheets Reference#background-prop}{background},
           \l{#background-clip-prop}{background-clip} and
           \l{#background-origin-prop}{background-origin} properties.

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

    \row
        \o QDialogButtonBox \target qdialogbuttonbox-widget
        \o The layout of buttons can be altered using the
           \l{#button-layout-prop}{button-layout} property.

    \row
        \o QDockWidget \target qdockwidget-widget
        \o Supports styling of the title bar and the title bar buttons when docked.

        The dock widget border can be styled using the \l{#border-prop}{border}
        property. The \l{#title-sub}{::title} subcontrol can be used to customize
        the title bar. The close and float buttons are positioned with respect
        to the \l{title-sub}{::title} subcontrol using the
        \l{#close-button-sub}{::close-button} and
        \l{#float-button-sub}{::float-button} respectively.

        When the title bar is vertical, the \l{#vertical-ps}{:vertical} pseudo
        class is set. In addition, depending on QDockWidget::DockWidgetFeature,
        the \l{#closable-ps}{:closable}, \l{#floatable-ps}{:floatable} and
        \l{#movable-ps}{:movable} pseudo states are set.

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

        \warning The style sheet has no effect when the QDockWidget is undocked
        as Qt uses native top level windows when undocked.

        See \l{Qt Style Sheets Examples#Customizing QDockWidget}
        {Customizing QDockWidget} for an example.

    \row
        \o QDoubleSpinBox \target qdoublespinbox-widget
        \o See \l{#qspinbox-widget}{QSpinBox}.

    \row
        \o QFrame \target qframe-widget
        \o Supports the \l{box model}.

           Since 4.3, setting a stylesheet on a QLabel automatically
           sets the QFrame::frameStyle property to QFrame::StyledPanel.

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

    \row
        \o QGroupBox \target qgroupbox-widget
        \o Supports the \l{box model}. The title can be styled using the
           \l{#title-sub}{::title} subcontrol. By default, the title is placed
           depending on QGroupBox::textAlignment.

           In the case of a checkable QGroupBox, the title includes the
           check indicator. The indicator is styled using the
           the \l{#indicator-sub}{::indicator} subcontrol. The
           \l{#spacing-prop}{spacing} property can be used to control
           the spacing between the text and indicator.

           See \l{Qt Style Sheets Examples#Customizing QGroupBox}{Customizing QGroupBox}
           for an example.

    \row
        \o QHeaderView \target qheaderview-widget
        \o Supports the \l{box model}. The sections of the header view are
           styled using the \l{#section-sub}{::section} sub control. The
           \c{section} Sub-control supports the \l{#middle-ps}{:middle},
           \l{#first-ps}{:first}, \l{#last-ps}{:last},
           \l{#only-one-ps}{:only-one}, \l{#next-selected-ps}{:next-selected},
           \l{#previous-selected-ps}{:previous-selected},
           \l{#selected-ps}{:selected},
           and \l{#checked-ps}{:checked} pseudo states.

           Sort indicator in can be styled using the
           \l{#up-arrow-sub}{::up-arrow} and the
           \l{#down-arrow-sub}{::down-arrow} Sub-control.

           See \l{Qt Style Sheets Examples#Customizing QHeaderView}{Customizing QHeaderView}
           for an example.

    \row
        \o QLabel \target qlabel-widget
        \o Supports the \l{box model}. Does not support the
           \l{#hover-ps}{:hover} pseudo-state.

           Since 4.3, setting a stylesheet on a QLabel automatically
           sets the QFrame::frameStyle property to QFrame::StyledPanel.

           See \l{Qt Style Sheets Examples#Customizing QFrame}{Customizing QFrame} for an
           example (a QLabel derives from QFrame).

    \row
        \o QLineEdit \target qlineedit-widget
        \o Support the \l{box model}.

           The color and background of the selected item is styled using
           \l{#selection-color-prop}{selection-color} and
           \l{#selection-background-color-prop}{selection-background-color}
           respectively.

           The password character can be styled using the
           \l{#lineedit-password-character-prop}{lineedit-password-character}
           property.

           See \l{Qt Style Sheets Examples#Customizing QLineEdit}{Customizing QLineEdit}
           for an example.

    \row
        \o QListView \target qlistview-widget
        \o Supports the \l{box model}. When
           \l{QAbstractItemView::alternatingRowColors}{alternating row colors}
           is enabled, the alternating colors can be styled using the
           \l{#alternate-background-color-prop}{alternate-background-color}
           property.

           The color and background of the selected item is styled using
           \l{#selection-color-prop}{selection-color} and
           \l{#selection-background-color-prop}{selection-background-color}