--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/gui/painting/qpaintdevice.qdoc Mon Jan 11 14:00:40 2010 +0000
@@ -0,0 +1,289 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (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 Technology Preview License Agreement accompanying
+** this package.
+**
+** 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.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \class QPaintDevice
+ \brief The QPaintDevice class is the base class of objects that
+ can be painted.
+
+ \ingroup painting
+
+ 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()
+*/