Style docs & snippets: remove references to QWindowsStyle

QWindowsStyle is being made internal. Use either QProxyStyle for
customizing existing styles or QCommonStyle to implement full custom
styles.

Change-Id: Ic81696abc61a3c012a3775efc0b4fba2e1dab4bb
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>
This commit is contained in:
J-P Nurmi 2012-11-27 18:06:22 +01:00 committed by The Qt Project
parent f4b80c1210
commit ea104efa34
6 changed files with 74 additions and 64 deletions

View File

@ -61,7 +61,7 @@ int main(int argc, char **argv)
//! [1] //! [1]
QApplication::setStyle(new QWindowsStyle); QApplication::setStyle(QStyleFactory::create("Fusion"));
//! [1] //! [1]

View File

@ -38,7 +38,7 @@
** **
****************************************************************************/ ****************************************************************************/
#include <QtGui> #include <QtWidgets>
#include "customstyle.h" #include "customstyle.h"
@ -84,7 +84,7 @@ void CustomStyle::drawPrimitive(PrimitiveElement element, const QStyleOption *op
} }
painter->drawPolygon(points); painter->drawPolygon(points);
} else { } else {
QWindowsStyle::drawPrimitive(element, option, painter, widget); QProxyStyle::drawPrimitive(element, option, painter, widget);
//! [2] //! [3] //! [2] //! [3]
} }
//! [3] //! [4] //! [3] //! [4]

View File

@ -41,10 +41,10 @@
#ifndef CUSTOMSTYLE_H #ifndef CUSTOMSTYLE_H
#define CUSTOMSTYLE_H #define CUSTOMSTYLE_H
#include <QWindowsStyle> #include <QProxyStyle>
//! [0] //! [0]
class CustomStyle : public QWindowsStyle class CustomStyle : public QProxyStyle
{ {
Q_OBJECT Q_OBJECT

View File

@ -63,7 +63,7 @@ void CustomViewStyle::drawPrimitive(PrimitiveElement element, const QStyleOption
break; break;
} }
default: default:
QWindowsStyle::drawPrimitive(element, option, painter, widget); QProxyStyle::drawPrimitive(element, option, painter, widget);
} }
//![0] //![0]
} }

View File

@ -77,7 +77,7 @@ inline QPoint JavaStyle::adjustScrollPoint(const QPoint &point,
QPalette JavaStyle::standardPalette() const QPalette JavaStyle::standardPalette() const
{ {
QPalette palette = QWindowsStyle::standardPalette(); QPalette palette = QCommonStyle::standardPalette();
palette.setBrush(QPalette::Active, QPalette::Button, palette.setBrush(QPalette::Active, QPalette::Button,
QColor(184, 207, 229)); QColor(184, 207, 229));
@ -877,8 +877,8 @@ void JavaStyle::drawControl(ControlElement control, const QStyleOption *option,
if (copy.state & State_HasFocus) if (copy.state & State_HasFocus)
copy.state ^= State_HasFocus; copy.state ^= State_HasFocus;
painter->setBrush(Qt::NoBrush); painter->setBrush(Qt::NoBrush);
QWindowsStyle::drawControl(CE_TabBarTabLabel, &copy, painter, QCommonStyle::drawControl(CE_TabBarTabLabel, &copy, painter,
widget); widget);
break; break;
} }
case CE_TabBarTabShape: { case CE_TabBarTabShape: {
@ -1048,7 +1048,7 @@ void JavaStyle::drawControl(ControlElement control, const QStyleOption *option,
break; break;
default: default:
QWindowsStyle::drawControl(control, option, painter, widget); QCommonStyle::drawControl(control, option, painter, widget);
} }
painter->restore(); painter->restore();
} }
@ -1079,8 +1079,8 @@ QRect JavaStyle::subControlRect(ComplexControl control,
SubControl subControl, SubControl subControl,
const QWidget *widget) const const QWidget *widget) const
{ {
QRect rect = QWindowsStyle::subControlRect(control, option, subControl, QRect rect = QCommonStyle::subControlRect(control, option, subControl,
widget); widget);
switch (control) { switch (control) {
case CC_TitleBar: { case CC_TitleBar: {
@ -1335,8 +1335,8 @@ QRect JavaStyle::subControlRect(ComplexControl control,
} }
break; break;
default: default:
return QWindowsStyle::subControlRect(control, option, return QCommonStyle::subControlRect(control, option,
subControl, widget); subControl, widget);
} }
break; break;
} }
@ -1433,8 +1433,8 @@ QRect JavaStyle::subControlRect(ComplexControl control,
break; break;
} }
default: default:
return QWindowsStyle::subControlRect(control, option, subControl, return QCommonStyle::subControlRect(control, option, subControl,
widget); widget);
} }
return rect; return rect;
} }
@ -1892,7 +1892,7 @@ void JavaStyle::drawComplexControl(ComplexControl control,
break; break;
} }
default: default:
QWindowsStyle::drawComplexControl(control, option, painter, widget); QCommonStyle::drawComplexControl(control, option, painter, widget);
} }
painter->restore(); painter->restore();
} }
@ -2014,8 +2014,8 @@ QStyle::SubControl JavaStyle::hitTestComplexControl(ComplexControl control,
break; break;
default: default:
ret = QWindowsStyle::hitTestComplexControl(control, option, pos, ret = QCommonStyle::hitTestComplexControl(control, option, pos,
widget); widget);
} }
return ret; return ret;
} }
@ -2391,7 +2391,7 @@ void JavaStyle::drawPrimitive(PrimitiveElement element,
break; break;
} }
default: default:
QWindowsStyle::drawPrimitive(element, option, painter, widget); QCommonStyle::drawPrimitive(element, option, painter, widget);
} }
painter->restore(); painter->restore();
} }
@ -2482,7 +2482,7 @@ QRect JavaStyle::subElementRect(SubElement element,
break; break;
} }
default: default:
rect = QWindowsStyle::subElementRect(element, option, widget); rect = QCommonStyle::subElementRect(element, option, widget);
} }
return rect; return rect;
} }
@ -2573,7 +2573,7 @@ int JavaStyle::pixelMetric(PixelMetric metric,
break; break;
} }
default: default:
value = QWindowsStyle::pixelMetric(metric); value = QCommonStyle::pixelMetric(metric);
} }
return value; return value;
} }
@ -2594,7 +2594,7 @@ int JavaStyle::styleHint(StyleHint hint, const QStyleOption *option,
ret = 1; ret = 1;
break; break;
default: default:
ret = QWindowsStyle::styleHint(hint, option, widget, returnData); ret = QCommonStyle::styleHint(hint, option, widget, returnData);
} }
return ret; return ret;
} }
@ -2603,8 +2603,8 @@ QPixmap JavaStyle::standardPixmap(StandardPixmap standardPixmap,
const QStyleOption *option, const QStyleOption *option,
const QWidget *widget) const const QWidget *widget) const
{ {
QPixmap pixmap = QWindowsStyle::standardPixmap(standardPixmap, option, QPixmap pixmap = QCommonStyle::standardPixmap(standardPixmap, option,
widget); widget);
QPixmap maximizePixmap(":/images/internalmaximize.png"); QPixmap maximizePixmap(":/images/internalmaximize.png");
QPixmap minimizePixmap(":/images/internalminimize.png"); QPixmap minimizePixmap(":/images/internalminimize.png");
@ -2709,7 +2709,7 @@ QSize JavaStyle::sizeFromContents(ContentsType type,
case CT_MenuItem: { case CT_MenuItem: {
const QStyleOptionMenuItem *menuItem = const QStyleOptionMenuItem *menuItem =
qstyleoption_cast<const QStyleOptionMenuItem *>(option); qstyleoption_cast<const QStyleOptionMenuItem *>(option);
QSize defaultSize = QWindowsStyle::sizeFromContents(type, option, QSize defaultSize = QCommonStyle::sizeFromContents(type, option,
contentsSize, widget); contentsSize, widget);
if (menuItem->menuItemType == QStyleOptionMenuItem::Separator) if (menuItem->menuItemType == QStyleOptionMenuItem::Separator)
@ -2739,7 +2739,7 @@ QSize JavaStyle::sizeFromContents(ContentsType type,
return QSize(width, height); return QSize(width, height);
} }
default: default:
return QWindowsStyle::sizeFromContents(type, option, contentsSize, return QCommonStyle::sizeFromContents(type, option, contentsSize,
widget); widget);
} }
} }

View File

@ -37,19 +37,32 @@
drawing, ensuring that they look exactly like the equivalent drawing, ensuring that they look exactly like the equivalent
native widgets. native widgets.
Several styles are built into Qt (e.g., Windows style and motif style). Qt comes with a selection of built-in styles. Some styles are only
Other styles are only available on specific platforms (such as available on specific platforms (such as the Mac, GTK+ and Windows
the Windows XP style). Custom styles are made available as plugins Vista styles). Custom styles are made available as plugins or by
or by creating an instance of the style class in an application and creating an instance of a specific style class with
setting it with QApplication::setStyle(). QStyleFactory::create() and setting it with QApplication::setStyle().
To implement a new style, you inherit one of Qt's existing styles \section1 Customizing a Style
- the one most resembling the style you want to create - and
reimplement a few virtual functions. This process is somewhat In order to customize an existing style, inherit QProxyStyle and
involved, and we therefore provide this overview. We give a reimplement the desired virtual methods. QProxyStyle allows one
step-by-step walkthrough of how to style individual Qt widgets. to specify a certain base style, or it will automatically use the
We will examine the QStyle virtual functions, member variables, application style when the base style is left unspecified. The
and enumerations. former gives a full control on the base style and works best if
the customization expects a certain style behavior, whereas the
latter provides a platform agnostic way to customize the application
style that defaults to the native platform style.
\section1 Implementing a Custom Style
QCommonStyle provides a convenient base for full custom style
implementations. The approach is same than with QProxyStyle, but
inherit QCommonStyle instead and reimplement the appropriate virtual
methods. Implementing a full custom style is somewhat involved, and
we therefore provide this overview. We give a step-by-step walkthrough
of how to style individual Qt widgets. We will examine the QStyle
virtual functions, member variables, and enumerations.
The part of this document that does not concern the styling of The part of this document that does not concern the styling of
individual widgets is meant to be read sequentially because later individual widgets is meant to be read sequentially because later
@ -453,11 +466,9 @@
\section2 Design and Implementation \section2 Design and Implementation
The first step in designing the style was to select the base The first step in designing the style was to select the base
class. We chose to subclass QWindowsStyle. This class implements class. We chose to subclass QCommonStyle. This class implements
most of the functionality we need, other than performing the actual most of the functionality we need, other than performing the actual
drawing. Also, Windows and Java share the layout of sub controls for drawing.
several of the complex controls (which reduces the amount of code
required considerably).
The style is implemented in one class. We have done this The style is implemented in one class. We have done this
because we find it convenient to keep all code in one file. Also, because we find it convenient to keep all code in one file. Also,
@ -503,7 +514,7 @@
which Java's JTree does not have a header. which Java's JTree does not have a header.
The style does not handle reverse layouts. We assume that the The style does not handle reverse layouts. We assume that the
layout direction is left to right. QWindowsStyle handles reverse layout direction is left to right. QCommonStyle handles reverse
widgets; if we implemented reverse layouts, widgets that we change widgets; if we implemented reverse layouts, widgets that we change
the position of sub elements, or handle text alignment in labels the position of sub elements, or handle text alignment in labels
ourselves would need to be updated. ourselves would need to be updated.
@ -636,10 +647,10 @@
The drawing of labels often gets somewhat involved. Luckily, it The drawing of labels often gets somewhat involved. Luckily, it
can usually be handled by the base class. The Java style can usually be handled by the base class. The Java style
implements its own push button label, since Java - contrary to implements its own push button label, since Java centers button
Windows - centers button contents also when the button has an icon. contents also when the button has an icon. You can examine that
You can examine that implementation if you need an example of implementation if you need an example of reimplementing label
reimplementing label drawing. drawing.
We'll now take a look at the Java implementation We'll now take a look at the Java implementation
of CE_CheckBoxIndicator in \c drawControl(): of CE_CheckBoxIndicator in \c drawControl():
@ -647,7 +658,7 @@
\snippet javastyle.cpp 0 \snippet javastyle.cpp 0
We first save the state of the painter. This is not always We first save the state of the painter. This is not always
necessary, but in this case the QWindowsStyle needs the painter in necessary, but in this case the QCommonStyle needs the painter in
the same state as it was when PE_IndicatorCheckBox was called (We the same state as it was when PE_IndicatorCheckBox was called (We
could also set the state with function calls, of course). We then could also set the state with function calls, of course). We then
use \c drawButtonBackground() to draw the background of the check use \c drawButtonBackground() to draw the background of the check
@ -690,7 +701,7 @@
not visible for that widget in the Java style. We still make sure not visible for that widget in the Java style. We still make sure
that all elements are implemented in a way that conforms with the that all elements are implemented in a way that conforms with the
Java style, as custom widgets might need them (this does not Java style, as custom widgets might need them (this does not
exclude leaving implementations to QWindowsStyle though). exclude leaving implementations to QCommonStyle though).
The following is given for each widget: The following is given for each widget:
@ -738,7 +749,7 @@
element rectangles, and sub control rectangles should be used when element rectangles, and sub control rectangles should be used when
examining the trees. If you are in doubt after reading the QStyle examining the trees. If you are in doubt after reading the QStyle
enum descriptions, we suggest that you examine the QCommonStyle enum descriptions, we suggest that you examine the QCommonStyle
and QWindowsStyle implementations. implementation.
Some of the bounding rectangles that we outline in the widget Some of the bounding rectangles that we outline in the widget
images are equal. Reasons for this are that some elements draw images are equal. Reasons for this are that some elements draw
@ -842,9 +853,8 @@
QCommonStyle to draw the elements that it contains: QCommonStyle to draw the elements that it contains:
\c PE_FrameDefaultButton, \c PE_FrameButtonBevel, and \c PE_FrameDefaultButton, \c PE_FrameButtonBevel, and
\c PE_PanelButtonCommand, all of which have the same bounds in common \c PE_PanelButtonCommand, all of which have the same bounds in common
and Windows style. \c PE_PushButtonBevel is also responsible for style. \c PE_PushButtonBevel is also responsible for drawing the menu
drawing the menu indicator (QCommonStyle draws indicator (QCommonStyle draws \c PE_IndicatorArrowDown).
\c PE_IndicatorArrowDown).
An image of a push button in the Java style that shows the bounding An image of a push button in the Java style that shows the bounding
rectangles of the elements is given below. Colors are used to rectangles of the elements is given below. Colors are used to
@ -971,10 +981,10 @@
\image javastyle/tabwidget.png \image javastyle/tabwidget.png
In the Java style (and also Windows), the tab bar shape and label In the Java style, the tab bar shape and label have the same bounding
have the same bounding rectangle as \c CE_TabBarTab. Notice that the rectangle as \c CE_TabBarTab. Notice that the tabs overlap with the
tabs overlap with the tab widget frame. The base of the tab bar tab widget frame. The base of the tab bar (if drawn) is the area where
(if drawn) is the area where the tabs and frame overlap. the tabs and frame overlap.
The style option for tabs (QStyleOptionTab) contains the necessary The style option for tabs (QStyleOptionTab) contains the necessary
information for drawing tabs. The option contains the position of information for drawing tabs. The option contains the position of
@ -984,7 +994,7 @@
icon's size. icon's size.
As the Java style tabs don't overlap, we also present an image of As the Java style tabs don't overlap, we also present an image of
a tab widget in the Windows style. Note that if you want the tabs a tab widget in the common style. Note that if you want the tabs
to overlap horizontally, you do that when drawing the tabs in to overlap horizontally, you do that when drawing the tabs in
\c CE_TabBarTabShape; the tabs bounding rectangles will not be \c CE_TabBarTabShape; the tabs bounding rectangles will not be
altered by the tab bar. The tabs are drawn from left to right in a altered by the tab bar. The tabs are drawn from left to right in a
@ -1103,8 +1113,8 @@
Java's, as it has two line up indicators. We have done this to show Java's, as it has two line up indicators. We have done this to show
that you can have two separate bounding rectangles for a that you can have two separate bounding rectangles for a
single sub control. The scroll bar is an example of a widget that single sub control. The scroll bar is an example of a widget that
is entirely implemented by the Java style - neither QWindowsStyle is entirely implemented by the Java style - QCommonStyle is not
nor QCommonStyle are involved in the drawing. involved in the drawing.
We have a look at the different states a scroll bar can set on We have a look at the different states a scroll bar can set on
the style option: the style option:
@ -1486,7 +1496,7 @@
\image javastyle/progressbar.png \image javastyle/progressbar.png
Here is a progress bar in the Windows style (the Java style Here is a progress bar in the common style (the Java style
bounding rectangles are equal): bounding rectangles are equal):
\image javastyle/progressbarimage.png \image javastyle/progressbarimage.png
@ -1543,7 +1553,7 @@
Note that \c PE_FrameButtonTool and \c PE_IndicatorArrowDown are Note that \c PE_FrameButtonTool and \c PE_IndicatorArrowDown are
included in the tree as the Java style draws them, but they can included in the tree as the Java style draws them, but they can
safely be omitted if you prefer it. The structure may also be safely be omitted if you prefer it. The structure may also be
different. QWindowsStyle, for instance, draws both different. QCommonStyle, for instance, draws both
\c PE_IndicatorButtonDropDown and \c PE_IndicatorArrowDown in \c PE_IndicatorButtonDropDown and \c PE_IndicatorArrowDown in
\c CE_ToolButton. \c CE_ToolButton.