source: trunk/doc/src/qt4-arthur.qdoc@ 321

Last change on this file since 321 was 2, checked in by Dmitry A. Kuminov, 16 years ago

Initially imported qt-all-opensource-src-4.5.1 from Trolltech.

File size: 13.1 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4** Contact: Qt Software Information ([email protected])
5**
6** This file is part of the documentation of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial Usage
10** Licensees holding valid Qt Commercial licenses may use this file in
11** accordance with the Qt Commercial License Agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and Nokia.
14**
15** GNU Lesser General Public License Usage
16** Alternatively, this file may be used under the terms of the GNU Lesser
17** General Public License version 2.1 as published by the Free Software
18** Foundation and appearing in the file LICENSE.LGPL included in the
19** packaging of this file. Please review the following information to
20** ensure the GNU Lesser General Public License version 2.1 requirements
21** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
22**
23** In addition, as a special exception, Nokia gives you certain
24** additional rights. These rights are described in the Nokia Qt LGPL
25** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
26** package.
27**
28** GNU General Public License Usage
29** Alternatively, this file may be used under the terms of the GNU
30** General Public License version 3.0 as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL included in the
32** packaging of this file. Please review the following information to
33** ensure the GNU General Public License version 3.0 requirements will be
34** met: http://www.gnu.org/copyleft/gpl.html.
35**
36** If you are unsure which license is appropriate for your use, please
37** contact the sales department at [email protected].
38** $QT_END_LICENSE$
39**
40****************************************************************************/
41
42/*!
43 \page qt4-arthur.html
44 \title The Arthur Paint System
45
46 \contentspage {What's New in Qt 4}{Home}
47 \previouspage The Interview Framework
48 \nextpage The Scribe Classes
49
50 This document describes Qt 4's painting system, providing a
51 comparison between the approaches used by Qt when rendering
52 graphics in Qt 3 and Qt 4.
53
54 \tableofcontents
55
56 \section1 Architecture
57
58 The Qt 4 Paint System is primarily based on the classes
59 QPainter, QPaintDevice, and QPaintEngine. QPainter is the
60 class used to perform drawing operations, such as drawLine()
61 and drawRect(). QPaintDevice represents a device that can be
62 painted on using a QPainter; both QWidget and QPixmap are
63 QPaintDevices. QPaintEngine provides the interface that the
64 painter uses to draw onto different types of devices.
65
66 \section2 A Look Back at Qt 3
67
68 In Qt 3, QPainter could be used to draw on widgets and pixmaps.
69 (It could also be used to draw to printers on Windows and Mac OS
70 X.) When other paint devices needed to be supported, such as
71 QPrinter on X11, this was done by deriving from QPaintDevice and
72 reimplementing the virtual function QPaintDevice::cmd(). A
73 reimplemented paint device was treated as an external device.
74
75 QPainter was capable of recognizing external devices and could
76 serialize each paint operation to the reimplemented cmd()
77 function. This allowed reimplementation of arbitrary devices, but
78 the approach has some disadvantages which we have addressed in
79 Qt 4. One of these is that an external device could not reuse any
80 functionality implemented in QPainter since QPainter was tied to
81 widget/pixmap painting on that platform. Supporting multiple
82 device backends, such as OpenGL, was therefore inconvenient and
83 not very efficient.
84
85 This has led us to devise a more convenient and intuitive API for
86 Qt 4.
87
88 \section2 How Painting is Done in Qt 4
89
90 In Qt 4 we have introduced the QPaintEngine abstract class.
91 Implementations of this class provide the concrete functionality
92 needed to draw to specific device types. The QPaintEngine class
93 is only used internally by QPainter and QPaintDevice, and it is
94 hidden from application programmers unless they reimplement their own
95 device types for their own QPaintEngine subclasses. Qt currently
96 provides paint engines for the following platforms and APIs:
97
98 \list
99 \o A pixel-based engine for the Windows platform that is
100 also used to draw onto QImages on all platforms
101 \o OpenGL on all platforms
102 \o PostScript on Linux, Unix, and Mac OS X
103 \o QuickDraw and CoreGraphics on Mac OS X
104 \o X11 and the X Render Extension on Linux and Unix systems
105 \omit
106 \o QVFb, VNC, and LinuxFb for Qt for Embedded Linux
107 \endomit
108 \endlist
109
110 To implement support for a new backend, you must derive from
111 QPaintEngine and reimplement its virtual functions. You also need
112 to derive from QPaintDevice and reimplement the virtual function
113 QPaintDevice::paintEngine() to tell QPainter which paint engine
114 should be used to draw on this particular device.
115
116 The main benefit of this approach is that all painting follows the
117 same painting pipeline. This means that adding support for new features
118 and providing default implementations for unsupported ones has
119 become much simpler.
120
121 \section1 New Features in the Qt 4 Paint System
122
123 \section2 Gradient Brushes
124
125 With Qt 4 it is possible to fill shapes using gradient
126 brushes. A gradient in this case is used to describe the transition
127 from one color at a given point to different color at another point. A
128 gradient can span from one color to another or over a
129 number of colors by specifying multiple colors at positions in the
130 gradient area. Qt 4 supports linear, radial, and conical gradients.
131
132 Linear gradients are specified using two control points.
133 Setting a linear gradient brush is done by creating a QLinearGradient
134 object and setting it as a brush.
135
136 \snippet doc/src/snippets/code/doc_src_qt4-arthur.qdoc 0
137
138 The code shown above produces a pattern as show in the following
139 pixmap:
140
141 \img diagonalGradient.png
142
143 Radial gradients are specified using a center, a radius, and a
144 focal point. Setting a radial brush is done by creating a QRadialGradient
145 object and setting it as a brush.
146
147 \snippet doc/src/snippets/code/doc_src_qt4-arthur.qdoc 1
148
149 The code shown above produces a pattern as shown in the following
150 pixmap:
151
152 \img radialGradient.png
153
154 Conical gradients are specified using a center and a start
155 angle. Setting a conical brush is done by creating a
156 QConicalGradient object and setting it as a brush.
157
158 \snippet doc/src/snippets/code/doc_src_qt4-arthur.qdoc 2
159
160 The code shown above produces a pattern as shown in the following
161 pixmap:
162
163 \img conicalGradient.png
164
165 \section2 Alpha-Blended Drawing
166
167 With Qt 4 we support alpha-blended outlining and filling. The
168 alpha channel of a color is defined through QColor. The alpha
169 channel specifies the transparency effect, 0 represents a fully
170 transparent color, while 255 represents a fully opaque color. For
171 example:
172
173 \snippet doc/src/snippets/code/doc_src_qt4-arthur.qdoc 3
174
175 The code shown above produces the following output:
176
177 \img alphafill.png
178
179 Alpha-blended drawing is supported on Windows, Mac OS X, and on
180 X11 systems that have the X Render extension installed.
181
182
183 \section2 QPainter and QGLWidget
184
185 It is now possible to open a QPainter on a QGLWidget as if it
186 were a normal QWidget. One huge benefit from this is that we
187 utilize the high performance of OpenGL for most drawing
188 operations, such as transformations and pixmap drawing.
189
190
191 \section2 Anti-Aliased Edges
192
193 On platforms where this is supported by the native drawing API, we
194 provide the option of turning on anti-aliased edges when drawing
195 graphics primitives.
196
197 \snippet doc/src/snippets/code/doc_src_qt4-arthur.qdoc 4
198
199 This produces the following output:
200
201 \img antialiased.png
202
203 Anti-aliasing is supported when drawing to a QImage and on all
204 systems, except on X11 when XRender is not present.
205
206
207 \section2 Extensive Use of Native Graphics Operations
208
209 Where this makes sense, Qt uses native graphics
210 operations. The benefit we gain from this is that these operations
211 can potentially be performed in hardware, giving significant
212 speed improvements over many pure-software implementations.
213
214 Among these are native transformations (Mac OS X and OpenGL),
215 making painting with a world matrix much faster. Some pixmap
216 operations have also been moved closer to the underlying
217 hardware implementations.
218
219
220 \section2 Painter Paths
221
222 A painter path is an object composed of a number of graphical
223 building blocks, such as rectangles, ellipses, lines, and curves.
224 A painter path can be used for filling, outlining, and for clipping.
225 The main advantage of painter paths over normal drawing operations
226 is that it is possible to build up non-linear shapes which can be
227 drawn later in one go.
228
229 Building blocks can be joined in closed subpaths, such as a
230 rectangle or an ellipse, or they can exist independently as unclosed
231 subpaths, although an unclosed path will not be filled.
232
233 Below is a code example on how a path can be used. The
234 painter in this case has a pen width of 3 and a light blue brush. We
235 first add a rectangle, which becomes a closed subpath. We then add
236 two bezier curves, and finally draw the entire path.
237
238 \snippet doc/src/snippets/code/doc_src_qt4-arthur.qdoc 5
239
240 The code above produces the following output:
241
242 \img pathexample.png
243
244
245 \section2 Widget Double-Buffering
246
247 In Qt 4, all widgets are double-buffered by default.
248
249 In previous versions of Qt double-buffering was achieved by
250 painting to an off-screen pixmap then copying the pixmap to the
251 screen. For example:
252
253 \snippet doc/src/snippets/code/doc_src_qt4-arthur.qdoc 6
254
255 Since the double-buffering is handled by QWidget internally this
256 now becomes:
257
258 \snippet doc/src/snippets/code/doc_src_qt4-arthur.qdoc 7
259
260 Double-buffering is turned on by default, but can be turned off for
261 individual widgets by setting the widget attribute
262 Qt::WA_PaintOnScreen.
263
264 \snippet doc/src/snippets/code/doc_src_qt4-arthur.qdoc 8
265
266 \section2 Pen and Brush Transformation
267
268 In Qt 3, pens and brushes weren't affected by the painter's
269 transformation matrix. For example, if you drew a rectangle with a
270 pen width of 1 using a scaled painter, the resulting line width
271 would still be 1. This made it difficult to implement features
272 such as zooming and high-resolution printing.
273
274 In Qt 4, pens and brushes honor the painter's transformation
275 matrix.
276
277 Note that this feature is still in development and not yet
278 supported on all platforms.
279
280 \section2 Custom Filled Pens
281
282 In Qt 4, it is possible to specify how an outline should be
283 filled. It can be a solid color or a QBrush, which makes it
284 possible to specify both texture and gradient fills for both
285 text and outlines.
286
287 \snippet doc/src/snippets/code/doc_src_qt4-arthur.qdoc 9
288
289 The code above produces the following output:
290
291 \img gradientText.png
292
293 \section2 QImage as a Paint Device
294
295 A great improvement of Qt 4 over previous versions it that it now
296 provides a pixel-based raster paint engine which allows users to
297 open a painter on a QImage. The QImage paint engine supports the
298 full feature set of QPainter (paths, antialiasing, alphablending,
299 etc.) and can be used on all platforms.
300
301 One advantage of this is that it is possible to guarantee the
302 pixel exactness of any drawing operation in a platform-independent
303 way.
304
305 Painting on an image is as simple as drawing on any other paint device.
306
307 \snippet doc/src/snippets/code/doc_src_qt4-arthur.qdoc 10
308
309 \section2 SVG Rendering Support
310
311 \l{Scalable Vector Graphics} (SVG) is an language for describing both static
312 and animated two-dimensional vector graphics. Qt includes support for the
313 \l{SVG 1.2 Tiny Static Features}{static features} of \l{SVG 1.2 Tiny}, taking
314 advantage of the improved paint system in Qt 4. SVG drawings can be rendered
315 onto any QPaintDevice subclass, such as QWidget, QImage, and QGLWidget, to
316 take advantage of specific advantages of each device. This approach gives
317 developers the flexibility to experiment, in order to find the best solution
318 for each application.
319
320 \image svg-image.png
321
322 Since SVG is an XML-based format, the QtXml module is required to read SVG
323 files. For this reason, classes for SVG handling are provided separately in
324 the QtSvg module.
325
326 Displaying an SVG drawing in an application is as simple as displaying a
327 bitmap image. QSvgWidget is a display widget that can be placed in an
328 appropriate place in a user interface, and new content can be loaded as
329 required. For example, a predetermined file can be loaded and displayed in
330 a widget with little effort:
331
332 \snippet doc/src/snippets/qsvgwidget/main.cpp 0
333
334 For applications with more specialized requirements, the QSvgRenderer class
335 provides more control over the way SVG drawings are rendered and animated.
336*/
Note: See TracBrowser for help on using the repository browser.