qt-everywhere-src-5.15.1/qtbase/src/gui/painting/qpaintdevice.qdoc - orbit - Git at Google

 /****************************************************************************
 **
 ** Copyright (C) 2016 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the documentation of the Qt Toolkit.
 **
 ** $QT_BEGIN_LICENSE:FDL$
 ** Commercial License Usage
 ** Licensees holding valid commercial Qt licenses may use this file in
 ** accordance with the commercial license agreement provided with the
 ** Software or, alternatively, in accordance with the terms contained in
 ** a written agreement between you and The Qt Company. For licensing terms
 ** and conditions see https://www.qt.io/terms-conditions. For further
 ** information use the contact form at https://www.qt.io/contact-us.
 **
 ** GNU Free Documentation License Usage
 ** Alternatively, this file may be used under the terms of the GNU Free
 ** Documentation License version 1.3 as published by the Free Software
 ** Foundation and appearing in the file included in the packaging of
 ** this file. Please review the following information to ensure
 ** the GNU Free Documentation License version 1.3 requirements
 ** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
 ** $QT_END_LICENSE$
 **
 ****************************************************************************/

 /*!
     \class QPaintDevice
     \brief The QPaintDevice class is the base class of objects that
     can be painted on with QPainter.

     \ingroup painting
     \inmodule QtGui

     A paint device is an abstraction of a two-dimensional space that
     can be drawn on 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 QGuiApplication 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 physical resolution differ, the corresponding
     QPaintEngine must handle the mapping. Finally, the colorCount()
     function returns the number of different colors available for the
     paint device.

     \sa QPaintEngine, QPainter, {Coordinate System}, {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 colorCount().

     \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().

     \value PdmDevicePixelRatio The device pixel ratio for device. Common
     values are 1 for normal-dpi displays and 2 for high-dpi "retina"
     displays.

     \value PdmDevicePixelRatioScaled The scaled device pixel ratio for the device.
     This is identical to PdmDevicePixelRatio, except that the value is scaled by a
     constant factor in order to support paint devices with fractional scale factors.
     The constant scaling factor used is devicePixelRatioFScale(). This enum value
     has been introduced in Qt 5.6.

     \sa metric(), devicePixelRatioF()
 */

 /*!
     \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 \c 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 \c 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::colorCount() const

     Returns the number of different colors available for the paint
     device. If the number of colors available is too great to be
     represented by the int data type, then INT_MAX will be 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()
 */

 /*!
     \fn int QPaintDevice::devicePixelRatio() const

     Returns the device pixel ratio for device.

     Common values are 1 for normal-dpi displays and 2 for high-dpi
     "retina" displays.
 */

 /*!
     \fn qreal QPaintDevice::devicePixelRatioF() const

     Returns the device pixel ratio for the device as a floating point number.

     \since 5.6
 */

 /*!
     \fn qreal QPaintDevice::devicePixelRatioFScale()

     \internal

     Returns the scaling factor used for \c PdmDevicePixelRatioScaled. Classes
     that are not QPaintDevice subclasses are implementing metric(), and need to
     access this constant. Since it's a qreal, it cannot be an enum, and an inline
     function is more efficient than a static member variable.

     \since 5.6
 */
	/****************************************************************************
	**
	** Copyright (C) 2016 The Qt Company Ltd.
	** Contact: https://www.qt.io/licensing/
	**
	** This file is part of the documentation of the Qt Toolkit.
	**
	** $QT_BEGIN_LICENSE:FDL$
	** Commercial License Usage
	** Licensees holding valid commercial Qt licenses may use this file in
	** accordance with the commercial license agreement provided with the
	** Software or, alternatively, in accordance with the terms contained in
	** a written agreement between you and The Qt Company. For licensing terms
	** and conditions see https://www.qt.io/terms-conditions. For further
	** information use the contact form at https://www.qt.io/contact-us.
	**
	** GNU Free Documentation License Usage
	** Alternatively, this file may be used under the terms of the GNU Free
	** Documentation License version 1.3 as published by the Free Software
	** Foundation and appearing in the file included in the packaging of
	** this file. Please review the following information to ensure
	** the GNU Free Documentation License version 1.3 requirements
	** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
	** $QT_END_LICENSE$
	**
	****************************************************************************/

	/*!
	\class QPaintDevice
	\brief The QPaintDevice class is the base class of objects that
	can be painted on with QPainter.

	\ingroup painting
	\inmodule QtGui

	A paint device is an abstraction of a two-dimensional space that
	can be drawn on 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 QGuiApplication 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 physical resolution differ, the corresponding
	QPaintEngine must handle the mapping. Finally, the colorCount()
	function returns the number of different colors available for the
	paint device.

	\sa QPaintEngine, QPainter, {Coordinate System}, {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 colorCount().

	\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().

	\value PdmDevicePixelRatio The device pixel ratio for device. Common
	values are 1 for normal-dpi displays and 2 for high-dpi "retina"
	displays.

	\value PdmDevicePixelRatioScaled The scaled device pixel ratio for the device.
	This is identical to PdmDevicePixelRatio, except that the value is scaled by a
	constant factor in order to support paint devices with fractional scale factors.
	The constant scaling factor used is devicePixelRatioFScale(). This enum value
	has been introduced in Qt 5.6.

	\sa metric(), devicePixelRatioF()
	*/

	/*!
	\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 \c 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 \c 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::colorCount() const

	Returns the number of different colors available for the paint
	device. If the number of colors available is too great to be
	represented by the int data type, then INT_MAX will be 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()
	*/

	/*!
	\fn int QPaintDevice::devicePixelRatio() const

	Returns the device pixel ratio for device.

	Common values are 1 for normal-dpi displays and 2 for high-dpi
	"retina" displays.
	*/

	/*!
	\fn qreal QPaintDevice::devicePixelRatioF() const

	Returns the device pixel ratio for the device as a floating point number.

	\since 5.6
	*/

	/*!
	\fn qreal QPaintDevice::devicePixelRatioFScale()

	\internal

	Returns the scaling factor used for \c PdmDevicePixelRatioScaled. Classes
	that are not QPaintDevice subclasses are implementing metric(), and need to
	access this constant. Since it's a qreal, it cannot be an enum, and an inline
	function is more efficient than a static member variable.

	\since 5.6
	*/