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

/****************************************************************************
**
** Copyright (C) 2010 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$
**
****************************************************************************/

/*!
    \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.