src/gui/painting/qpaintdevice.qdoc

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