source: trunk/doc/src/examples/styles.qdoc@ 1168

/****************************************************************************
**
** Copyright (C) 2011 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:FDL$
** 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 Free Documentation License
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of this
** file.
**
** If you have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \example widgets/styles
    \title Styles Example

    The Styles example illustrates how to create custom widget
    drawing styles using Qt, and demonstrates Qt's predefined styles.

    \image styles-enabledwood.png Screenshot of the Styles example

    A style in Qt is a subclass of QStyle or of one of its
    subclasses. Styles perform drawing on behalf of widgets. Qt
    provides a whole range of predefined styles, either built into
    the \l QtGui library or found in plugins. Custom styles are
    usually created by subclassing one of Qt's existing style and
    reimplementing a few virtual functions.

    In this example, the custom style is called \c NorwegianWoodStyle
    and derives from QMotifStyle. Its main features are the wooden
    textures used for filling most of the widgets and its round
    buttons and comboboxes.

    To implement the style, we use some advanced features provided by
    QPainter, such as \l{QPainter::Antialiasing}{antialiasing} (to
    obtain smoother button edges), \l{QColor::alpha()}{alpha blending}
    (to make the buttons appeared raised or sunken), and
    \l{QPainterPath}{painter paths} (to fill the buttons and draw the
    outline). We also use many features of QBrush and QPalette.

    The example consists of the following classes:

    \list
    \o \c NorwegianWoodStyle inherits from QMotifStyle and implements
        the Norwegian Wood style.
    \o \c WidgetGallery is a \c QDialog subclass that shows the most
       common widgets and allows the user to switch style
       dynamically.
    \endlist

    \section1 NorwegianWoodStyle Class Definition

    Here's the definition of the \c NorwegianWoodStyle class:

    \snippet examples/widgets/styles/norwegianwoodstyle.h 0

    The public functions are all declared in QStyle (QMotifStyle's
    grandparent class) and reimplemented here to override the Motif
    look and feel. The private functions are helper functions.

    \section1 NorwegianWoodStyle Class Implementation

    We will now review the implementation of the \c
    NorwegianWoodStyle class.

    \snippet examples/widgets/styles/norwegianwoodstyle.cpp 0

    The \c polish() function is reimplemented from QStyle. It takes a
    QPalette as a reference and adapts the palette to fit the style.
    Most styles don't need to reimplement that function. The
    Norwegian Wood style reimplements it to set a "wooden" palette.

    We start by defining a few \l{QColor}s that we'll need. Then we
    load two PNG images. The \c : prefix in the file path indicates
    that the PNG files are \l{The Qt Resource System}{embedded
    resources}.

    \table
    \row \o \inlineimage widgets/styles/images/woodbackground.png

         \o \bold{woodbackground.png}

            This texture is used as the background of most widgets.
            The wood pattern is horizontal.

    \row \o \inlineimage widgets/styles/images/woodbutton.png

         \o \bold{woodbutton.png}

            This texture is used for filling push buttons and
            comboboxes. The wood pattern is vertical and more reddish
            than the texture used for the background.
    \endtable

    The \c midImage variable is initialized to be the same as \c
    buttonImage, but then we use a QPainter and fill it with a 25%
    opaque black color (a black with an \l{QColor::alpha()}{alpha
    channel} of 63). The result is a somewhat darker image than \c
    buttonImage. This image will be used for filling buttons that the
    user is holding down.

    \snippet examples/widgets/styles/norwegianwoodstyle.cpp 1

    We initialize the palette. Palettes have various
    \l{QPalette::ColorRole}{color roles}, such as QPalette::Base
    (used for filling text editors, item views, etc.), QPalette::Text
    (used for foreground text), and QPalette::Background (used for
    the background of most widgets). Each role has its own QBrush,
    which usually is a plain color but can also be a brush pattern or
    even a texture (a QPixmap).

    In addition to the roles, palettes have several
    \l{QPalette::ColorGroup}{color groups}: active, disabled, and
    inactive. The active color group is used for painting widgets in
    the active window. The disabled group is used for disabled
    widgets. The inactive group is used for all other widgets. Most
    palettes have identical active and inactive groups, while the
    disabled group uses darker shades.

    We initialize the QPalette object with a brown color. Qt
    automatically derivates all color roles for all color groups from
    that single color. We then override some of the default values. For
    example, we use Qt::darkGreen instead of the default
    (Qt::darkBlue) for the QPalette::Highlight role. The
    QPalette::setBrush() overload that we use here sets the same
    color or brush for all three color groups.

    The \c setTexture() function is a private function that sets the
    texture for a certain color role, while preserving the existing
    color in the QBrush. A QBrush can hold both a solid color and a
    texture at the same time. The solid color is used for drawing
    text and other graphical elements where textures don't look good.

    At the end, we set the brush for the disabled color group of the
    palette. We use \c woodbackground.png as the texture for all
    disabled widgets, including buttons, and use a darker color to
    accompany the texture.

    \image styles-disabledwood.png The Norwegian Wood style with disabled widgets

    Let's move on to the other functions reimplemented from
    QMotifStyle:

    \snippet examples/widgets/styles/norwegianwoodstyle.cpp 3
    \snippet examples/widgets/styles/norwegianwoodstyle.cpp 4

    This QStyle::polish() overload is called once on every widget
    drawn using the style. We reimplement it to set the Qt::WA_Hover
    attribute on \l{QPushButton}s and \l{QComboBox}es. When this
    attribute is set, Qt generates paint events when the mouse
    pointer enters or leaves the widget. This makes it possible to
    render push buttons and comboboxes differently when the mouse
    pointer is over them.

    \snippet examples/widgets/styles/norwegianwoodstyle.cpp 5
    \snippet examples/widgets/styles/norwegianwoodstyle.cpp 6

    This QStyle::unpolish() overload is called to undo any
    modification done to the widget in \c polish(). For simplicity,
    we assume that the flag wasn't set before \c polish() was called.
    In an ideal world, we would remember the original state for each
    widgets (e.g., using a QMap<QWidget *, bool>) and restore it in
    \c unpolish().

    \snippet examples/widgets/styles/norwegianwoodstyle.cpp 7
    \snippet examples/widgets/styles/norwegianwoodstyle.cpp 8

    The \l{QStyle::pixelMetric()}{pixelMetric()} function returns the