1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
6 \brief The QPaintDevice class is the base class of objects that
7 can be painted on with QPainter.
12 A paint device is an abstraction of a two-dimensional space that
13 can be drawn on using a QPainter. Its default coordinate system has
14 its origin located at the top-left position. X increases to the
15 right and Y increases downwards. The unit is one pixel.
17 The drawing capabilities of QPaintDevice are currently implemented
18 by the QWidget, QImage, QPixmap, QPicture, and QPrinter subclasses.
20 To implement support for a new backend, you must derive from
21 QPaintDevice and reimplement the virtual paintEngine() function to
22 tell QPainter which paint engine should be used to draw on this
23 particular device. Note that you also must create a corresponding
24 paint engine to be able to draw on the device, i.e derive from
25 QPaintEngine and reimplement its virtual functions.
27 \warning Qt requires that a QGuiApplication object exists before
28 any paint devices can be created. Paint devices access window
29 system resources, and these resources are not initialized before
30 an application object is created.
32 The QPaintDevice class provides several functions returning the
33 various device metrics: The depth() function returns its bit depth
34 (number of bit planes). The height() function returns its height
35 in default coordinate system units (e.g. pixels for QPixmap and
36 QWidget) while heightMM() returns the height of the device in
37 millimeters. Similiarily, the width() and widthMM() functions
38 return the width of the device in default coordinate system units
39 and in millimeters, respectively. Alternatively, the protected
40 metric() function can be used to retrieve the metric information
41 by specifying the desired PaintDeviceMetric as argument.
43 The logicalDpiX() and logicalDpiY() functions return the
44 horizontal and vertical resolution of the device in dots per
45 inch. The physicalDpiX() and physicalDpiY() functions also return
46 the resolution of the device in dots per inch, but note that if
47 the logical and physical resolution differ, the corresponding
48 QPaintEngine must handle the mapping. Finally, the colorCount()
49 function returns the number of different colors available for the
52 \sa QPaintEngine, QPainter, {Coordinate System}, {Paint System}
56 \enum QPaintDevice::PaintDeviceMetric
58 Describes the various metrics of a paint device.
60 \value PdmWidth The width of the paint device in default
61 coordinate system units (e.g. pixels for QPixmap and QWidget). See
64 \value PdmHeight The height of the paint device in default
65 coordinate system units (e.g. pixels for QPixmap and QWidget). See
68 \value PdmWidthMM The width of the paint device in millimeters. See
71 \value PdmHeightMM The height of the paint device in millimeters. See
74 \value PdmNumColors The number of different colors available for
75 the paint device. See also colorCount().
77 \value PdmDepth The bit depth (number of bit planes) of the paint
78 device. See also depth().
80 \value PdmDpiX The horizontal resolution of the device in dots per
81 inch. See also logicalDpiX().
83 \value PdmDpiY The vertical resolution of the device in dots per inch. See
86 \value PdmPhysicalDpiX The horizontal resolution of the device in
87 dots per inch. See also physicalDpiX().
89 \value PdmPhysicalDpiY The vertical resolution of the device in
90 dots per inch. See also physicalDpiY().
92 \value PdmDevicePixelRatio The device pixel ratio for device. Common
93 values are 1 for normal-dpi displays and 2 for high-dpi "retina"
96 \value PdmDevicePixelRatioScaled The scaled device pixel ratio for the device.
97 This is identical to PdmDevicePixelRatio, except that the value is scaled by a
98 constant factor in order to support paint devices with fractional scale factors.
99 The constant scaling factor used is devicePixelRatioFScale(). This enum value
100 has been introduced in Qt 5.6.
102 \sa metric(), devicePixelRatio()
106 \fn QPaintDevice::QPaintDevice()
108 Constructs a paint device. This constructor can be invoked only from
109 subclasses of QPaintDevice.
113 \fn QPaintDevice::~QPaintDevice()
115 Destroys the paint device and frees window system resources.
119 \fn int QPaintDevice::devType() const
123 Returns the device type identifier, which is QInternal::Widget
124 if the device is a QWidget, QInternal::Pixmap if it's a
125 QPixmap, QInternal::Printer if it's a QPrinter,
126 QInternal::Picture if it's a QPicture, or
127 QInternal::UnknownDevice in other cases.
131 \fn bool QPaintDevice::paintingActive() const
133 Returns \c true if the device is currently being painted on, i.e. someone has
134 called QPainter::begin() but not yet called QPainter::end() for
135 this device; otherwise returns \c false.
137 \sa QPainter::isActive()
141 \fn QPaintEngine *QPaintDevice::paintEngine() const
143 Returns a pointer to the paint engine used for drawing on the
148 \fn int QPaintDevice::metric(PaintDeviceMetric metric) const
150 Returns the metric information for the given paint device \a metric.
152 \sa PaintDeviceMetric
156 \fn int QPaintDevice::width() const
158 Returns the width of the paint device in default coordinate system
159 units (e.g. pixels for QPixmap and QWidget).
165 \fn int QPaintDevice::height() const
167 Returns the height of the paint device in default coordinate
168 system units (e.g. pixels for QPixmap and QWidget).
174 \fn int QPaintDevice::widthMM() const
176 Returns the width of the paint device in millimeters. Due to platform
177 limitations it may not be possible to use this function to determine
178 the actual physical size of a widget on the screen.
184 \fn int QPaintDevice::heightMM() const
186 Returns the height of the paint device in millimeters. Due to platform
187 limitations it may not be possible to use this function to determine
188 the actual physical size of a widget on the screen.
194 \fn int QPaintDevice::colorCount() const
196 Returns the number of different colors available for the paint
197 device. If the number of colors available is too great to be
198 represented by the int data type, then INT_MAX will be returned
203 \fn int QPaintDevice::depth() const
205 Returns the bit depth (number of bit planes) of the paint device.
209 \fn int QPaintDevice::logicalDpiX() const
211 Returns the horizontal resolution of the device in dots per inch,
212 which is used when computing font sizes. For X11, this is usually
213 the same as could be computed from widthMM().
215 Note that if the logicalDpiX() doesn't equal the physicalDpiX(),
216 the corresponding QPaintEngine must handle the resolution mapping.
218 \sa logicalDpiY(), physicalDpiX()
222 \fn int QPaintDevice::logicalDpiY() const
224 Returns the vertical resolution of the device in dots per inch,
225 which is used when computing font sizes. For X11, this is usually
226 the same as could be computed from heightMM().
228 Note that if the logicalDpiY() doesn't equal the physicalDpiY(),
229 the corresponding QPaintEngine must handle the resolution mapping.
231 \sa logicalDpiX(), physicalDpiY()
235 \fn int QPaintDevice::physicalDpiX() const
237 Returns the horizontal resolution of the device in dots per inch.
238 For example, when printing, this resolution refers to the physical
239 printer's resolution. The logical DPI on the other hand, refers to
240 the resolution used by the actual paint engine.
242 Note that if the physicalDpiX() doesn't equal the logicalDpiX(),
243 the corresponding QPaintEngine must handle the resolution mapping.
245 \sa physicalDpiY(), logicalDpiX()
249 \fn int QPaintDevice::physicalDpiY() const
251 Returns the horizontal resolution of the device in dots per inch.
252 For example, when printing, this resolution refers to the physical
253 printer's resolution. The logical DPI on the other hand, refers to
254 the resolution used by the actual paint engine.
256 Note that if the physicalDpiY() doesn't equal the logicalDpiY(),
257 the corresponding QPaintEngine must handle the resolution mapping.
259 \sa physicalDpiX(), logicalDpiY()
263 \fn qreal QPaintDevice::devicePixelRatio() const
265 Returns the device pixel ratio for device.
267 Common values are 1 for normal-dpi displays and 2 for high-dpi
272 \fn qreal QPaintDevice::devicePixelRatioF() const
274 Returns the device pixel ratio for the device as a floating point number.
280 \fn qreal QPaintDevice::devicePixelRatioFScale()
284 Returns the scaling factor used for \c PdmDevicePixelRatioScaled. Classes
285 that are not QPaintDevice subclasses are implementing metric(), and need to
286 access this constant. Since it's a qreal, it cannot be an enum, and an inline
287 function is more efficient than a static member variable.