doc/src/qpaintdevice.qdoc

   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 multimedia
  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 */