source: trunk/doc/src/styles.qdoc@ 551

/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Qt Software Information ([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.0, 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 are unsure which license is appropriate for your use, please
** contact the sales department at [email protected].
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page style-reference.html

    \title Implementing Styles and Style Aware Widgets
    \ingroup architecture
    \brief An overview of styles and the styling of widgets.

    \tableofcontents

    \section1 Introduction

    Styles (classes that inherit QStyle) draw on behalf of widgets
    and encapsulate the look and feel of a GUI. Several styles are
    built into Qt (e.g., windows style and motif style). Other styles are
    only available on specific platforms (such as the windows XP style).
    Custom styles are made available as plugins or by creating an
    instance of the style class in an application and setting it with
    QApplication::setStyle().

    To implement a new style, you inherit one of Qt's existing styles
    - the one most resembling the style you want to create - and
    reimplement a few virtual functions. This process is somewhat
    involved, and we therefore provide this overview. We give a
    step-by-step walkthrough of how to style individual Qt widgets.
    We will examine the QStyle virtual functions, member variables,
    and enumerations.

    The part of this document that does not concern the styling of
    individual widgets is meant to be read sequentially because later
    sections tend to depend on earlier ones. The description of the
    widgets can be used for reference while implementing a style.
    However, you may need to consult the Qt source code in some cases.
    The sequence in the styling process should become clear after
    reading this document, which will aid you in locating relevant code.

    To develop style aware widgets (i.e., widgets that conform to
    the style in which they are drawn), you need to draw them using the
    current style. This document shows how widgets draw themselves
    and which possibilities the style gives them.

    \section1 The QStyle implementation

    The API of QStyle contains functions that draw the widgets, static
    helper functions to do common and difficult tasks (e.g.,
    calculating the position of slider handles) and functions to do
    the various calculations necessary while drawing (e.g., for the
    widgets to calculate their size hints). The style also help some
    widgets with the layout of their contents. In addition, it creates
    a QPalette that contains \l{QBrush}es to draw with.

    QStyle draws graphical elements; an element is a widget or a
    widget part like a push button bevel, a window frame, or a scroll
    bar. When a widget asks a style to draw an element, it provides the
    style with a style option, which is a class that contains the
    information necessary for drawing.

    We will in the course of this section look at the style elements,
    the style options, and the functions of QStyle. Finally, we describe
    how the palette is used.

    Items in item views is drawn by \l{Delegate Classes}{delegates} in
    Qt. The item view headers are still drawn by the style. Qt's
    default delegate, QStyledItemDelegate, draws its items partially
    through the current style; it draws the check box indicators and
    calculate bounding rectangles for the elements of which the item
    consists. In this document, we only describe how to implement a
    QStyle subclass. If you wish to add support for other datatypes
    than those supported by the QStyledItemDelegate, you need to
    implement a custom delegate. Note that delegates must be set
    programmatically for each individual widget (i.e., default
    delegates cannot be provided as plugins).

    \section2 The Style Elements

    A style element is a graphical part of a GUI. A widget consists
    of a hierarchy (or tree) of style elements. For instance, when a
    style receives a request to draw a push button (from QPushButton,
    for example), it draws a label (text and icon), a button bevel,
    and a focus frame. The button bevel, in turn, consists of a frame
    around the bevel and two other elements, which we will look at
    later. Below is a conceptual illustration of the push button
    element tree. We will see the actual tree for QPushButton when we
    go through the individual widgets.

    \image javastyle/conceptualpushbuttontree.png

    Widgets are not necessarily drawn by asking the style to draw
    only one element. Widgets can make several calls to the style to
    draw different elements. An example is QTabWidget, which draws its
    tabs and frame individually.

    There are three element types: primitive elements, control
    elements, and complex control elements. The elements are defined
    by the \l{QStyle::}{ComplexControl}, \l{QStyle::}{ControlElement},
    and \l{QStyle::}{PrimitiveElement} enums. The values of
    each element enum has a prefix to identify their type: \c{CC_} for
    complex elements, \c{CE_} for control elements, and \c{PE_} for
    primitive elements. We will in the following three sections see what
    defines the different elements and see examples of widgets that use
    them.

    The QStyle class description contains a list of these elements and
    their roles in styling widgets. We will see how they are used when
    we style individual widgets.

    \section3 Primitive Elements

    Primitive elements are GUI elements that are common and often used
    by several widgets. Examples of these are frames, button bevels,
    and arrows for spin boxes, scroll bars, and combo boxes.
    Primitive elements cannot exist on their own: they are always part
    of a larger construct. They take no part in the interaction with
    the user, but are passive decorations in the GUI.

    \section3 Control Elements

    A control element performs an action or displays information
    to the user. Examples of control elements are push buttons, check
    boxes, and header sections in tables and tree views. Control
    elements are not necessarily complete widgets such as push
    buttons, but can also be widget parts such as tab bar tabs and
    scroll bar sliders. They differ from primitive elements in that
    they are not passive, but fill a function in the interaction with
    the user. Controls that consist of several elements often use the
    style to calculate the bounding rectangles of the elements. The
    available sub elements are defined by the \l{QStyle::}{SubElement}
    enum. This enum is only used for calculating bounding rectangles,
    and sub elements are as such not graphical elements to be drawn
    like primitive, control, and complex elements.

    \section3 Complex Control Elements

    Complex control elements contain sub controls. Complex controls
    behave differently depending on where the user handles them with
    the mouse and which keyboard keys are pressed. This is dependent
    on which sub control (if any) that the mouse is over or received a
    mouse press. Examples of complex controls are scroll bars and
    combo boxes. With a scroll bar, you can use the mouse to move the
    slider and press the line up and line down buttons. The available
    sub controls are defined by the \l{QStyle}{SubControl} enum.

    In addition to drawing, the style needs to provide the widgets
    with information on which sub control (if any) a mouse press was
    made on. For instance, a QScrollBar needs to know if the user
    pressed the slider, the slider groove, or one of the buttons.

    Note that sub controls are not the same as the control elements
    described in the previous section. You cannot use the style to
    draw a sub control; the style will only calculate the bounding
    rectangle in which the sub control should be drawn. It is common,
    though, that complex elements use control and primitive elements
    to draw their sub controls, which is an approach that is
    frequently used by the built-in styles in Qt and also the Java
    style. For instance, the Java style uses PE_IndicatorCheckBox to
    draw the check box in group boxes (which is a sub control of
    CC_GroupBox). Some sub controls have an equivalent control element,
    e.g., the scroll bar slider (SC_SCrollBarSlider and
    CE_ScrollBarSlider).

    \section3 Other QStyle Tasks

    The style elements and widgets, as mentioned, use the style to
    calculate bounding rectangles of sub elements and sub controls,
    and pixel metrics, which is a style dependent size in screen
    pixels, for measures when drawing. The available rectangles and
    pixel metrics are represented by three enums in QStyle:
    \l{QStyle::}{SubElement}, \l{QStyle::}{SubControl}, and
    \l{QStyle::}{PixelMetric}. Values of the enums can easily by
    identified as they start with SE_, SC_ and PM_.

    The style also contain a set of style hints, which is
    represented as values in the \l{QStyle::}{StyleHint} enum. All
    widgets do not have the same functionality and look in the
    different styles. For instance, when the menu items in a menu do not
    fit in a single column on the screen, some styles support
    scrolling while others draw more than one column to fit all items.

    A style usually has a set of standard images (such as a warning, a
    question, and an error image) for message boxes, file dialogs,
    etc. QStyle provides the \l{QStyle::}{StandardPixmap} enum. Its
    values represent the standard images. Qt's widgets use these, so
    when you implement a custom style you should supply the images
    used by the style that is being implemented.

    The style calculates the spacing between widgets in layouts. There
    are two ways the style can handle these calculations. You can set
    the PM_LayoutHorizontalSpacing and PM_LayoutVerticalSpacing, which
    is the way the java style does it (through QCommonStyle).
    Alternatively, you can implement QStyle::layoutSpacing() and
    QStyle::layoutSpacingImplementation() if you need more control over 
    this part of the layout. In these functions you can calculate the
    spacing based on control types (QSizePolicy::ControlType) for
    different size policies (QSizePolicy::Policy) and also the style
    option for the widget in question.

    \section2 Style Options

    A style option (a class that inherit QStyleOption) stores
    parameters used by QStyle functions. The sub-classes of
    QStyleOption contain all information necessary to style the
    individual widgets. The style options keep public variables for
    performance reasons. Style options are filled out by the widgets.

    The widgets can be in a number of different states, which are
    defined by the \l{QStyle::}{State} enum. Some of the state flags have
    different meanings depending on the widget, but others are common
    for all widgets like State_Disabled. It is QStyleOption that sets
    the common states with QStyleOption::init(); the rest of the
    states are set by the individual widgets.

    Most notably, the style options contain the palette and bounding
    rectangles of the widgets to be drawn. Most widgets have
    specialized style options. QPushButton and QCheckBox, for
    instance, use QStyleOptionButton as style option, which contain
    the text, icon, and the size of their icon. The exact contents of
    all options are described when we go through individual widgets.

    \section2 QStyle Functions

    The QStyle class defines three functions for drawing the primitive,
    control, and complex elements:
    \l{QStyle::}{drawPrimitive()},
    \l{QStyle::}{drawControl()}, and
    \l{QStyle::}{drawComplexControl()}. The functions takes the
    following parameters:

    \list
        \o the enum value of the element to draw
        \o a QStyleOption which contains the information needed to
           draw the element.
        \o a QPainter with which to draw the element.
        \o a pointer to a QWidget, typically the widget
           that the element is painted on.
    \endlist

    Not all widgets send a pointer to themselves. If the style
    option sent to the function does not contain the information you
    need, you should check the widget implementation to see if it
    sends a pointer to itself.

    The QStyle class also provides helper functions that are used
    when drawing the elements. The \l{QStyle::}{drawItemText()}
    function draws text within a specified rectangle and taking a
    QPalette as a parameter. The \l{QStyle::}{drawItemPixmap()}
    function helps to align a pixmap within a specified bounding
    rectangle.

    Other QStyle functions do various calculations for the
    functions that draw. The widgets also use these functions for
    calculating size hints and also for bounding rectangle
    calculations if they draw several style elements themselves.
    As with the functions that draw elements the helper functions
    typically takes the same arguments.

    \list
        \o The \l{QStyle::}{subElementRect()} function takes a
        \l{QStyle::}{SubElement} enum value, and calculates a bounding
        rectangle for a sub element. The style uses this function to
        know where to draw the different parts of an element. This is
        mainly done for reuse. If you create a new style, you can use
        the same location of sub elements as the super class.

        \o The \l{QStyle::}{subControlRect()} function is used to
        calculate bounding rectangles for sub controls in complex
        controls. When you implement a new style, you reimplement \c
        subControlRect() and calculate the rectangles that are different
        from the super class.

        \o The \l{QStyle::}{pixelMetric()} function returns a pixel
        metric, which is a style dependent size given in screen
        pixels. It takes a value of the \l{QStyle::}{PixelMetric} enum
        and returns the correct measure. Note that pixel metrics do
        not necessarily have to be static measures, but can be
        calculated with, for example, the style option.

        \o The \l{QStyle::}{hitTestComplexControl()} function returns the
        sub control that the mouse pointer is over in a complex control.
        Usually, this is simply a matter of using
        \l{QStyle::}{subControlRect()} to get the bounding rectangles of
        the sub controls, and see which rectangle contains the position of
        the cursor.
    \endlist

    QStyle also have the functions \l{QStyle::}{polish()} and
    \l{QStyle::}{unpolish()}. All widgets are sent to the \c polish()
    function before being shown and to \c unpolish() when they
    are hidden. You can use these functions to set attributes on the
    widgets or do other work that is required by your style. For
    instance, if you need to know when the mouse is hovering over the
    widget, you need to set the \l{Qt::}{WA_Hover} widget attribute.
    The State_MouseOver state flag will then be set in the widget's