source: trunk/doc/src/porting/qt4-styles.qdoc

/****************************************************************************
**
** Copyright (C) 2011 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: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 qt-info@nokia.com.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page qt4-styles.html
    \title The Qt 4 Style API

    \contentspage {What's New in Qt 4}{Home}
    \previouspage The Network Module in Qt 4
    \nextpage Thread Support in Qt 4

    Qt's style API is responsible for performing the widget drawing
    for built-in widgets. The Qt 4 style API has been revised to make
    it possible for a style to draw widgets without calling any
    functions on the widget.

    Because Qt 4 is split across multiple libraries, Qt needed this
    update to be able to draw widgets from other libraries than
    QtGui. For application developers, this has other benefits, such
    as more managable parameter lists and the possibility of drawing
    any graphical element without having a widget of a specific
    type.

    \section1 General Overview

    The QStyle class is an abstract base class that encapsulates
    the look and feel of a GUI. Qt's built-in widgets use it to
    perform nearly all of their drawing, ensuring that they look
    exactly like the equivalent native widgets.  

    Most draw functions now take four arguments:

    \list
    \o an enum value specifying which graphical element to draw
    \o a QStyleOption specifying how and where to render that element
    \o a QPainter that should be used to draw the element
    \o a QWidget on which the drawing is performed (optional)
    \endlist

    The style gets all the information it needs to render the
    graphical element from QStyleOption. The widget is passed as the
    last argument in case the style needs it to perform special
    effects (such as animated default buttons on Mac OS X), but it
    isn't mandatory. In fact, QStyle can be used to draw on any
    paint device, not just widgets, by setting the QPainter properly.

    Thanks to QStyleOption, it is now possible to make QStyle draw
    widgets without linking in any code for the widget. This is how
    Qt's built-in styles can draw Qt 3 widgets such as
    Q3ListView without necessarily linking against the Qt3Support
    library. Another significant benefit of the new approach is that
    it's now possible to use \l{QStyle}'s draw functions on other
    widgets than the built-in widgets; for example, you can draw a
    combobox on any widget, not just on a QComboBox.

    QStyleOption has various subclasses for the various types of
    graphical elements that can be drawn, and it's possible to create
    custom subclasses. For example, the QStyle::PE_FrameFocusRect
    element expects a QStyleOptionFocusRect argument. This is
    documented for each enum value.

    When reimplementing QStyle functions that take a
    QStyleOption parameter, you often need to cast the
    QStyleOption to a subclass (e.g., QStyleOptionFocusRect). For
    safety, you can use qstyleoption_cast() to ensure that the
    pointer type is correct. If the object isn't of the right type,
    qstyleoption_cast() returns 0. For example:

    \snippet doc/src/snippets/code/doc_src_qt4-styles.qdoc 0

    For performance reasons, there are few member functions and the
    access to the variables is direct. This "low-level" feel makes
    the structures use straightforward and emphasizes that these are
    simply parameters used by the style functions. In addition, the
    caller of a QStyle function usually creates QStyleOption
    objects on the stack. This combined with Qt's extensive use of
    \l{implicit sharing} for types such as QString, QPalette, and
    QColor ensures that no memory allocation needlessly takes place.
    (Dynamic memory allocation can be an expensive operation,
    especially when drawing very often in a short time.)

    \section1 Example Code

    The following code snippet illustrates how to use QStyle to
    draw the focus rectangle from a custom widget's paintEvent():

    \snippet doc/src/snippets/code/doc_src_qt4-styles.qdoc 1

    The next example shows how to derive from an existing style to
    customize the look of a graphical element:

    \snippet doc/src/snippets/customstyle/customstyle.h 0
    \codeline
    \snippet doc/src/snippets/customstyle/customstyle.cpp 2
    \snippet doc/src/snippets/customstyle/customstyle.cpp 3
    \snippet doc/src/snippets/customstyle/customstyle.cpp 4

    See also the \l{Styles Example} for a more detailed description of
    how custom styles can be created.

    \section1 Comparison with Qt 3

    The QStyle class has a similar API in Qt 4 as in Qt 3, with
    more or less the same functions. What has changed is the
    signature of the functions and the role played by QStyleOption.
    For example, here's the signature of the QStyle::drawControl()
    function in Qt 3:

    \snippet doc/src/snippets/code/doc_src_qt4-styles.qdoc 2

    Here's the signature of the same function in Qt 4:

    \snippet doc/src/snippets/code/doc_src_qt4-styles.qdoc 3

    In Qt 3, some of the information required to draw a graphical
    element was stored in a QStyleOption parameter, while the rest
    was deduced by querying the widget. In Qt 4, everything is stored
    in the QStyleOption parameter.
*/