|
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 \class QPaintDevice |
|
44 \brief The QPaintDevice class is the base class of objects that |
|
45 can be painted. |
|
46 |
|
47 \ingroup painting |
|
48 |
|
49 A paint device is an abstraction of a two-dimensional space that |
|
50 can be drawn using a QPainter. Its default coordinate system has |
|
51 its origin located at the top-left position. X increases to the |
|
52 right and Y increases downwards. The unit is one pixel. |
|
53 |
|
54 The drawing capabilities of QPaintDevice are currently implemented |
|
55 by the QWidget, QImage, QPixmap, QGLPixelBuffer, QPicture, and |
|
56 QPrinter subclasses. |
|
57 |
|
58 To implement support for a new backend, you must derive from |
|
59 QPaintDevice and reimplement the virtual paintEngine() function to |
|
60 tell QPainter which paint engine should be used to draw on this |
|
61 particular device. Note that you also must create a corresponding |
|
62 paint engine to be able to draw on the device, i.e derive from |
|
63 QPaintEngine and reimplement its virtual functions. |
|
64 |
|
65 \warning Qt requires that a QApplication object exists before |
|
66 any paint devices can be created. Paint devices access window |
|
67 system resources, and these resources are not initialized before |
|
68 an application object is created. |
|
69 |
|
70 The QPaintDevice class provides several functions returning the |
|
71 various device metrics: The depth() function returns its bit depth |
|
72 (number of bit planes). The height() function returns its height |
|
73 in default coordinate system units (e.g. pixels for QPixmap and |
|
74 QWidget) while heightMM() returns the height of the device in |
|
75 millimeters. Similiarily, the width() and widthMM() functions |
|
76 return the width of the device in default coordinate system units |
|
77 and in millimeters, respectively. Alternatively, the protected |
|
78 metric() function can be used to retrieve the metric information |
|
79 by specifying the desired PaintDeviceMetric as argument. |
|
80 |
|
81 The logicalDpiX() and logicalDpiY() functions return the |
|
82 horizontal and vertical resolution of the device in dots per |
|
83 inch. The physicalDpiX() and physicalDpiY() functions also return |
|
84 the resolution of the device in dots per inch, but note that if |
|
85 the logical and vertical resolution differ, the corresponding |
|
86 QPaintEngine must handle the mapping. Finally, the numColors() |
|
87 function returns the number of different colors available for the |
|
88 paint device. |
|
89 |
|
90 \sa QPaintEngine, QPainter, {The Coordinate System}, {The Paint |
|
91 System} |
|
92 */ |
|
93 |
|
94 /*! |
|
95 \enum QPaintDevice::PaintDeviceMetric |
|
96 |
|
97 Describes the various metrics of a paint device. |
|
98 |
|
99 \value PdmWidth The width of the paint device in default |
|
100 coordinate system units (e.g. pixels for QPixmap and QWidget). See |
|
101 also width(). |
|
102 |
|
103 \value PdmHeight The height of the paint device in default |
|
104 coordinate system units (e.g. pixels for QPixmap and QWidget). See |
|
105 also height(). |
|
106 |
|
107 \value PdmWidthMM The width of the paint device in millimeters. See |
|
108 also widthMM(). |
|
109 |
|
110 \value PdmHeightMM The height of the paint device in millimeters. See |
|
111 also heightMM(). |
|
112 |
|
113 \value PdmNumColors The number of different colors available for |
|
114 the paint device. See also numColors(). |
|
115 |
|
116 \value PdmDepth The bit depth (number of bit planes) of the paint |
|
117 device. See also depth(). |
|
118 |
|
119 \value PdmDpiX The horizontal resolution of the device in dots per |
|
120 inch. See also logicalDpiX(). |
|
121 |
|
122 \value PdmDpiY The vertical resolution of the device in dots per inch. See |
|
123 also logicalDpiY(). |
|
124 |
|
125 \value PdmPhysicalDpiX The horizontal resolution of the device in |
|
126 dots per inch. See also physicalDpiX(). |
|
127 |
|
128 \value PdmPhysicalDpiY The vertical resolution of the device in |
|
129 dots per inch. See also physicalDpiY(). |
|
130 |
|
131 \sa metric() |
|
132 */ |
|
133 |
|
134 /*! |
|
135 \fn QPaintDevice::QPaintDevice() |
|
136 |
|
137 Constructs a paint device. This constructor can be invoked only from |
|
138 subclasses of QPaintDevice. |
|
139 */ |
|
140 |
|
141 /*! |
|
142 \fn QPaintDevice::~QPaintDevice() |
|
143 |
|
144 Destroys the paint device and frees window system resources. |
|
145 */ |
|
146 |
|
147 /*! |
|
148 \fn int QPaintDevice::devType() const |
|
149 |
|
150 \internal |
|
151 |
|
152 Returns the device type identifier, which is QInternal::Widget |
|
153 if the device is a QWidget, QInternal::Pixmap if it's a |
|
154 QPixmap, QInternal::Printer if it's a QPrinter, |
|
155 QInternal::Picture if it's a QPicture, or |
|
156 QInternal::UnknownDevice in other cases. |
|
157 */ |
|
158 |
|
159 /*! |
|
160 \fn bool QPaintDevice::paintingActive() const |
|
161 |
|
162 Returns true if the device is currently being painted on, i.e. someone has |
|
163 called QPainter::begin() but not yet called QPainter::end() for |
|
164 this device; otherwise returns false. |
|
165 |
|
166 \sa QPainter::isActive() |
|
167 */ |
|
168 |
|
169 /*! |
|
170 \fn QPaintEngine *QPaintDevice::paintEngine() const |
|
171 |
|
172 Returns a pointer to the paint engine used for drawing on the |
|
173 device. |
|
174 */ |
|
175 |
|
176 /*! |
|
177 \fn int QPaintDevice::metric(PaintDeviceMetric metric) const |
|
178 |
|
179 Returns the metric information for the given paint device \a metric. |
|
180 |
|
181 \sa PaintDeviceMetric |
|
182 */ |
|
183 |
|
184 /*! |
|
185 \fn int QPaintDevice::width() const |
|
186 |
|
187 Returns the width of the paint device in default coordinate system |
|
188 units (e.g. pixels for QPixmap and QWidget). |
|
189 |
|
190 \sa widthMM() |
|
191 */ |
|
192 |
|
193 /*! |
|
194 \fn int QPaintDevice::height() const |
|
195 |
|
196 Returns the height of the paint device in default coordinate |
|
197 system units (e.g. pixels for QPixmap and QWidget). |
|
198 |
|
199 \sa heightMM() |
|
200 */ |
|
201 |
|
202 /*! |
|
203 \fn int QPaintDevice::widthMM() const |
|
204 |
|
205 Returns the width of the paint device in millimeters. Due to platform |
|
206 limitations it may not be possible to use this function to determine |
|
207 the actual physical size of a widget on the screen. |
|
208 |
|
209 \sa width() |
|
210 */ |
|
211 |
|
212 /*! |
|
213 \fn int QPaintDevice::heightMM() const |
|
214 |
|
215 Returns the height of the paint device in millimeters. Due to platform |
|
216 limitations it may not be possible to use this function to determine |
|
217 the actual physical size of a widget on the screen. |
|
218 |
|
219 \sa height() |
|
220 */ |
|
221 |
|
222 /*! |
|
223 \fn int QPaintDevice::numColors() const |
|
224 |
|
225 Returns the number of different colors available for the paint |
|
226 device. Since this value is an int, it will not be sufficient to represent |
|
227 the number of colors on 32 bit displays, in this case INT_MAX is |
|
228 returned instead. |
|
229 */ |
|
230 |
|
231 /*! |
|
232 \fn int QPaintDevice::depth() const |
|
233 |
|
234 Returns the bit depth (number of bit planes) of the paint device. |
|
235 */ |
|
236 |
|
237 /*! |
|
238 \fn int QPaintDevice::logicalDpiX() const |
|
239 |
|
240 Returns the horizontal resolution of the device in dots per inch, |
|
241 which is used when computing font sizes. For X11, this is usually |
|
242 the same as could be computed from widthMM(). |
|
243 |
|
244 Note that if the logicalDpiX() doesn't equal the physicalDpiX(), |
|
245 the corresponding QPaintEngine must handle the resolution mapping. |
|
246 |
|
247 \sa logicalDpiY(), physicalDpiX() |
|
248 */ |
|
249 |
|
250 /*! |
|
251 \fn int QPaintDevice::logicalDpiY() const |
|
252 |
|
253 Returns the vertical resolution of the device in dots per inch, |
|
254 which is used when computing font sizes. For X11, this is usually |
|
255 the same as could be computed from heightMM(). |
|
256 |
|
257 Note that if the logicalDpiY() doesn't equal the physicalDpiY(), |
|
258 the corresponding QPaintEngine must handle the resolution mapping. |
|
259 |
|
260 \sa logicalDpiX(), physicalDpiY() |
|
261 */ |
|
262 |
|
263 /*! |
|
264 \fn int QPaintDevice::physicalDpiX() const |
|
265 |
|
266 Returns the horizontal resolution of the device in dots per inch. |
|
267 For example, when printing, this resolution refers to the physical |
|
268 printer's resolution. The logical DPI on the other hand, refers to |
|
269 the resolution used by the actual paint engine. |
|
270 |
|
271 Note that if the physicalDpiX() doesn't equal the logicalDpiX(), |
|
272 the corresponding QPaintEngine must handle the resolution mapping. |
|
273 |
|
274 \sa physicalDpiY(), logicalDpiX() |
|
275 */ |
|
276 |
|
277 /*! |
|
278 \fn int QPaintDevice::physicalDpiY() const |
|
279 |
|
280 Returns the horizontal resolution of the device in dots per inch. |
|
281 For example, when printing, this resolution refers to the physical |
|
282 printer's resolution. The logical DPI on the other hand, refers to |
|
283 the resolution used by the actual paint engine. |
|
284 |
|
285 Note that if the physicalDpiY() doesn't equal the logicalDpiY(), |
|
286 the corresponding QPaintEngine must handle the resolution mapping. |
|
287 |
|
288 \sa physicalDpiX(), logicalDpiY() |
|
289 */ |