1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
|
/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the Technology Preview License Agreement accompanying
** this package.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain additional
** rights. These rights are described in the Nokia Qt LGPL Exception
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
**
**
**
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qt4-styles.html
\title The Qt 4 Style API
\contentspage {What's New in Qt 4}{Home}
\previouspage The Network Module in Qt 4
\nextpage Thread Support in Qt 4
Qt's style API is responsible for performing the widget drawing
for built-in widgets. The Qt 4 style API has been revised to make
it possible for a style to draw widgets without calling any
functions on the widget.
Because Qt 4 is split across multiple libraries, Qt needed this
update to be able to draw widgets from other libraries than
QtGui. For application developers, this has other benefits, such
as more managable parameter lists and the possibility of drawing
any graphical element without having a widget of a specific
type.
\section1 General Overview
The QStyle class is an abstract base class that encapsulates
the look and feel of a GUI. Qt's built-in widgets use it to
perform nearly all of their drawing, ensuring that they look
exactly like the equivalent native widgets.
Most draw functions now take four arguments:
\list
\o an enum value specifying which graphical element to draw
\o a QStyleOption specifying how and where to render that element
\o a QPainter that should be used to draw the element
\o a QWidget on which the drawing is performed (optional)
\endlist
The style gets all the information it needs to render the
graphical element from QStyleOption. The widget is passed as the
last argument in case the style needs it to perform special
effects (such as animated default buttons on Mac OS X), but it
isn't mandatory. In fact, QStyle can be used to draw on any
paint device, not just widgets, by setting the QPainter properly.
Thanks to QStyleOption, it is now possible to make QStyle draw
widgets without linking in any code for the widget. This is how
Qt's built-in styles can draw Qt 3 widgets such as
Q3ListView without necessarily linking against the Qt3Support
library. Another significant benefit of the new approach is that
it's now possible to use \l{QStyle}'s draw functions on other
widgets than the built-in widgets; for example, you can draw a
combobox on any widget, not just on a QComboBox.
QStyleOption has various subclasses for the various types of
graphical elements that can be drawn, and it's possible to create
custom subclasses. For example, the QStyle::PE_FrameFocusRect
element expects a QStyleOptionFocusRect argument. This is
documented for each enum value.
When reimplementing QStyle functions that take a
QStyleOption parameter, you often need to cast the
QStyleOption to a subclass (e.g., QStyleOptionFocusRect). For
safety, you can use qstyleoption_cast() to ensure that the
pointer type is correct. If the object isn't of the right type,
qstyleoption_cast() returns 0. For example:
\snippet doc/src/snippets/code/doc_src_qt4-styles.qdoc 0
For performance reasons, there are few member functions and the
access to the variables is direct. This "low-level" feel makes
the structures use straightforward and emphasizes that these are
simply parameters used by the style functions. In addition, the
caller of a QStyle function usually creates QStyleOption
objects on the stack. This combined with Qt's extensive use of
\l{implicit sharing} for types such as QString, QPalette, and
QColor ensures that no memory allocation needlessly takes place.
(Dynamic memory allocation can be an expensive operation,
especially when drawing very often in a short time.)
\section1 Example Code
The following code snippet illustrates how to use QStyle to
draw the focus rectangle from a custom widget's paintEvent():
\snippet doc/src/snippets/code/doc_src_qt4-styles.qdoc 1
The next example shows how to derive from an existing style to
customize the look of a graphical element:
\snippet doc/src/snippets/customstyle/customstyle.h 0
\codeline
\snippet doc/src/snippets/customstyle/customstyle.cpp 2
\snippet doc/src/snippets/customstyle/customstyle.cpp 3
\snippet doc/src/snippets/customstyle/customstyle.cpp 4
See also the \l{Styles Example} for a more detailed description of
how custom styles can be created.
\section1 Comparison with Qt 3
The QStyle class has a similar API in Qt 4 as in Qt 3, with
more or less the same functions. What has changed is the
signature of the functions and the role played by QStyleOption.
For example, here's the signature of the QStyle::drawControl()
function in Qt 3:
\snippet doc/src/snippets/code/doc_src_qt4-styles.qdoc 2
Here's the signature of the same function in Qt 4:
\snippet doc/src/snippets/code/doc_src_qt4-styles.qdoc 3
In Qt 3, some of the information required to draw a graphical
element was stored in a QStyleOption parameter, while the rest
was deduced by querying the widget. In Qt 4, everything is stored
in the QStyleOption parameter.
*/
|
