diff options
Diffstat (limited to 'doc/src/qpaintdevice.qdoc')
| -rw-r--r-- | doc/src/qpaintdevice.qdoc | 289 |
1 files changed, 289 insertions, 0 deletions
diff --git a/doc/src/qpaintdevice.qdoc b/doc/src/qpaintdevice.qdoc new file mode 100644 index 0000000..be2f4bb --- /dev/null +++ b/doc/src/qpaintdevice.qdoc @@ -0,0 +1,289 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class QPaintDevice + \brief The QPaintDevice class is the base class of objects that + can be painted. + + \ingroup multimedia + + A paint device is an abstraction of a two-dimensional space that + can be drawn using a QPainter. Its default coordinate system has + its origin located at the top-left position. X increases to the + right and Y increases downwards. The unit is one pixel. + + The drawing capabilities of QPaintDevice are currently implemented + by the QWidget, QImage, QPixmap, QGLPixelBuffer, QPicture, and + QPrinter subclasses. + + To implement support for a new backend, you must derive from + QPaintDevice and reimplement the virtual paintEngine() function to + tell QPainter which paint engine should be used to draw on this + particular device. Note that you also must create a corresponding + paint engine to be able to draw on the device, i.e derive from + QPaintEngine and reimplement its virtual functions. + + \warning Qt requires that a QApplication object exists before + any paint devices can be created. Paint devices access window + system resources, and these resources are not initialized before + an application object is created. + + The QPaintDevice class provides several functions returning the + various device metrics: The depth() function returns its bit depth + (number of bit planes). The height() function returns its height + in default coordinate system units (e.g. pixels for QPixmap and + QWidget) while heightMM() returns the height of the device in + millimeters. Similiarily, the width() and widthMM() functions + return the width of the device in default coordinate system units + and in millimeters, respectively. Alternatively, the protected + metric() function can be used to retrieve the metric information + by specifying the desired PaintDeviceMetric as argument. + + The logicalDpiX() and logicalDpiY() functions return the + horizontal and vertical resolution of the device in dots per + inch. The physicalDpiX() and physicalDpiY() functions also return + the resolution of the device in dots per inch, but note that if + the logical and vertical resolution differ, the corresponding + QPaintEngine must handle the mapping. Finally, the numColors() + function returns the number of different colors available for the + paint device. + + \sa QPaintEngine, QPainter, {The Coordinate System}, {The Paint + System} +*/ + +/*! + \enum QPaintDevice::PaintDeviceMetric + + Describes the various metrics of a paint device. + + \value PdmWidth The width of the paint device in default + coordinate system units (e.g. pixels for QPixmap and QWidget). See + also width(). + + \value PdmHeight The height of the paint device in default + coordinate system units (e.g. pixels for QPixmap and QWidget). See + also height(). + + \value PdmWidthMM The width of the paint device in millimeters. See + also widthMM(). + + \value PdmHeightMM The height of the paint device in millimeters. See + also heightMM(). + + \value PdmNumColors The number of different colors available for + the paint device. See also numColors(). + + \value PdmDepth The bit depth (number of bit planes) of the paint + device. See also depth(). + + \value PdmDpiX The horizontal resolution of the device in dots per + inch. See also logicalDpiX(). + + \value PdmDpiY The vertical resolution of the device in dots per inch. See + also logicalDpiY(). + + \value PdmPhysicalDpiX The horizontal resolution of the device in + dots per inch. See also physicalDpiX(). + + \value PdmPhysicalDpiY The vertical resolution of the device in + dots per inch. See also physicalDpiY(). + + \sa metric() +*/ + +/*! + \fn QPaintDevice::QPaintDevice() + + Constructs a paint device. This constructor can be invoked only from + subclasses of QPaintDevice. +*/ + +/*! + \fn QPaintDevice::~QPaintDevice() + + Destroys the paint device and frees window system resources. +*/ + +/*! + \fn int QPaintDevice::devType() const + + \internal + + Returns the device type identifier, which is QInternal::Widget + if the device is a QWidget, QInternal::Pixmap if it's a + QPixmap, QInternal::Printer if it's a QPrinter, + QInternal::Picture if it's a QPicture, or + QInternal::UnknownDevice in other cases. +*/ + +/*! + \fn bool QPaintDevice::paintingActive() const + + Returns true if the device is currently being painted on, i.e. someone has + called QPainter::begin() but not yet called QPainter::end() for + this device; otherwise returns false. + + \sa QPainter::isActive() +*/ + +/*! + \fn QPaintEngine *QPaintDevice::paintEngine() const + + Returns a pointer to the paint engine used for drawing on the + device. +*/ + +/*! + \fn int QPaintDevice::metric(PaintDeviceMetric metric) const + + Returns the metric information for the given paint device \a metric. + + \sa PaintDeviceMetric +*/ + +/*! + \fn int QPaintDevice::width() const + + Returns the width of the paint device in default coordinate system + units (e.g. pixels for QPixmap and QWidget). + + \sa widthMM() +*/ + +/*! + \fn int QPaintDevice::height() const + + Returns the height of the paint device in default coordinate + system units (e.g. pixels for QPixmap and QWidget). + + \sa heightMM() +*/ + +/*! + \fn int QPaintDevice::widthMM() const + + Returns the width of the paint device in millimeters. Due to platform + limitations it may not be possible to use this function to determine + the actual physical size of a widget on the screen. + + \sa width() +*/ + +/*! + \fn int QPaintDevice::heightMM() const + + Returns the height of the paint device in millimeters. Due to platform + limitations it may not be possible to use this function to determine + the actual physical size of a widget on the screen. + + \sa height() +*/ + +/*! + \fn int QPaintDevice::numColors() const + + Returns the number of different colors available for the paint + device. Since this value is an int, it will not be sufficient to represent + the number of colors on 32 bit displays, in this case INT_MAX is + returned instead. +*/ + +/*! + \fn int QPaintDevice::depth() const + + Returns the bit depth (number of bit planes) of the paint device. +*/ + +/*! + \fn int QPaintDevice::logicalDpiX() const + + Returns the horizontal resolution of the device in dots per inch, + which is used when computing font sizes. For X11, this is usually + the same as could be computed from widthMM(). + + Note that if the logicalDpiX() doesn't equal the physicalDpiX(), + the corresponding QPaintEngine must handle the resolution mapping. + + \sa logicalDpiY(), physicalDpiX() +*/ + +/*! + \fn int QPaintDevice::logicalDpiY() const + + Returns the vertical resolution of the device in dots per inch, + which is used when computing font sizes. For X11, this is usually + the same as could be computed from heightMM(). + + Note that if the logicalDpiY() doesn't equal the physicalDpiY(), + the corresponding QPaintEngine must handle the resolution mapping. + + \sa logicalDpiX(), physicalDpiY() +*/ + +/*! + \fn int QPaintDevice::physicalDpiX() const + + Returns the horizontal resolution of the device in dots per inch. + For example, when printing, this resolution refers to the physical + printer's resolution. The logical DPI on the other hand, refers to + the resolution used by the actual paint engine. + + Note that if the physicalDpiX() doesn't equal the logicalDpiX(), + the corresponding QPaintEngine must handle the resolution mapping. + + \sa physicalDpiY(), logicalDpiX() +*/ + +/*! + \fn int QPaintDevice::physicalDpiY() const + + Returns the horizontal resolution of the device in dots per inch. + For example, when printing, this resolution refers to the physical + printer's resolution. The logical DPI on the other hand, refers to + the resolution used by the actual paint engine. + + Note that if the physicalDpiY() doesn't equal the logicalDpiY(), + the corresponding QPaintEngine must handle the resolution mapping. + + \sa physicalDpiX(), logicalDpiY() +*/ |