qt5base-lts/examples/widgets/doc/styles.qdoc
Andy Nichols fc924ae47e Doc: Fix snippet and example referencing widget examples
Widget examples were moved into a widgets subfolder, but
qdoc references were not updated.

Change-Id: Id2a4573e723745b9827c664c852807d6116f8f6d
Reviewed-by: Casper van Donderen <casper.vandonderen@nokia.com>
2012-08-23 11:20:37 +02:00

473 lines
20 KiB
Plaintext

/****************************************************************************
**
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** GNU Free Documentation License
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\example widgets/widgets/styles
\title Styles Example
The Styles example illustrates how to create custom widget
drawing styles using Qt, and demonstrates Qt's predefined styles.
\image styles-enabledwood.png Screenshot of the Styles example
A style in Qt is a subclass of QStyle or of one of its
subclasses. Styles perform drawing on behalf of widgets. Qt
provides a whole range of predefined styles, either built into
the \l QtGui library or found in plugins. Custom styles are
usually created by subclassing one of Qt's existing style and
reimplementing a few virtual functions.
In this example, the custom style is called \c NorwegianWoodStyle
and derives from QMotifStyle. Its main features are the wooden
textures used for filling most of the widgets and its round
buttons and comboboxes.
To implement the style, we use some advanced features provided by
QPainter, such as \l{QPainter::Antialiasing}{antialiasing} (to
obtain smoother button edges), \l{QColor::alpha()}{alpha blending}
(to make the buttons appeared raised or sunken), and
\l{QPainterPath}{painter paths} (to fill the buttons and draw the
outline). We also use many features of QBrush and QPalette.
The example consists of the following classes:
\list
\li \c NorwegianWoodStyle inherits from QMotifStyle and implements
the Norwegian Wood style.
\li \c WidgetGallery is a \c QDialog subclass that shows the most
common widgets and allows the user to switch style
dynamically.
\endlist
\section1 NorwegianWoodStyle Class Definition
Here's the definition of the \c NorwegianWoodStyle class:
\snippet widgets/widgets/styles/norwegianwoodstyle.h 0
The public functions are all declared in QStyle (QMotifStyle's
grandparent class) and reimplemented here to override the Motif
look and feel. The private functions are helper functions.
\section1 NorwegianWoodStyle Class Implementation
We will now review the implementation of the \c
NorwegianWoodStyle class.
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 0
The \c polish() function is reimplemented from QStyle. It takes a
QPalette as a reference and adapts the palette to fit the style.
Most styles don't need to reimplement that function. The
Norwegian Wood style reimplements it to set a "wooden" palette.
We start by defining a few \l{QColor}s that we'll need. Then we
load two PNG images. The \c : prefix in the file path indicates
that the PNG files are \l{The Qt Resource System}{embedded
resources}.
\table
\row \li \inlineimage widgets/styles/images/woodbackground.png
\li \b{woodbackground.png}
This texture is used as the background of most widgets.
The wood pattern is horizontal.
\row \li \inlineimage widgets/styles/images/woodbutton.png
\li \b{woodbutton.png}
This texture is used for filling push buttons and
comboboxes. The wood pattern is vertical and more reddish
than the texture used for the background.
\endtable
The \c midImage variable is initialized to be the same as \c
buttonImage, but then we use a QPainter and fill it with a 25%
opaque black color (a black with an \l{QColor::alpha()}{alpha
channel} of 63). The result is a somewhat darker image than \c
buttonImage. This image will be used for filling buttons that the
user is holding down.
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 1
We initialize the palette. Palettes have various
\l{QPalette::ColorRole}{color roles}, such as QPalette::Base
(used for filling text editors, item views, etc.), QPalette::Text
(used for foreground text), and QPalette::Background (used for
the background of most widgets). Each role has its own QBrush,
which usually is a plain color but can also be a brush pattern or
even a texture (a QPixmap).
In addition to the roles, palettes have several
\l{QPalette::ColorGroup}{color groups}: active, disabled, and
inactive. The active color group is used for painting widgets in
the active window. The disabled group is used for disabled
widgets. The inactive group is used for all other widgets. Most
palettes have identical active and inactive groups, while the
disabled group uses darker shades.
We initialize the QPalette object with a brown color. Qt
automatically derivates all color roles for all color groups from
that single color. We then override some of the default values. For
example, we use Qt::darkGreen instead of the default
(Qt::darkBlue) for the QPalette::Highlight role. The
QPalette::setBrush() overload that we use here sets the same
color or brush for all three color groups.
The \c setTexture() function is a private function that sets the
texture for a certain color role, while preserving the existing
color in the QBrush. A QBrush can hold both a solid color and a
texture at the same time. The solid color is used for drawing
text and other graphical elements where textures don't look good.
At the end, we set the brush for the disabled color group of the
palette. We use \c woodbackground.png as the texture for all
disabled widgets, including buttons, and use a darker color to
accompany the texture.
\image styles-disabledwood.png The Norwegian Wood style with disabled widgets
Let's move on to the other functions reimplemented from
QMotifStyle:
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 3
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 4
This QStyle::polish() overload is called once on every widget
drawn using the style. We reimplement it to set the Qt::WA_Hover
attribute on \l{QPushButton}s and \l{QComboBox}es. When this
attribute is set, Qt generates paint events when the mouse
pointer enters or leaves the widget. This makes it possible to
render push buttons and comboboxes differently when the mouse
pointer is over them.
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 5
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 6
This QStyle::unpolish() overload is called to undo any
modification done to the widget in \c polish(). For simplicity,
we assume that the flag wasn't set before \c polish() was called.
In an ideal world, we would remember the original state for each
widgets (e.g., using a QMap<QWidget *, bool>) and restore it in
\c unpolish().
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 7
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 8
The \l{QStyle::pixelMetric()}{pixelMetric()} function returns the
size in pixels for a certain user interface element. By
reimplementing this function, we can affect the way certain
widgets are drawn and their size hint. Here, we return 8 as the
width around a shown in a QComboBox, ensuring that there is
enough place around the text and the arrow for the Norwegian Wood
round corners. The default value for this setting in the Motif
style is 2.
We also change the extent of \l{QScrollBar}s, i.e., the height
for a horizontal scroll bar and the width for a vertical scroll
bar, to be 4 pixels more than in the Motif style. This makes the
style a bit more distinctive.
For all other QStyle::PixelMetric elements, we use the Motif
settings.
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 9
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 10
The \l{QStyle::styleHint()}{styleHint()} function returns some
hints to widgets or to the base style (in our case QMotifStyle)
about how to draw the widgets. The Motif style returns \c true
for the QStyle::SH_DitherDisabledText hint, resulting in a most
unpleasing visual effect. We override this behavior and return \c
false instead. We also return \c true for the
QStyle::SH_EtchDisabledText hint, meaning that disabled text is
rendered with an embossed look (as QWindowsStyle does).
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 11
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 12
The \l{QStyle::drawPrimitive()}{drawPrimitive()} function is
called by Qt widgets to draw various fundamental graphical
elements. Here we reimplement it to draw QPushButton and
QComboBox with round corners. The button part of these widgets is
drawn using the QStyle::PE_PanelButtonCommand primitive element.
The \c option parameter, of type QStyleOption, contains
everything we need to know about the widget we want to draw on.
In particular, \c option->rect gives the rectangle within which
to draw the primitive element. The \c painter parameter is a
QPainter object that we can use to draw on the widget.
The \c widget parameter is the widget itself. Normally, all the
information we need is available in \c option and \c painter, so
we don't need \c widget. We can use it to perform special
effects; for example, QMacStyle uses it to animate default
buttons. If you use it, be aware that the caller is allowed to
pass a null pointer.
We start by defining three \l{QColor}s that we'll need later on.
We also put the x, y, width, and height components of the
widget's rectangle in local variables. The value used for the \c
semiTransparentWhite and for the \c semiTransparentBlack color's
alpha channel depends on whether the mouse cursor is over the
widget or not. Since we set the Qt::WA_Hover attribute on
\l{QPushButton}s and \l{QComboBox}es, we can rely on the
QStyle::State_MouseOver flag to be set when the mouse is over the
widget.
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 13
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 14
The \c roundRect variable is a QPainterPath. A QPainterPath is is
a vectorial specification of a shape. Any shape (rectangle,
ellipse, spline, etc.) or combination of shapes can be expressed
as a path. We will use \c roundRect both for filling the button
background with a wooden texture and for drawing the outline. The
\c roundRectPath() function is a private function; we will come
back to it later.
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 15
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 16
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 17
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 18
We define two variables, \c brush and \c darker, and initialize
them based on the state of the button:
\list
\li If the button is a \l{QPushButton::flat}{flat button}, we use
the \l{QPalette::Background}{Background} brush. We set \c
darker to \c true if the button is
\l{QAbstractButton::down}{down} or
\l{QAbstractButton::checked}{checked}.
\li If the button is currently held down by the user or in the
\l{QAbstractButton::checked}{checked} state, we use the
\l{QPalette::Mid}{Mid} component of the palette. We set
\c darker to \c true if the button is
\l{QAbstractButton::checked}{checked}.
\li Otherwise, we use the \l{QPalette::Button}{Button} component
of the palette.
\endlist
The screenshot below illustrates how \l{QPushButton}s are
rendered based on their state:
\image styles-woodbuttons.png Norwegian Wood buttons in different states
To discover whether the button is flat or not, we need to cast
the \c option parameter to QStyleOptionButton and check if the
\l{QStyleOptionButton::features}{features} member specifies the
QStyleOptionButton::Flat flag. The qstyleoption_cast() function
performs a dynamic cast; if \c option is not a
QStyleOptionButton, qstyleoption_cast() returns a null pointer.
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 19
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 20
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 21
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 22
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 23
We turn on antialiasing on QPainter. Antialiasing is a technique
that reduces the visual distortion that occurs when the edges of
a shape are converted into pixels. For the Norwegian Wood style,
we use it to obtain smoother edges for the round buttons.
\image styles-aliasing.png Norwegian wood buttons with and without antialiasing
The first call to QPainter::fillPath() draws the background of
the button with a wooden texture. The second call to
\l{QPainter::fillPath()}{fillPath()} paints the same area with a
semi-transparent black color (a black color with an alpha channel
of 63) to make the area darker if \c darker is true.
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 24
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 25
Next, we draw the outline. The top-left half of the outline and
the bottom-right half of the outline are drawn using different
\l{QPen}s to produce a 3D effect. Normally, the top-left half of
the outline is drawn lighter whereas the bottom-right half is
drawn darker, but if the button is
\l{QAbstractButton::down}{down} or
\l{QAbstractButton::checked}{checked}, we invert the two
\l{QPen}s to give a sunken look to the button.
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 26
We draw the top-left part of the outline by calling
QPainter::drawPath() with an appropriate
\l{QPainter::setClipRegion()}{clip region}. If the
\l{QStyleOption::direction}{layout direction} is right-to-left
instead of left-to-right, we swap the \c x1, \c x2, \c x3, and \c
x4 variables to obtain correct results. On right-to-left desktop,
the "light" comes from the top-right corner of the screen instead
of the top-left corner; raised and sunken widgets must be drawn
accordingly.
The diagram below illustrates how 3D effects are drawn according
to the layout direction. The area in red on the diagram
corresponds to the \c topHalf polygon:
\image styles-3d.png
An easy way to test how a style looks in right-to-left mode is to
pass the \c -reverse command-line option to the application. This
option is recognized by the QApplication constructor.
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 32
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 33
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 34
The bottom-right part of the outline is drawn in a similar
fashion. Then we draw a one-pixel wide outline around the entire
button, using the \l{QPalette::Foreground}{Foreground} component
of the QPalette.
This completes the QStyle::PE_PanelButtonCommand case of the \c
switch statement. Other primitive elements are handled by the
base style. Let's now turn to the other \c NorwegianWoodStyle
member functions:
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 35
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 36
We reimplement QStyle::drawControl() to draw the text on a
QPushButton in a bright color when the button is
\l{QAbstractButton::down}{down} or
\l{QAbstractButton::checked}{checked}.
If the \c option parameter points to a QStyleOptionButton object
(it normally should), we take a copy of the object and modify its
\l{QStyleOption::palette}{palette} member to make the
QPalette::ButtonText be the same as the QPalette::BrightText
component (unless the widget is disabled).
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 37
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 38
The \c setTexture() function is a private function that sets the
\l{QBrush::texture()}{texture} component of the \l{QBrush}es for
a certain \l{QPalette::ColorRole}{color role}, for all three
\l{QPalette::ColorGroup}{color groups} (active, disabled,
inactive). We used it to initialize the Norwegian Wood palette in
\c polish(QPalette &).
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 39
\snippet widgets/widgets/styles/norwegianwoodstyle.cpp 40
The \c roundRectPath() function is a private function that
constructs a QPainterPath object for round buttons. The path
consists of eight segments: four arc segments for the corners and
four lines for the sides.
With around 250 lines of code, we have a fully functional custom
style based on one of the predefined styles. Custom styles can be
used to provide a distinct look to an application or family of
applications.
\section1 WidgetGallery Class
For completeness, we will quickly review the \c WidgetGallery
class, which contains the most common Qt widgets and allows the
user to change style dynamically. Here's the class definition:
\snippet widgets/widgets/styles/widgetgallery.h 0
\dots
\snippet widgets/widgets/styles/widgetgallery.h 1
Here's the \c WidgetGallery constructor:
\snippet widgets/widgets/styles/widgetgallery.cpp 0
We start by creating child widgets. The \uicontrol Style combobox is
initialized with all the styles known to QStyleFactory, in
addition to \c NorwegianWood. The \c create...() functions are
private functions that set up the various parts of the \c
WidgetGallery.
\snippet widgets/widgets/styles/widgetgallery.cpp 1
\snippet widgets/widgets/styles/widgetgallery.cpp 2
We connect the \uicontrol Style combobox to the \c changeStyle()
private slot, the \uicontrol{Use style's standard palette} check box to
the \c changePalette() slot, and the \uicontrol{Disable widgets} check
box to the child widgets'
\l{QWidget::setDisabled()}{setDisabled()} slot.
\snippet widgets/widgets/styles/widgetgallery.cpp 3
\snippet widgets/widgets/styles/widgetgallery.cpp 4
Finally, we put the child widgets in layouts.
\snippet widgets/widgets/styles/widgetgallery.cpp 5
\snippet widgets/widgets/styles/widgetgallery.cpp 6
When the user changes the style in the combobox, we call
QApplication::setStyle() to dynamically change the style of the
application.
\snippet widgets/widgets/styles/widgetgallery.cpp 7
\snippet widgets/widgets/styles/widgetgallery.cpp 8
If the user turns the \uicontrol{Use style's standard palette} on, the
current style's \l{QStyle::standardPalette()}{standard palette}
is used; otherwise, the system's default palette is honored.
For the Norwegian Wood style, this makes no difference because we
always override the palette with our own palette in \c
NorwegianWoodStyle::polish().
\snippet widgets/widgets/styles/widgetgallery.cpp 9
\snippet widgets/widgets/styles/widgetgallery.cpp 10
The \c advanceProgressBar() slot is called at regular intervals
to advance the progress bar. Since we don't know how long the
user will keep the Styles application running, we use a
logarithmic formula: The closer the progress bar gets to 100%,
the slower it advances.
We will review \c createProgressBar() in a moment.
\snippet widgets/widgets/styles/widgetgallery.cpp 11
\snippet widgets/widgets/styles/widgetgallery.cpp 12
The \c createTopLeftGroupBox() function creates the QGroupBox
that occupies the top-left corner of the \c WidgetGallery. We
skip the \c createTopRightGroupBox(), \c
createBottomLeftTabWidget(), and \c createBottomRightGroupBox()
functions, which are very similar.
\snippet widgets/widgets/styles/widgetgallery.cpp 13
In \c createProgressBar(), we create a QProgressBar at the bottom
of the \c WidgetGallery and connect its
\l{QTimer::timeout()}{timeout()} signal to the \c
advanceProgressBar() slot.
*/