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

**

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

**

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

/*!

    \group appearance

    \title Widget Appearance and Style

    \brief Classes used for customizing UI appearance and style.

*/

/*!

    \page style-reference.html

    \title Implementing Styles and Style Aware Widgets

    \brief An overview of styles and the styling of widgets.

    \ingroup frameworks-technologies

    \previouspage Widget Classes

    \contentspage Widgets and Layouts

    \nextpage {Qt Style Sheets}{Style sheets}

    Styles (classes that inherit QStyle) draw on behalf of widgets

    and encapsulate the look and feel of a GUI. 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.

    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.

    \tableofcontents

    \section1 Classes for Widget Styling

    These classes are used to customize an application's appearance and

    style.

    \annotatedlist appearance

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

    When a widget asks a style to draw an element, it provides the style

    with a QStyleOption, which is a class that contains the information

    necessary for drawing. Thanks to QStyleOption, it is possible to make

    QStyle draw widgets without linking in any code for the widget. This

    makes it possible to use \l{QStyle}'s draw functions on any paint

    device. Ie you can draw a combobox on any widget, not just on a

    QComboBox.

    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.

    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

    The sub-classes of QStyleOption contain all information necessary

    to style the individual elements. Style options are instantiated - 

    usually on the stack - and filled out by the caller of the QStyle

    function. Depending on what is drawn the style will expect

    different a different style option class. For example, the

    QStyle::PE_FrameFocusRect element expects a QStyleOptionFocusRect

    argument, and it's possible to create custom subclasses that a

    custom style can use. The style options keep public variables

    for performance reasons.

    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::initFrom(); 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.

    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

    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

    \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

    style options.

    QStyle has a few static helper functions that do some common and

    difficult tasks. They can calculate the position of a slider

    handle from the value of the slider and transform rectangles

    and draw text considering reverse layouts; see the QStyle

    class documentation for more details.

    The usual approach when one reimplements QStyle virtual

    functions is to do work on elements that are different from the

    super class; for all other elements, you can simply use the super

    class implementation.

    \section2 The Palette

    Each style provides a color - that is, QBrush - palette that

    should be used for drawing the widgets. There is one set of colors

    for the different widget states (QPalette::ColorGroup): active

    (widgets in the window that has keyboard focus), inactive (widgets

    used for other windows), and disabled (widgets that are set

    disabled). The states can be found by querying the State_Active

    and State_Enabled state flags. Each set contains color certain

    roles given by the QPalette::ColorRole enum. The roles describe in

    which situations the colors should be used (e.g., for painting

    widget backgrounds, text, or buttons).

    How the color roles are used is up to the style. For instance, if

    the style uses gradients, one can use a palette color and make it

    darker or lighter with QColor::darker() and QColor::lighter() to

    create the gradient. In general, if you need a brush that is not

    provided by the palette, you should try to derive it from one.

    QPalette, which provides the palette, stores colors for

    different widget states and color roles. The palette for a style

    is returned by \l{QStyle::}{standardPalette()}. The standard

    palette is not installed automatically when a new style is set

    on the application (QApplication::setStyle()) or widget

    (QWidget::setStyle()), so you must set the palette yourself

    with (QApplication::setPalette()) or (QWidget::setPalette()).

    It is not recommended to hard code colors as applications and

    individual widgets can set their own palette and also use the

    styles palette for drawing. Note that none of Qt's widgets set

    their own palette. The java style does hard code some colors, but

    its author looks past this in silence. Of course, it is not

    intended that the style should look good with any palette.

    \section2 Implementation Issues

    When you implement styles, there are several issues to

    consider. We will give some hints and advice on implementation

    here.

    When implementing styles, it is necessary to look through the

    code of the widgets and code of the base class and its ancestors.

    This is because the widgets use the style differently, because the

    implementation in the different styles virtual functions can

    affect the state of the drawing (e.g., by altering the QPainter

    state without restoring it and drawing some elements without using

    the appropriate pixel metrics and sub elements).

    It is recommended that the styles do not alter the proposed size

    of widgets with the QStyle::sizeFromContents() function but let

    the QCommonStyle implementation handle it. If changes need to be

    made, you should try to keep them small; application development

    may be difficult if the layout of widgets looks considerably

    different in the various styles.

    We recommend using the QPainter directly for drawing, i.e., not

    use pixmaps or images. This makes it easier for the style conform

    to the palette (although you can set your own color table on a

    QImage with \l{QImage::}{setColorTable()}).

    It is, naturally, possible to draw elements without using the

    style to draw the sub elements as intended by Qt. This is

    discouraged as custom widgets may depend on these sub elements to

    be implemented correctly. The widget walkthrough shows how Qt

    uses the sub elements.

    \section1 Java Style

    We have implemented a style that resembles the Java default look

    and feel (previously known as Metal). We have done this as it is

    relatively simple to implement and we wanted to build a style for

    this overview document. To keep it simple and not to extensive, we

    have simplified the style somewhat, but Qt is perfectly able to

    make an exact copy of the style. However, there are no concrete

    plans to implement the style as a part of Qt.

    In this section we will have a look at some implementation

    issues. Finally, we will see a complete example on the styling of

    a Java widget. We will continue to use the java style

    throughout the document for examples and widget images. The

    implementation itself is somewhat involved, and it is not

    intended that you should read through it.

    \section2 Design and Implementation

    The first step in designing the style was to select the base

    class. We chose to subclass QWindowsStyle. This class implements

    most of the functionality we need other than performing the actual

    drawing. Also, windows and java share layout of sub controls for

    several of the complex controls (which reduces the amount of code

    required considerably).

    The style is implemented in one class. We have done this

    because we find it convenient to keep all code in one file. Also,

    it is an advantage with regards to optimization as we instantiate

    less objects. We also keep the number of functions at a minimum by

    using switches to identify which element to draw in the functions.

    This results in large functions, but since we divide the code for

    each element in the switches, the code should still be easy to

    read.

    \section2 Limitations and Differences from Java

    We have not fully implemented every element in the Java style.

    This way, we have reduced the amount and complexity of the code.

    In general, the style was intended as a practical example for

    this style overview document, and not to be a part of Qt

    itself.

    Not all widgets have every state implemented. This goes for

    states that are common, e.g., State_Disabled. Each state is,

    however, implemented for at least one widget.

    We have only implemented ticks below the slider. Flat push

    buttons are also left out. We do not handle the case where the

    title bars and dock window titles grows to small for their

    contents, but simply draw sub controls over each other.

    We have not tried to emulate the Java fonts. Java and Qt use very

    different font engines, so we don't consider it worth the effort