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

     2 **

     3 ** Copyright (C) 2009 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     \example widgets/styles

    44     \title Styles Example

    45 

    46     The Styles example illustrates how to create custom widget

    47     drawing styles using Qt, and demonstrates Qt's predefined styles.

    48 

    49     \image styles-enabledwood.png Screenshot of the Styles example

    50 

    51     A style in Qt is a subclass of QStyle or of one of its

    52     subclasses. Styles perform drawing on behalf of widgets. Qt

    53     provides a whole range of predefined styles, either built into

    54     the \l QtGui library or found in plugins. Custom styles are

    55     usually created by subclassing one of Qt's existing style and

    56     reimplementing a few virtual functions.

    57 

    58     In this example, the custom style is called \c NorwegianWoodStyle

    59     and derives from QMotifStyle. Its main features are the wooden

    60     textures used for filling most of the widgets and its round

    61     buttons and comboboxes.

    62 

    63     To implement the style, we use some advanced features provided by

    64     QPainter, such as \l{QPainter::Antialiasing}{antialiasing} (to

    65     obtain smoother button edges), \l{QColor::alpha()}{alpha blending}

    66     (to make the buttons appeared raised or sunken), and

    67     \l{QPainterPath}{painter paths} (to fill the buttons and draw the

    68     outline). We also use many features of QBrush and QPalette.

    69 

    70     The example consists of the following classes:

    71 

    72     \list

    73     \o \c NorwegianWoodStyle inherits from QMotifStyle and implements

    74         the Norwegian Wood style.

    75     \o \c WidgetGallery is a \c QDialog subclass that shows the most

    76        common widgets and allows the user to switch style

    77        dynamically.

    78     \endlist

    79 

    80     \section1 NorwegianWoodStyle Class Definition

    81 

    82     Here's the definition of the \c NorwegianWoodStyle class:

    83 

    84     \snippet examples/widgets/styles/norwegianwoodstyle.h 0

    85 

    86     The public functions are all declared in QStyle (QMotifStyle's

    87     grandparent class) and reimplemented here to override the Motif

    88     look and feel. The private functions are helper functions.

    89 

    90     \section1 NorwegianWoodStyle Class Implementation

    91 

    92     We will now review the implementation of the \c

    93     NorwegianWoodStyle class.

    94 

    95     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 0

    96 

    97     The \c polish() function is reimplemented from QStyle. It takes a

    98     QPalette as a reference and adapts the palette to fit the style.

    99     Most styles don't need to reimplement that function. The

   100     Norwegian Wood style reimplements it to set a "wooden" palette.

   101 

   102     We start by defining a few \l{QColor}s that we'll need. Then we

   103     load two PNG images. The \c : prefix in the file path indicates

   104     that the PNG files are \l{The Qt Resource System}{embedded

   105     resources}.

   106 

   107     \table

   108     \row \o \inlineimage widgets/styles/images/woodbackground.png

   109 

   110          \o \bold{woodbackground.png}

   111 

   112             This texture is used as the background of most widgets.

   113             The wood pattern is horizontal.

   114 

   115     \row \o \inlineimage widgets/styles/images/woodbutton.png

   116 

   117          \o \bold{woodbutton.png}

   118 

   119             This texture is used for filling push buttons and

   120             comboboxes. The wood pattern is vertical and more reddish

   121             than the texture used for the background.

   122     \endtable

   123 

   124     The \c midImage variable is initialized to be the same as \c

   125     buttonImage, but then we use a QPainter and fill it with a 25%

   126     opaque black color (a black with an \l{QColor::alpha()}{alpha

   127     channel} of 63). The result is a somewhat darker image than \c

   128     buttonImage. This image will be used for filling buttons that the

   129     user is holding down.

   130 

   131     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 1

   132 

   133     We initialize the palette. Palettes have various

   134     \l{QPalette::ColorRole}{color roles}, such as QPalette::Base

   135     (used for filling text editors, item views, etc.), QPalette::Text

   136     (used for foreground text), and QPalette::Background (used for

   137     the background of most widgets). Each role has its own QBrush,

   138     which usually is a plain color but can also be a brush pattern or

   139     even a texture (a QPixmap).

   140 

   141     In addition to the roles, palettes have several

   142     \l{QPalette::ColorGroup}{color groups}: active, disabled, and

   143     inactive. The active color group is used for painting widgets in

   144     the active window. The disabled group is used for disabled

   145     widgets. The inactive group is used for all other widgets. Most

   146     palettes have identical active and inactive groups, while the

   147     disabled group uses darker shades.

   148 

   149     We initialize the QPalette object with a brown color. Qt

   150     automatically derivates all color roles for all color groups from

   151     that single color. We then override some of the default values. For

   152     example, we use Qt::darkGreen instead of the default

   153     (Qt::darkBlue) for the QPalette::Highlight role. The

   154     QPalette::setBrush() overload that we use here sets the same

   155     color or brush for all three color groups.

   156 

   157     The \c setTexture() function is a private function that sets the

   158     texture for a certain color role, while preserving the existing

   159     color in the QBrush. A QBrush can hold both a solid color and a

   160     texture at the same time. The solid color is used for drawing

   161     text and other graphical elements where textures don't look good.

   162 

   163     At the end, we set the brush for the disabled color group of the

   164     palette. We use \c woodbackground.png as the texture for all

   165     disabled widgets, including buttons, and use a darker color to

   166     accompany the texture.

   167 

   168     \image styles-disabledwood.png The Norwegian Wood style with disabled widgets

   169 

   170     Let's move on to the other functions reimplemented from

   171     QMotifStyle:

   172 

   173     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 3

   174     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 4

   175 

   176     This QStyle::polish() overload is called once on every widget

   177     drawn using the style. We reimplement it to set the Qt::WA_Hover

   178     attribute on \l{QPushButton}s and \l{QComboBox}es. When this

   179     attribute is set, Qt generates paint events when the mouse

   180     pointer enters or leaves the widget. This makes it possible to

   181     render push buttons and comboboxes differently when the mouse

   182     pointer is over them.

   183 

   184     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 5

   185     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 6

   186 

   187     This QStyle::unpolish() overload is called to undo any

   188     modification done to the widget in \c polish(). For simplicity,

   189     we assume that the flag wasn't set before \c polish() was called.

   190     In an ideal world, we would remember the original state for each

   191     widgets (e.g., using a QMap<QWidget *, bool>) and restore it in

   192     \c unpolish().

   193 

   194     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 7

   195     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 8

   196 

   197     The \l{QStyle::pixelMetric()}{pixelMetric()} function returns the

   198     size in pixels for a certain user interface element. By

   199     reimplementing this function, we can affect the way certain

   200     widgets are drawn and their size hint. Here, we return 8 as the

   201     width around a shown in a QComboBox, ensuring that there is

   202     enough place around the text and the arrow for the Norwegian Wood

   203     round corners. The default value for this setting in the Motif

   204     style is 2.

   205 

   206     We also change the extent of \l{QScrollBar}s, i.e., the height

   207     for a horizontal scroll bar and the width for a vertical scroll

   208     bar, to be 4 pixels more than in the Motif style. This makes the

   209     style a bit more distinctive.

   210 

   211     For all other QStyle::PixelMetric elements, we use the Motif

   212     settings.

   213 

   214     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 9

   215     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 10

   216 

   217     The \l{QStyle::styleHint()}{styleHint()} function returns some

   218     hints to widgets or to the base style (in our case QMotifStyle)

   219     about how to draw the widgets. The Motif style returns \c true

   220     for the QStyle::SH_DitherDisabledText hint, resulting in a most

   221     unpleasing visual effect. We override this behavior and return \c

   222     false instead. We also return \c true for the

   223     QStyle::SH_EtchDisabledText hint, meaning that disabled text is

   224     rendered with an embossed look (as QWindowsStyle does).

   225 

   226     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 11

   227     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 12

   228 

   229     The \l{QStyle::drawPrimitive()}{drawPrimitive()} function is

   230     called by Qt widgets to draw various fundamental graphical

   231     elements. Here we reimplement it to draw QPushButton and

   232     QComboBox with round corners. The button part of these widgets is

   233     drawn using the QStyle::PE_PanelButtonCommand primitive element.

   234 

   235     The \c option parameter, of type QStyleOption, contains

   236     everything we need to know about the widget we want to draw on.

   237     In particular, \c option->rect gives the rectangle within which

   238     to draw the primitive element. The \c painter parameter is a

   239     QPainter object that we can use to draw on the widget.

   240 

   241     The \c widget parameter is the widget itself. Normally, all the

   242     information we need is available in \c option and \c painter, so

   243     we don't need \c widget. We can use it to perform special

   244     effects; for example, QMacStyle uses it to animate default

   245     buttons. If you use it, be aware that the caller is allowed to

   246     pass a null pointer.

   247 

   248     We start by defining three \l{QColor}s that we'll need later on.

   249     We also put the x, y, width, and height components of the

   250     widget's rectangle in local variables. The value used for the \c

   251     semiTransparentWhite and for the \c semiTransparentBlack color's

   252     alpha channel depends on whether the mouse cursor is over the

   253     widget or not. Since we set the Qt::WA_Hover attribute on

   254     \l{QPushButton}s and \l{QComboBox}es, we can rely on the

   255     QStyle::State_MouseOver flag to be set when the mouse is over the

   256     widget.

   257 

   258     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 13

   259     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 14

   260 

   261     The \c roundRect variable is a QPainterPath. A QPainterPath is is

   262     a vectorial specification of a shape. Any shape (rectangle,

   263     ellipse, spline, etc.) or combination of shapes can be expressed

   264     as a path. We will use \c roundRect both for filling the button

   265     background with a wooden texture and for drawing the outline. The

   266     \c roundRectPath() function is a private function; we will come

   267     back to it later.

   268 

   269     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 15

   270     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 16

   271     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 17

   272     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 18

   273 

   274     We define two variables, \c brush and \c darker, and initialize

   275     them based on the state of the button:

   276 

   277     \list

   278     \o If the button is a \l{QPushButton::flat}{flat button}, we use

   279        the \l{QPalette::Background}{Background} brush. We set \c

   280        darker to \c true if the button is

   281        \l{QAbstractButton::down}{down} or

   282        \l{QAbstractButton::checked}{checked}.

   283     \o If the button is currently held down by the user or in the

   284        \l{QAbstractButton::checked}{checked} state, we use the

   285        \l{QPalette::Mid}{Mid} component of the palette. We set

   286        \c darker to \c true if the button is

   287        \l{QAbstractButton::checked}{checked}.

   288     \o Otherwise, we use the \l{QPalette::Button}{Button} component

   289        of the palette.

   290     \endlist

   291 

   292     The screenshot below illustrates how \l{QPushButton}s are

   293     rendered based on their state:

   294 

   295     \image styles-woodbuttons.png Norwegian Wood buttons in different states

   296 

   297     To discover whether the button is flat or not, we need to cast

   298     the \c option parameter to QStyleOptionButton and check if the

   299     \l{QStyleOptionButton::features}{features} member specifies the

   300     QStyleOptionButton::Flat flag. The qstyleoption_cast() function

   301     performs a dynamic cast; if \c option is not a

   302     QStyleOptionButton, qstyleoption_cast() returns a null pointer.

   303 

   304     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 19

   305     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 20

   306     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 21

   307     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 22

   308     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 23

   309 

   310     We turn on antialiasing on QPainter. Antialiasing is a technique

   311     that reduces the visual distortion that occurs when the edges of

   312     a shape are converted into pixels. For the Norwegian Wood style,

   313     we use it to obtain smoother edges for the round buttons.

   314 

   315     \image styles-aliasing.png Norwegian wood buttons with and without antialiasing

   316 

   317     The first call to QPainter::fillPath() draws the background of

   318     the button with a wooden texture. The second call to

   319     \l{QPainter::fillPath()}{fillPath()} paints the same area with a

   320     semi-transparent black color (a black color with an alpha channel

   321     of 63) to make the area darker if \c darker is true.

   322 

   323     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 24

   324     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 25

   325 

   326     Next, we draw the outline. The top-left half of the outline and

   327     the bottom-right half of the outline are drawn using different

   328     \l{QPen}s to produce a 3D effect. Normally, the top-left half of

   329     the outline is drawn lighter whereas the bottom-right half is

   330     drawn darker, but if the button is

   331     \l{QAbstractButton::down}{down} or

   332     \l{QAbstractButton::checked}{checked}, we invert the two

   333     \l{QPen}s to give a sunken look to the button.

   334 

   335     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 26

   336 

   337     We draw the top-left part of the outline by calling

   338     QPainter::drawPath() with an appropriate

   339     \l{QPainter::setClipRegion()}{clip region}. If the

   340     \l{QStyleOption::direction}{layout direction} is right-to-left

   341     instead of left-to-right, we swap the \c x1, \c x2, \c x3, and \c

   342     x4 variables to obtain correct results. On right-to-left desktop,

   343     the "light" comes from the top-right corner of the screen instead

   344     of the top-left corner; raised and sunken widgets must be drawn

   345     accordingly.

   346 

   347     The diagram below illustrates how 3D effects are drawn according

   348     to the layout direction. The area in red on the diagram

   349     corresponds to the \c topHalf polygon:

   350 

   351     \image styles-3d.png

   352 

   353     An easy way to test how a style looks in right-to-left mode is to

   354     pass the \c -reverse command-line option to the application. This

   355     option is recognized by the QApplication constructor.

   356 

   357     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 32

   358     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 33

   359     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 34

   360 

   361     The bottom-right part of the outline is drawn in a similar

   362     fashion. Then we draw a one-pixel wide outline around the entire

   363     button, using the \l{QPalette::Foreground}{Foreground} component

   364     of the QPalette.

   365 

   366     This completes the QStyle::PE_PanelButtonCommand case of the \c

   367     switch statement. Other primitive elements are handled by the

   368     base style. Let's now turn to the other \c NorwegianWoodStyle

   369     member functions:

   370 

   371     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 35

   372     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 36

   373 

   374     We reimplement QStyle::drawControl() to draw the text on a

   375     QPushButton in a bright color when the button is

   376     \l{QAbstractButton::down}{down} or

   377     \l{QAbstractButton::checked}{checked}.

   378 

   379     If the \c option parameter points to a QStyleOptionButton object

   380     (it normally should), we take a copy of the object and modify its

   381     \l{QStyleOption::palette}{palette} member to make the

   382     QPalette::ButtonText be the same as the QPalette::BrightText

   383     component (unless the widget is disabled).

   384 

   385     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 37

   386     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 38

   387 

   388     The \c setTexture() function is a private function that sets the

   389     \l{QBrush::texture()}{texture} component of the \l{QBrush}es for

   390     a certain \l{QPalette::ColorRole}{color role}, for all three

   391     \l{QPalette::ColorGroup}{color groups} (active, disabled,

   392     inactive). We used it to initialize the Norwegian Wood palette in

   393     \c polish(QPalette &).

   394 

   395     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 39

   396     \snippet examples/widgets/styles/norwegianwoodstyle.cpp 40

   397 

   398     The \c roundRectPath() function is a private function that

   399     constructs a QPainterPath object for round buttons. The path

   400     consists of eight segments: four arc segments for the corners and

   401     four lines for the sides.

   402 

   403     With around 250 lines of code, we have a fully functional custom

   404     style based on one of the predefined styles. Custom styles can be

   405     used to provide a distinct look to an application or family of

   406     applications.

   407 

   408     \section1 WidgetGallery Class

   409 

   410     For completeness, we will quickly review the \c WidgetGallery

   411     class, which contains the most common Qt widgets and allows the

   412     user to change style dynamically. Here's the class definition:

   413 

   414     \snippet examples/widgets/styles/widgetgallery.h 0

   415     \dots

   416     \snippet examples/widgets/styles/widgetgallery.h 1

   417 

   418     Here's the \c WidgetGallery constructor:

   419 

   420     \snippet examples/widgets/styles/widgetgallery.cpp 0

   421 

   422     We start by creating child widgets. The \gui Style combobox is

   423     initialized with all the styles known to QStyleFactory, in

   424     addition to \c NorwegianWood. The \c create...() functions are

   425     private functions that set up the various parts of the \c

   426     WidgetGallery.

   427 

   428     \snippet examples/widgets/styles/widgetgallery.cpp 1

   429     \snippet examples/widgets/styles/widgetgallery.cpp 2

   430 

   431     We connect the \gui Style combobox to the \c changeStyle()

   432     private slot, the \gui{Use style's standard palette} check box to

   433     the \c changePalette() slot, and the \gui{Disable widgets} check

   434     box to the child widgets'

   435     \l{QWidget::setDisabled()}{setDisabled()} slot.

   436 

   437     \snippet examples/widgets/styles/widgetgallery.cpp 3

   438     \snippet examples/widgets/styles/widgetgallery.cpp 4

   439 

   440     Finally, we put the child widgets in layouts.

   441 

   442     \snippet examples/widgets/styles/widgetgallery.cpp 5

   443     \snippet examples/widgets/styles/widgetgallery.cpp 6

   444 

   445     When the user changes the style in the combobox, we call

   446     QApplication::setStyle() to dynamically change the style of the

   447     application.

   448 

   449     \snippet examples/widgets/styles/widgetgallery.cpp 7

   450     \snippet examples/widgets/styles/widgetgallery.cpp 8

   451 

   452     If the user turns the \gui{Use style's standard palette} on, the

   453     current style's \l{QStyle::standardPalette()}{standard palette}

   454     is used; otherwise, the system's default palette is honored.

   455 

   456     For the Norwegian Wood style, this makes no difference because we

   457     always override the palette with our own palette in \c

   458     NorwegianWoodStyle::polish().

   459 

   460     \snippet examples/widgets/styles/widgetgallery.cpp 9

   461     \snippet examples/widgets/styles/widgetgallery.cpp 10

   462 

   463     The \c advanceProgressBar() slot is called at regular intervals

   464     to advance the progress bar. Since we don't know how long the

   465     user will keep the Styles application running, we use a

   466     logarithmic formula: The closer the progress bar gets to 100%,

   467     the slower it advances.

   468 

   469     We will review \c createProgressBar() in a moment.

   470 

   471     \snippet examples/widgets/styles/widgetgallery.cpp 11

   472     \snippet examples/widgets/styles/widgetgallery.cpp 12

   473 

   474     The \c createTopLeftGroupBox() function creates the QGroupBox

   475     that occupies the top-left corner of the \c WidgetGallery. We

   476     skip the \c createTopRightGroupBox(), \c

   477     createBottomLeftTabWidget(), and \c createBottomRightGroupBox()

   478     functions, which are very similar.

   479 

   480     \snippet examples/widgets/styles/widgetgallery.cpp 13

   481 

   482     In \c createProgressBar(), we create a QProgressBar at the bottom

   483     of the \c WidgetGallery and connect its

   484     \l{QTimer::timeout()}{timeout()} signal to the \c

   485     advanceProgressBar() slot.

   486 */