1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the documentation of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*!

    43     \group appearance

    44     \title Widget Appearance and Style

    45     \brief Classes used for customizing UI appearance and style.

    46 */

    47 

    48 /*!

    49     \page style-reference.html

    50     \title Implementing Styles and Style Aware Widgets

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

    52 

    53     \ingroup frameworks-technologies

    54 

    55     \previouspage Widget Classes

    56     \contentspage Widgets and Layouts

    57     \nextpage {Qt Style Sheets}{Style sheets}

    58 

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

    60     and encapsulate the look and feel of a GUI. The QStyle class is

    61     an abstract base class that encapsulates the look and feel of a

    62     GUI. Qt's built-in widgets use it to perform nearly all of their

    63     drawing, ensuring that they look exactly like the equivalent

    64     native widgets.

    65 

    66     Several styles are built into Qt (e.g., windows style and motif style).

    67     Other styles are only available on specific platforms (such as

    68     the windows XP style). Custom styles are made available as plugins

    69     or by creating an instance of the style class in an application and

    70     setting it with QApplication::setStyle().

    71 

    72     To implement a new style, you inherit one of Qt's existing styles

    73     - the one most resembling the style you want to create - and

    74     reimplement a few virtual functions. This process is somewhat

    75     involved, and we therefore provide this overview. We give a

    76     step-by-step walkthrough of how to style individual Qt widgets.

    77     We will examine the QStyle virtual functions, member variables,

    78     and enumerations.

    79 

    80     The part of this document that does not concern the styling of

    81     individual widgets is meant to be read sequentially because later

    82     sections tend to depend on earlier ones. The description of the

    83     widgets can be used for reference while implementing a style.

    84     However, you may need to consult the Qt source code in some cases.

    85     The sequence in the styling process should become clear after

    86     reading this document, which will aid you in locating relevant code.

    87 

    88     To develop style aware widgets (i.e., widgets that conform to

    89     the style in which they are drawn), you need to draw them using the

    90     current style. This document shows how widgets draw themselves

    91     and which possibilities the style gives them.

    92 

    93     \tableofcontents

    94 

    95     \section1 Classes for Widget Styling

    96 

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

    98     style.

    99 

   100     \annotatedlist appearance

   101 

   102     \section1 The QStyle implementation

   103 

   104     The API of QStyle contains functions that draw the widgets, static

   105     helper functions to do common and difficult tasks (e.g.,

   106     calculating the position of slider handles) and functions to do

   107     the various calculations necessary while drawing (e.g., for the

   108     widgets to calculate their size hints). The style also help some

   109     widgets with the layout of their contents. In addition, it creates

   110     a QPalette that contains \l{QBrush}es to draw with.

   111 

   112     QStyle draws graphical elements; an element is a widget or a

   113     widget part like a push button bevel, a window frame, or a scroll

   114     bar. Most draw functions now take four arguments:

   115 

   116     \list

   117     \o an enum value specifying which graphical element to draw

   118     \o a QStyleOption specifying how and where to render that element

   119     \o a QPainter that should be used to draw the element

   120     \o a QWidget on which the drawing is performed (optional)

   121     \endlist

   122 

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

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

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

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

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

   128     device, i.e., you can draw a combobox on any widget, not just on a

   129     QComboBox.

   130 

   131     The widget is passed as the last argument in case the style needs

   132     it to perform special effects (such as animated default buttons on

   133     Mac OS X), but it isn't mandatory.

   134 

   135     We will in the course of this section look at the style elements,

   136     the style options, and the functions of QStyle. Finally, we describe

   137     how the palette is used.

   138 

   139     Items in item views is drawn by \l{Delegate Classes}{delegates} in

   140     Qt. The item view headers are still drawn by the style. Qt's

   141     default delegate, QStyledItemDelegate, draws its items partially

   142     through the current style; it draws the check box indicators and

   143     calculate bounding rectangles for the elements of which the item

   144     consists. In this document, we only describe how to implement a

   145     QStyle subclass. If you wish to add support for other datatypes

   146     than those supported by the QStyledItemDelegate, you need to

   147     implement a custom delegate. Note that delegates must be set

   148     programmatically for each individual widget (i.e., default

   149     delegates cannot be provided as plugins).

   150 

   151     \section2 The Style Elements

   152 

   153     A style element is a graphical part of a GUI. A widget consists

   154     of a hierarchy (or tree) of style elements. For instance, when a

   155     style receives a request to draw a push button (from QPushButton,

   156     for example), it draws a label (text and icon), a button bevel,

   157     and a focus frame. The button bevel, in turn, consists of a frame

   158     around the bevel and two other elements, which we will look at

   159     later. Below is a conceptual illustration of the push button

   160     element tree. We will see the actual tree for QPushButton when we

   161     go through the individual widgets.

   162 

   163     \image javastyle/conceptualpushbuttontree.png

   164 

   165     Widgets are not necessarily drawn by asking the style to draw

   166     only one element. Widgets can make several calls to the style to

   167     draw different elements. An example is QTabWidget, which draws its

   168     tabs and frame individually.

   169 

   170     There are three element types: primitive elements, control

   171     elements, and complex control elements. The elements are defined

   172     by the \l{QStyle::}{ComplexControl}, \l{QStyle::}{ControlElement},

   173     and \l{QStyle::}{PrimitiveElement} enums. The values of

   174     each element enum has a prefix to identify their type: \c{CC_} for

   175     complex elements, \c{CE_} for control elements, and \c{PE_} for

   176     primitive elements. We will in the following three sections see what

   177     defines the different elements and see examples of widgets that use

   178     them.

   179 

   180     The QStyle class description contains a list of these elements and

   181     their roles in styling widgets. We will see how they are used when

   182     we style individual widgets.

   183 

   184     \section3 Primitive Elements

   185 

   186     Primitive elements are GUI elements that are common and often used

   187     by several widgets. Examples of these are frames, button bevels,

   188     and arrows for spin boxes, scroll bars, and combo boxes.

   189     Primitive elements cannot exist on their own: they are always part

   190     of a larger construct. They take no part in the interaction with

   191     the user, but are passive decorations in the GUI.

   192 

   193     \section3 Control Elements

   194 

   195     A control element performs an action or displays information

   196     to the user. Examples of control elements are push buttons, check

   197     boxes, and header sections in tables and tree views. Control

   198     elements are not necessarily complete widgets such as push

   199     buttons, but can also be widget parts such as tab bar tabs and

   200     scroll bar sliders. They differ from primitive elements in that

   201     they are not passive, but fill a function in the interaction with

   202     the user. Controls that consist of several elements often use the

   203     style to calculate the bounding rectangles of the elements. The

   204     available sub elements are defined by the \l{QStyle::}{SubElement}

   205     enum. This enum is only used for calculating bounding rectangles,

   206     and sub elements are as such not graphical elements to be drawn

   207     like primitive, control, and complex elements.

   208 

   209     \section3 Complex Control Elements

   210 

   211     Complex control elements contain sub controls. Complex controls

   212     behave differently depending on where the user handles them with

   213     the mouse and which keyboard keys are pressed. This is dependent

   214     on which sub control (if any) that the mouse is over or received a

   215     mouse press. Examples of complex controls are scroll bars and

   216     combo boxes. With a scroll bar, you can use the mouse to move the

   217     slider and press the line up and line down buttons. The available

   218     sub controls are defined by the \l{QStyle}{SubControl} enum.

   219 

   220     In addition to drawing, the style needs to provide the widgets

   221     with information on which sub control (if any) a mouse press was

   222     made on. For instance, a QScrollBar needs to know if the user

   223     pressed the slider, the slider groove, or one of the buttons.

   224 

   225     Note that sub controls are not the same as the control elements

   226     described in the previous section. You cannot use the style to

   227     draw a sub control; the style will only calculate the bounding

   228     rectangle in which the sub control should be drawn. It is common,

   229     though, that complex elements use control and primitive elements

   230     to draw their sub controls, which is an approach that is

   231     frequently used by the built-in styles in Qt and also the Java

   232     style. For instance, the Java style uses PE_IndicatorCheckBox to

   233     draw the check box in group boxes (which is a sub control of

   234     CC_GroupBox). Some sub controls have an equivalent control element,

   235     e.g., the scroll bar slider (SC_SCrollBarSlider and

   236     CE_ScrollBarSlider).

   237 

   238     \section3 Other QStyle Tasks

   239 

   240     The style elements and widgets, as mentioned, use the style to

   241     calculate bounding rectangles of sub elements and sub controls,

   242     and pixel metrics, which is a style dependent size in screen

   243     pixels, for measures when drawing. The available rectangles and

   244     pixel metrics are represented by three enums in QStyle:

   245     \l{QStyle::}{SubElement}, \l{QStyle::}{SubControl}, and

   246     \l{QStyle::}{PixelMetric}. Values of the enums can easily by

   247     identified as they start with SE_, SC_ and PM_.

   248 

   249     The style also contain a set of style hints, which is

   250     represented as values in the \l{QStyle::}{StyleHint} enum. All

   251     widgets do not have the same functionality and look in the

   252     different styles. For instance, when the menu items in a menu do not

   253     fit in a single column on the screen, some styles support

   254     scrolling while others draw more than one column to fit all items.

   255 

   256     A style usually has a set of standard images (such as a warning, a

   257     question, and an error image) for message boxes, file dialogs,

   258     etc. QStyle provides the \l{QStyle::}{StandardPixmap} enum. Its

   259     values represent the standard images. Qt's widgets use these, so

   260     when you implement a custom style you should supply the images

   261     used by the style that is being implemented.

   262 

   263     The style calculates the spacing between widgets in layouts. There

   264     are two ways the style can handle these calculations. You can set

   265     the PM_LayoutHorizontalSpacing and PM_LayoutVerticalSpacing, which

   266     is the way the java style does it (through QCommonStyle).

   267     Alternatively, you can implement QStyle::layoutSpacing() and

   268     QStyle::layoutSpacingImplementation() if you need more control over 

   269     this part of the layout. In these functions you can calculate the

   270     spacing based on control types (QSizePolicy::ControlType) for

   271     different size policies (QSizePolicy::Policy) and also the style

   272     option for the widget in question.

   273 

   274     \section2 Style Options

   275 

   276     The sub-classes of QStyleOption contain all information necessary

   277     to style the individual elements. Style options are instantiated - 

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

   279     function. Depending on what is drawn the style will expect

   280     different a different style option class. For example, the

   281     QStyle::PE_FrameFocusRect element expects a QStyleOptionFocusRect

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

   283     custom style can use. The style options keep public variables

   284     for performance reasons.

   285 

   286     The widgets can be in a number of different states, which are

   287     defined by the \l{QStyle::}{State} enum. Some of the state flags have

   288     different meanings depending on the widget, but others are common

   289     for all widgets like State_Disabled. It is QStyleOption that sets

   290     the common states with QStyleOption::initFrom(); the rest of the

   291     states are set by the individual widgets.

   292 

   293     Most notably, the style options contain the palette and bounding

   294     rectangles of the widgets to be drawn. Most widgets have

   295     specialized style options. QPushButton and QCheckBox, for

   296     instance, use QStyleOptionButton as style option, which contain

   297     the text, icon, and the size of their icon. The exact contents of

   298     all options are described when we go through individual widgets.

   299 

   300     When reimplementing QStyle functions that take a

   301     QStyleOption parameter, you often need to cast the

   302     QStyleOption to a subclass (e.g., QStyleOptionFocusRect). For

   303     safety, you can use qstyleoption_cast() to ensure that the

   304     pointer type is correct. If the object isn't of the right type,

   305     qstyleoption_cast() returns 0. For example:

   306 

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

   308 

   309     The following code snippet illustrates how to use QStyle to

   310     draw the focus rectangle from a custom widget's paintEvent():

   311 

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

   313 

   314     The next example shows how to derive from an existing style to

   315     customize the look of a graphical element:

   316 

   317     \snippet doc/src/snippets/customstyle/customstyle.h 0

   318     \codeline

   319     \snippet doc/src/snippets/customstyle/customstyle.cpp 2

   320     \snippet doc/src/snippets/customstyle/customstyle.cpp 3

   321     \snippet doc/src/snippets/customstyle/customstyle.cpp 4

   322 

   323     \section2 QStyle Functions

   324 

   325     The QStyle class defines three functions for drawing the primitive,

   326     control, and complex elements:

   327     \l{QStyle::}{drawPrimitive()},

   328     \l{QStyle::}{drawControl()}, and

   329     \l{QStyle::}{drawComplexControl()}. The functions takes the

   330     following parameters:

   331 

   332     \list

   333         \o the enum value of the element to draw

   334         \o a QStyleOption which contains the information needed to

   335            draw the element.

   336         \o a QPainter with which to draw the element.

   337         \o a pointer to a QWidget, typically the widget

   338            that the element is painted on.

   339     \endlist

   340 

   341     Not all widgets send a pointer to themselves. If the style

   342     option sent to the function does not contain the information you

   343     need, you should check the widget implementation to see if it

   344     sends a pointer to itself.

   345 

   346     The QStyle class also provides helper functions that are used

   347     when drawing the elements. The \l{QStyle::}{drawItemText()}

   348     function draws text within a specified rectangle and taking a

   349     QPalette as a parameter. The \l{QStyle::}{drawItemPixmap()}

   350     function helps to align a pixmap within a specified bounding

   351     rectangle.

   352 

   353     Other QStyle functions do various calculations for the

   354     functions that draw. The widgets also use these functions for

   355     calculating size hints and also for bounding rectangle

   356     calculations if they draw several style elements themselves.

   357     As with the functions that draw elements the helper functions

   358     typically takes the same arguments.

   359 

   360     \list

   361         \o The \l{QStyle::}{subElementRect()} function takes a

   362         \l{QStyle::}{SubElement} enum value, and calculates a bounding

   363         rectangle for a sub element. The style uses this function to

   364         know where to draw the different parts of an element. This is

   365         mainly done for reuse. If you create a new style, you can use

   366         the same location of sub elements as the super class.

   367 

   368         \o The \l{QStyle::}{subControlRect()} function is used to

   369         calculate bounding rectangles for sub controls in complex

   370         controls. When you implement a new style, you reimplement \c

   371         subControlRect() and calculate the rectangles that are different

   372         from the super class.

   373 

   374         \o The \l{QStyle::}{pixelMetric()} function returns a pixel

   375         metric, which is a style dependent size given in screen

   376         pixels. It takes a value of the \l{QStyle::}{PixelMetric} enum

   377         and returns the correct measure. Note that pixel metrics do

   378         not necessarily have to be static measures, but can be

   379         calculated with, for example, the style option.

   380 

   381         \o The \l{QStyle::}{hitTestComplexControl()} function returns the

   382         sub control that the mouse pointer is over in a complex control.

   383         Usually, this is simply a matter of using

   384         \l{QStyle::}{subControlRect()} to get the bounding rectangles of

   385         the sub controls, and see which rectangle contains the position of

   386         the cursor.

   387     \endlist

   388 

   389     QStyle also have the functions \l{QStyle::}{polish()} and

   390     \l{QStyle::}{unpolish()}. All widgets are sent to the \c polish()

   391     function before being shown and to \c unpolish() when they

   392     are hidden. You can use these functions to set attributes on the

   393     widgets or do other work that is required by your style. For

   394     instance, if you need to know when the mouse is hovering over the

   395     widget, you need to set the \l{Qt::}{WA_Hover} widget attribute.

   396     The State_MouseOver state flag will then be set in the widget's

   397     style options.

   398 

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

   400     difficult tasks. They can calculate the position of a slider

   401     handle from the value of the slider and transform rectangles

   402     and draw text considering reverse layouts; see the QStyle

   403     class documentation for more details.

   404 

   405     The usual approach when one reimplements QStyle virtual

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

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

   408     class implementation.

   409 

   410     \section2 The Palette

   411 

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

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

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

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

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

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

   418     and State_Enabled state flags. Each set contains color certain

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

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

   421     widget backgrounds, text, or buttons).

   422 

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

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

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

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

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

   428 

   429     QPalette, which provides the palette, stores colors for

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

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

   432     palette is not installed automatically when a new style is set

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

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

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

   436 

   437     It is not recommended to hard code colors as applications and

   438     individual widgets can set their own palette and also use the

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

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

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

   442     intended that the style should look good with any palette.

   443 

   444     \section2 Implementation Issues

   445 

   446     When you implement styles, there are several issues to

   447     consider. We will give some hints and advice on implementation

   448     here.

   449 

   450     When implementing styles, it is necessary to look through the

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

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

   453     implementation in the different styles virtual functions can

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

   455     state without restoring it and drawing some elements without using

   456     the appropriate pixel metrics and sub elements).

   457 

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

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

   460     the QCommonStyle implementation handle it. If changes need to be

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

   462     may be difficult if the layout of widgets looks considerably

   463     different in the various styles.

   464 

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

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

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

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

   469 

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

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

   472     discouraged as custom widgets may depend on these sub elements to

   473     be implemented correctly. The widget walkthrough shows how Qt

   474     uses the sub elements.

   475 

   476     \section1 Java Style

   477 

   478     We have implemented a style that resembles the Java default look

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

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

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

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

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

   484     plans to implement the style as a part of Qt.

   485 

   486     In this section we will have a look at some implementation

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

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

   489     throughout the document for examples and widget images. The

   490     implementation itself is somewhat involved, and it is not

   491     intended that you should read through it.

   492 

   493     \section2 Design and Implementation

   494 

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

   496     class. We chose to subclass QWindowsStyle. This class implements

   497     most of the functionality we need other than performing the actual

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

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

   500     required considerably).

   501 

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

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

   504     it is an advantage with regards to optimization as we instantiate

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

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

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

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

   509     read.

   510 

   511     \section2 Limitations and Differences from Java

   512 

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

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

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

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

   517     itself.

   518 

   519     Not all widgets have every state implemented. This goes for

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

   521     however, implemented for at least one widget.

   522 

   523     We have only implemented ticks below the slider. Flat push

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

   525     title bars and dock window titles grows to small for their

   526     contents, but simply draw sub controls over each other.

   527 

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

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

   530     as we only use the style as an example for this overview.

   531 

   532     We have hardcoded the colors (we don't use the QPalette) for

   533     the linear gradients, which are used, for example, for button

   534     bevels, tool bars, and check boxes. This is because the Java

   535     palette cannot produce these colors. Java does not change these

   536     colors based on widget color group or role anyway (they are not

   537     dependent on the palette), so it does not present a problem in any

   538     case.

   539 

   540     It is Qt's widgets that are styled. Some widgets do not exist

   541     at all in Java, e.g., QToolBox. Others contain elements that the

   542     Java widgets don't. The tree widget is an example of the latter in

   543     which Java's JTree does not have a header.

   544 

   545     The style does not handle reverse layouts. We assume that the

   546     layout direction is left to right. QWindowsStyle handles reverse

   547     widgets; if we implemented reverse layouts, widgets that we change

   548     the position of sub elements, or handle text alignment in labels

   549     our selves would need to be updated.

   550 

   551     \section2 Styling Java Check Boxes

   552 

   553     As an example, we will examine the styling of check boxes in the

   554     java style. We describe the complete process and print all code in

   555     both the java style and Qt classes involved. In the rest of this

   556     document, we will not examine the source code of the individual

   557     widgets. Hopefully, this will give you an idea on how to search

   558     through the code if you need to check specific implementation

   559     details; most widgets follow the same structure as the check

   560     boxes. We have edited the QCommonStyle code somewhat to remove

   561     code that is not directly relevant for check box styling.

   562  

   563     We start with a look at how QCheckBox builds it style option,

   564     which is QStyleOptionButton for checkboxes:

   565 

   566     \snippet doc/src/snippets/code/doc_src_styles.qdoc 0

   567 

   568     First we let QStyleOption set up the option with the information

   569     that is common for all widgets with \c initFrom().  We will look at

   570     this shortly.

   571 

   572     The down boolean is true when the user press the box down; this is

   573     true whether the box is checked or not of the checkbox.  The

   574     State_NoChange state is set when we have a tristate checkbox and

   575     it is partially checked. It has State_On if the box is checked and

   576     State_Off if it is unchecked. State_MouseOver is set if the mouse

   577     hovers over the checkbox and the widget has attribute Qt::WA_Hover

   578     set - you set this in QStyle::polish(). In addition, the style

   579     option also contains the text, icon, and icon size of the button.

   580 

   581     \l{QStyleOption::}{initFrom()} sets up the style option with the

   582     attributes that are common for all widgets. We print its

   583     implementation here:

   584 

   585     \snippet doc/src/snippets/code/doc_src_styles.qdoc 1

   586 

   587     The State_Enabled is set when the widget is enabled. When the

   588     widget has focus the State_HasFocus flag is set. Equally, the

   589     State_Active flag is set when the widget is a child of the active

   590     window. The State_MouseOver will only be set if the widget has

   591     the WA_HoverEnabled windows flag set. Notice that keypad

   592     navigation must be enabled in Qt for the State_HasEditFocus to

   593     be included; it is not included by default.

   594 

   595     In addition to setting state flags the QStyleOption contains

   596     other information about the widget: \c direction is the layout

   597     direction of the layout, \c rect is the bounding rectangle of the

   598     widget (the area in which to draw), \c palette is the QPalette

   599     that should be used for drawing the widget, and \c fontMetrics is

   600     the metrics of the font that is used by the widget.

   601 

   602     We give an image of a checkbox and the style option to match

   603     it.

   604 

   605     \image javastyle/checkboxexample.png A java style checkbox

   606 

   607     The above checkbox will have the following state flags in its

   608     style option:

   609 

   610     \table 90%

   611     \header

   612         \o State flag

   613         \o Set

   614     \row

   615         \o State_Sunken

   616         \o Yes

   617     \row

   618         \o State_NoChange

   619         \o No

   620     \row

   621         \o State_On

   622         \o Yes

   623     \row

   624         \o State_Off

   625         \o No

   626     \row

   627         \o State_MouseOver

   628         \o Yes

   629     \row

   630         \o State_Enabled

   631         \o Yes

   632     \row

   633         \o State_HasFocus

   634         \o Yes

   635     \row

   636         \o State_KeyboardFocusChange

   637         \o No

   638     \row

   639         \o State_Active

   640         \o Yes

   641     \endtable

   642 

   643     The QCheckBox paints itself in QWidget::paintEvent() with

   644     style option \c opt and QStylePainter \c p. The QStylePainter

   645     class is a convenience class to draw style elements. Most

   646     notably, it wraps the methods in QStyle used for painting. The

   647     QCheckBox draws itself as follows:

   648 

   649     \snippet doc/src/snippets/code/doc_src_styles.qdoc 2

   650 

   651     QCommonStyle handles the CE_CheckBox element. The QCheckBox

   652     has two sub elements: SE_CheckBoxIndicator (the checked indicator)

   653     and SE_CheckBoxContents (the contents, which is used for the

   654     checkbox label). QCommonStyle also implements these sub element

   655     bounding rectangles. We have a look at the QCommonStyle code:

   656 

   657     \snippet doc/src/snippets/code/doc_src_styles.qdoc 3

   658 

   659     As can be seen from the code extract, the common style gets

   660     the bounding rectangles of the two sub elements of

   661     CE_CheckBox, and then draws them. If the checkbox has focus,

   662     the focus frame is also drawn.

   663 

   664     The java style draws CE_CheckBoxIndicator, while QCommonStyle

   665     handles CE_CheckboxLabel. We will examine each implementation and

   666     start with CE_CheckBoxLabel:

   667 

   668     \snippet doc/src/snippets/code/doc_src_styles.qdoc 4

   669 

   670     \l{QStyle::}{visualAlignment()} adjusts the alignment of text

   671     according to the layout direction. We then draw an icon if it

   672     exists, and adjust the space left for the text.

   673     \l{QStyle::}{drawItemText()} draws the text taking alignment,

   674     layout direction, and the mnemonic into account. It also uses the

   675     palette to draw the text in the right color.

   676 

   677     The drawing of labels often get somewhat involved. Luckily, it

   678     can usually be handled by the base class. The java style

   679     implements its own push button label since Java-contrary to

   680     windows-center button contents also when the button has an icon.

   681     You can examine that implementation if you need an example of

   682     reimplementing label drawing.

   683 

   684     We take a look at the java implementation

   685     of CE_CheckBoxIndicator in \c drawControl():

   686 

   687     \snippet doc/src/snippets/javastyle.cpp 0

   688 

   689     We first save the state of the painter. This is not always

   690     necessary but in this case the QWindowsStyle needs the painter in

   691     the same state as it was when PE_IndicatorCheckBox was called (We

   692     could also set the state with function calls, of course). We then

   693     use \c drawButtonBackground() to draw the background of the check

   694     box indicator. This is a helper function that draws the background

   695     and also the frame of push buttons and check boxes. We take a look

   696     at that function below. We then check if the mouse is hovering

   697     over the checkbox. If it is, we draw the frame java checkboxes

   698     have when the box is not pressed down and the mouse is over it.

   699     You may note that java does not handle tristate boxes, so we have

   700     not implemented it.

   701 

   702     Here we use a png image for our indicator. We could also check

   703     here if the widget is disabled. We would then have to use

   704     another image with the indicator in the disabled color.

   705 

   706     \snippet doc/src/snippets/javastyle.cpp 1

   707 

   708     We have seen how check boxes are styled in the java style from the

   709     widget gets a paint request to the style is finished painting. To

   710     learn in detail how each widget is painted, you need to go through

   711     the code step-by-step as we have done here.  However, it is

   712     usually enough to know which style elements the widgets draw. The

   713     widget builds a style option and calls on the style one or more

   714     times to draw the style elements of which it consists. Usually,

   715     it is also sufficient to know the states a widget can be in and the

   716     other contents of the style option, i.e., what we list in the next

   717     section.

   718 

   719     \section1 Widget Walkthrough

   720 

   721     In this section, we will examine how most of Qt's widgets are

   722     styled.  Hopefully, this will save you some time and effort while

   723     developing your own styles and widgets. You will not find

   724     information here that is not attainable elsewhere (i.e., by

   725     examining the source code or the class descriptions for the style

   726     related classes).

   727 

   728     We mostly use java style widgets as examples. The java style does not

   729     draw every element in the element trees. This is because they are

   730     not visible for that widget in the java style. We still make sure

   731     that all elements are implemented in a way that conforms with the

   732     java style as custom widgets might need them (this does not

   733     exclude leaving implementations to QWindowsStyle though).

   734 

   735     The following is given for each widget:

   736 

   737     \list

   738         \o A table with the members (variables, etc.) of its style option.

   739         \o A table over the state flags (QStyle::StateFlag) that

   740            can be set on the widget and when the states are set.

   741         \o Its element tree (see section \l{The Style Elements}).

   742         \o An image of the widget in which the elements are outlined.

   743         \omit This is not written yet - probably never will be

   744               either

   745         \o List of style hints that should be checked for the

   746            widget.

   747         \o List of standard pixmaps that could be used by the

   748            elements.

   749         \endomit

   750     \endlist

   751 

   752     The element tree contains the primitive, control, and complex

   753     style elements. By doing a top-down traversal of the element tree,

   754     you get the sequence in which the elements should be drawn. In the

   755     nodes, we have written the sub element rectangles, sub control

   756     elements, and pixel metrics that should be considered when drawing

   757     the element of the node.

   758 

   759     Our approach on styling center on the drawing of the widgets. The

   760     calculations of sub elements rectangles, sub controls, and pixel

   761     metrics used \bold during drawing is only listed as contents in

   762     the element trees. Note that there are rectangles and pixel

   763     metrics that are only used by widgets. This leaves these

   764     calculations untreated in the walkthrough. For instance, the

   765     \l{QStyle::}{subControlRect()} and

   766     \l{QStyle::}{sizeFromContents()} functions often call

   767     \l{QStyle::}{subElementRect()} to calculate their bounding

   768     rectangles. We could draw trees for this as well. However, how

   769     these calculations are done is completely up to the individual

   770     styles, and they do not have to follow a specific structure (Qt

   771     does not impose a specific structure). You should still make sure

   772     that you use the appropriate pixel metrics, though. To limit the

   773     size of the document, we have therefore chosen not to include

   774     trees or describe the calculations made by the Java (or any other)

   775     style.

   776 

   777     You may be confused about how the different pixel metrics, sub

   778     element rectangles, and sub control rectangles should be used when

   779     examining the trees. If you are in doubt after reading the QStyle

   780     enum descriptions, we suggest that you examine the QCommonStyle

   781     and QWindowsStyle implementations.

   782 

   783     Some of the bounding rectangles that we outline in the widget

   784     images are equal. Reasons for this are that some elements draw

   785     backgrounds while others draw frames and labels. If in doubt,

   786     check the description of each element in QStyle. Also, some

   787     elements are there to layout, i.e., decide where to draw, other

   788     elements.

   789 

   790     \section2 Common Widget Properties

   791 

   792     Some states and variables are common for all widgets. These are

   793     set with QStyleOption::initFrom(). Not all elements use this function;

   794     it is the widgets that create the style options, and for some

   795     elements the information from \l{QStyleOption::}{initFrom()} is not

   796     necessary.

   797 

   798     A table with the common states follows:

   799 

   800     \table 90%

   801         \header

   802             \o State

   803             \o State Set When

   804         \row

   805             \o State_Enabled

   806             \o Set if the widget is not disabled (see

   807                QWidget::setEnabled())

   808         \row

   809             \o State_Focus

   810             \o Set if the widget has focus (see

   811                QWidget::hasFocus())

   812         \row

   813             \o State_KeyobordFocusChange

   814             \o Set when the user changes focus with the keyboard

   815                (see Qt::WA_KeyboardFocusChange)

   816         \row

   817             \o State_MouseOver

   818             \o Set if the mouse cursor is over the widget

   819         \row

   820             \o State_Active

   821             \o Set if the widget is a child of the active window.

   822         \row

   823             \o State_HasEditFocus

   824             \o Set if the widget has the edit focus

   825     \endtable

   826 

   827     The other common members for widgets are:

   828 

   829     \table 90%

   830         \header

   831             \o Member

   832             \o Content

   833         \row

   834             \o rect

   835             \o The bounding rectangle of the element to draw. This

   836                is set to the widget bounding rectangle

   837                (QWidget::rect()).

   838         \row

   839             \o direction

   840             \o The layout direction; a value of the

   841                Qt::LayoutDirection enum.

   842         \row

   843             \o palette

   844             \o The QPalette to use when drawing the element. This

   845                is set to the widgets palette (QWidget::palette()).

   846         \row

   847             \o fontMetrics

   848             \o The QFontMetrics to use when drawing text on the

   849                widget.

   850     \endtable

   851 

   852     The complex style options (classes that inherit

   853     QStyleOptionComplex) used for complex style elements share two

   854     variables: \l{QStyleOptionComplex::}{subControls} and

   855     \l{QStyleOptionComplex::}{activeSubControls}. Both variables are

   856     an OR'ed combination of QStyle::SubControl enum values. They

   857     indicate which sub controls the complex control consists of and

   858     which of these controls are currently active.

   859 

   860     As mentioned, the style calculates the size of the widgets

   861     contents, which the widgets calculate their size hints from. In

   862     addition, complex controls also use the style to test which

   863     sub-controls the mouse is over. 

   864 

   865     \section2 Widget Reference

   866 

   867     Without further delay, we present the widget walkthrough; each

   868     widget has its own sub-section.

   869 

   870     \section3 Push Buttons

   871 

   872     The style structure for push buttons is shown below. By doing a

   873     top-down traversal of the tree, you get the sequence in which the

   874     elements should be drawn.

   875 

   876     \image javastyle/pushbutton.png The style structure for push buttons

   877 

   878     The layout of the buttons, with regard element bounds, varies from

   879     style to style. This makes it difficult to show conceptual images

   880     of this. Also, elements may - even be intended to - have the same

   881     bounds; the PE_PushButtonBevel, for instance, is used in

   882     QCommonStyle to draw the elements that contains it:

   883     PE_FrameDefaultButton, PE_FrameButtonBevel, and

   884     PE_PanelButtonCommand, all of which have the same bounds in common

   885     and windows style.  PE_PushButtonBevel is also responsible for

   886     drawing the menu indicator (QCommonStyle draws

   887     PE_IndicatorArrowDown).

   888 

   889     An image of a push button in the java style that show the bounding

   890     rectangles of the elements is given below. Colors are used to

   891     separate the bounding rectangles in the image; they do not fill

   892     any other purpose. This is also true for similar images for the

   893     other widgets.

   894 

   895     \image javastyle/button.png

   896 

   897     The java style, as well as all other styles implemented in Qt,

   898     does not use PE_FrameButtonBevel. It is usual that a button

   899     with a PE_DefaultFrame adjusts the PE_PanelButtonCommand's

   900     rectangle by PM_ButtonDefaultIndicator. The CE_PushButtonLabel

   901     is found by adjusting the rect by PM_DefaultFrameWidth.

   902 

   903     We will now examine the style option for push

   904     buttons - QStyleOptionButton. A table for the states that

   905     QPushButton can set on the style option follows:

   906 

   907     \table 90%

   908         \header

   909             \o State

   910             \o State Set When

   911         \row

   912             \o State_Sunken

   913             \o Button is down or menu is pressed shown

   914         \row

   915             \o State_On

   916             \o Button is checked

   917         \row

   918             \o State_Raised

   919             \o Button is not flat and not pressed down

   920     \endtable

   921 

   922     Other members of QStyleOptionButton is:

   923 

   924     \table 90%

   925         \header

   926             \o Member

   927             \o Content

   928         \row

   929             \o features

   930             \o Flags of the QStyleOptionButton::ButtonFeatures enum,

   931                which describes various button properties (see enum)

   932         \row

   933             \o icon

   934             \o The buttons QIcon (if any)

   935         \row

   936             \o iconSize

   937             \o The QSize of the icon

   938         \row

   939             \o text

   940             \o a QString with the buttons text

   941     \endtable

   942 

   943     \section3 Check and Radio Buttons

   944 

   945     The structures for radio and check buttons are identical.

   946     We show the structure using QCheckBox element and pixel

   947     metric names:

   948 

   949     \image javastyle/checkbox.png

   950 

   951     QStyleOptionButton is used as the style option for both check

   952     and radio buttons. We first give a table of the states that

   953     can be set in the option:

   954 

   955     \table 90%

   956         \header

   957             \o State

   958             \o State Set When

   959         \row

   960             \o State_sunken

   961             \o The box is pressed down

   962         \row

   963             \o State_NoChange

   964             \o The box is partially checked (for tristate

   965                checkboxes.)

   966         \row

   967             \o State_On

   968             \o The box is checked

   969         \row

   970             \o State_Off

   971             \o The box is unchecked

   972     \endtable

   973 

   974     See \l{Push Buttons} for a table over other members in the

   975     QStyleOptionButtonClass.

   976 

   977     \section3 Tabs

   978 

   979     In Qt, QTabBar uses the style to draw its tabs. Tabs exist either

   980     in a QTabWidget, which contains a QTabBar, or as a separate bar.

   981     If the bar is not part of a tab widget, it draws its own base.

   982 

   983     QTabBar lays out the tabs, so the style does not have control over

   984     tab placement. However, while laying out its tabs, the bar asks

   985     the style for PM_TabBarTabHSpace and PM_TabBarTabVSpace, which is

   986     extra width and height over the minimum size of the tab bar tab

   987     label (icon and text). The style can also further influence the

   988     tab size before it is laid out, as the tab bar asks for

   989     CT_TabBarTab. The bounding rectangle of the bar is decided by the

   990     tab widget when it is part of the widget (still considering

   991     CT_TabBarTab).

   992 

   993     The tab bar is responsible for drawing the buttons that appear on

   994     the tab bar when all tabs do not fit. Their placement is not

   995     controlled by the style, but the buttons are \l{QToolButton}s

   996     and are therefore drawn by the style.

   997 

   998     Here is the style structure for QTabWidget and QTabBar:

   999 

  1000     \image javastyle/tab.png

  1001 

  1002     The dotted lines indicate that the QTabWidget contains a tab bar,

  1003     but does not draw it itself, that QTabBar only draws its base line

  1004     when not part of a tab widget, and that the tab bar keeps two tool

  1005     buttons that scroll the bar when all tabs do not fit; see \l{Tool

  1006     Buttons} for their element tree. Also note that since the buttons

  1007     are children of the tab bar, they are drawn after the bar. The

  1008     tabs bounding rectangles overlap the base by PM_TabBarBaseOverlap.

  1009 

  1010     Here is a tab widget in the java style:

  1011 

  1012     \image javastyle/tabwidget.png

  1013 

  1014     In the java style (and also windows), the tab bar shape and label

  1015     have the same bounding rectangle as CE_TabBarTab. Notice that the

  1016     tabs overlap with the tab widget frame. The base of the tab bar

  1017     (if drawn) is the area where the tabs and frame overlap.

  1018 

  1019     The style option for tabs (QStyleOptionTab) contains the necessary

  1020     information for drawing tabs. The option contains the position of

  1021     the tab in the tab bar, the position of the selected tab, the

  1022     shape of the tab, the text, and icon. After Qt 4.1 the option

  1023     should be cast to a QStyleOptionTabV2, which also contains the

  1024     icons size.

  1025 

  1026     As the java style tabs don't overlap, we also present an image of

  1027     a tab widget in the windows style. Note that if you want the tabs

  1028     to overlap horizontally, you do that when drawing the tabs in

  1029     CE_TabBarTabShape; the tabs bounding rectangles will not be

  1030     altered by the tab bar. The tabs are drawn from left to right in a

  1031     north tab bar shape, top to bottom in an east tab bar shape, etc.

  1032     The selected tab is drawn last, so that it is easy to draw it over

  1033     the other tabs (if it is to be bigger).

  1034 

  1035     \image javastyle/windowstabimage.png

  1036 

  1037     A table of the states a tab bar can set on its tabs follows:

  1038 

  1039     \table 90%

  1040         \header

  1041             \o State

  1042             \o State Set When

  1043         \row

  1044             \o State_Sunken

  1045             \o The tab is pressed on with the mouse.

  1046         \row

  1047             \o State_Selected

  1048             \o If it is the current tab.

  1049         \row

  1050             \o State_HasFocus

  1051             \o The tab bar has focus and the tab is selected

  1052     \endtable

  1053 

  1054     Note that individual tabs may be disabled even if the tab bar

  1055     is not. The tab will be active if the tab bar is active.

  1056 

  1057     Here follows a table of QStyleOptionTabV2's members:

  1058 

  1059     \table 90%

  1060         \header

  1061             \o Member

  1062             \o Content

  1063         \row

  1064             \o cornerWidgets

  1065             \o Is flags of the CornerWidget enum, which indicate

  1066                if and which corner widgets the tab bar has.

  1067         \row

  1068             \o icon

  1069             \o The QIcon of the tab

  1070         \row

  1071             \o iconSize

  1072             \o The QSize of the icon

  1073         \row

  1074             \o position

  1075             \o A TabPosition enum value that indicates the tabs

  1076                position on the bar relative to the other tabs.

  1077         \row

  1078             \o row

  1079             \o holds which row the tab is in

  1080         \row

  1081             \o selectedPosition

  1082             \o A value of the SelectedPosition enum that indicates

  1083                whether the selected tab is adjacent to or is the

  1084                tab.

  1085         \row

  1086             \o shape

  1087             \o A value of the QTabBar::Shape enum indication

  1088                whether the tab has rounded or triangular corners

  1089                and the orientation of the tab.

  1090         \row

  1091             \o text

  1092             \o The tab text

  1093     \endtable

  1094 

  1095     The frame for tab widgets use QStyleOptionTabWidgetFrame as

  1096     style option. We list its members here. It does not have

  1097     states set besides the common flags.

  1098 

  1099     \table 90%

  1100         \header

  1101             \o Member

  1102             \o content

  1103         \row

  1104             \o leftCornerWidgetSize

  1105             \o The QSize of the left corner widget (if any).

  1106         \row

  1107             \o rightCornerWidgetSize

  1108             \o The QSize of the right corner widget (if any).

  1109         \row

  1110             \o lineWidth

  1111             \o holds the line with for drawing the panel.

  1112         \row

  1113             \o midLineWith

  1114             \o this value is currently always 0.

  1115         \row

  1116             \o shape

  1117             \o The shape of the tabs on the tab bar.

  1118         \row

  1119             \o tabBarSize

  1120             \o The QSize of the tab bar.

  1121     \endtable

  1122 

  1123     \section3 Scroll Bars

  1124 

  1125     Here is the style structure for scrollBars:

  1126 

  1127     \image javastyle/scrollbar.png

  1128 

  1129     QScrollBar simply creates its style option and then draws

  1130     CC_ScrollBar. Some styles draw the background of add page and sub

  1131     page with PE_PanelButtonBevel and also use indicator arrows to

  1132     draw the arrows in the nest and previous line indicators; we have

  1133     not included these in the tree as their use is up to the

  1134     individual style. The style's PM_MaximumDragDistance is the

  1135     maximum distance in pixels the mouse can move from the bounds