/****************************************************************************

**

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

** All rights reserved.

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

**

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

**

** $QT_BEGIN_LICENSE:LGPL$

** No Commercial Usage

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

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

** contained in the Technology Preview License Agreement accompanying

** this package.

**

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

**

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

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

**

**

**

**

**

**

**

**

** $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