From 14b772b03e0c1f5bcd5f7c25d0ae35593a9f6427 Mon Sep 17 00:00:00 2001 From: Volker Hilsheimer Date: Mon, 27 Jul 2009 12:18:51 +0200 Subject: Doc: Obsolete QMatrix and QPainter APIs using it. QTransform and respective APIs should be used. Still some changes required - Some references to QMatrix left in documentation - Qt code uses QMatrix APIs (ie translationX) Reviewed-by: Samuel --- doc/src/paintsystem.qdoc | 2 +- src/gui/image/qbitmap.cpp | 3 +- src/gui/painting/qmatrix.cpp | 1 + src/gui/painting/qpainter.cpp | 90 ++++++++++++++++++++++++++----------------- 4 files changed, 58 insertions(+), 38 deletions(-) diff --git a/doc/src/paintsystem.qdoc b/doc/src/paintsystem.qdoc index a75908b..c2434e0 100644 --- a/doc/src/paintsystem.qdoc +++ b/doc/src/paintsystem.qdoc @@ -121,7 +121,7 @@ Normally, QPainter draws in a "natural" coordinate system, but it is able to perform view and world transformations using the - QMatrix class. For more information, see \l {The Coordinate + QTransform class. For more information, see \l {The Coordinate System} documentation which also describes the rendering process, i.e. the relation between the logical representation and the rendered pixels, and the benefits of anti-aliased painting. diff --git a/src/gui/image/qbitmap.cpp b/src/gui/image/qbitmap.cpp index 6bca504..78c3396 100644 --- a/src/gui/image/qbitmap.cpp +++ b/src/gui/image/qbitmap.cpp @@ -78,7 +78,7 @@ QT_BEGIN_NAMESPACE 0 for black and 1 for white. The QBitmap class provides the transformed() function returning a - transformed copy of the bitmap; use the QMatrix argument to + transformed copy of the bitmap; use the QTransform argument to translate, scale, shear, and rotate the bitmap. In addition, QBitmap provides the static fromData() function which returns a bitmap constructed from the given \c uchar data, and the static @@ -318,6 +318,7 @@ QBitmap QBitmap::transformed(const QTransform &matrix) const /*! \overload + \obsolete This convenience function converts the \a matrix to a QTransform and calls the overloaded function. diff --git a/src/gui/painting/qmatrix.cpp b/src/gui/painting/qmatrix.cpp index bc08235..39f4d95 100644 --- a/src/gui/painting/qmatrix.cpp +++ b/src/gui/painting/qmatrix.cpp @@ -55,6 +55,7 @@ QT_BEGIN_NAMESPACE \class QMatrix \brief The QMatrix class specifies 2D transformations of a coordinate system. + \obsolete \ingroup multimedia diff --git a/src/gui/painting/qpainter.cpp b/src/gui/painting/qpainter.cpp index 4c10a5a..4ebfc50 100644 --- a/src/gui/painting/qpainter.cpp +++ b/src/gui/painting/qpainter.cpp @@ -1005,7 +1005,7 @@ void QPainterPrivate::updateState(QPainterState *newState) \o brushOrigin() defines the origin of the tiled brushes, normally the origin of widget's background. - \o viewport(), window(), worldMatrix() make up the painter's coordinate + \o viewport(), window(), worldTransform() make up the painter's coordinate transformation system. For more information, see the \l {Coordinate Transformations} section and the \l {The Coordinate System} documentation. @@ -1212,15 +1212,15 @@ void QPainterPrivate::updateState(QPainterState *newState) \endtable All the tranformation operations operate on the transformation - worldMatrix(). A matrix transforms a point in the plane to another + worldTransform(). A matrix transforms a point in the plane to another point. For more information about the transformation matrix, see - the \l {The Coordinate System} and QMatrix documentation. + the \l {The Coordinate System} and QTransform documentation. - The setWorldMatrix() function can replace or add to the currently - set worldMatrix(). The resetMatrix() function resets any + The setWorldTransform() function can replace or add to the currently + set worldTransform(). The resetTransform() function resets any transformations that were made using translate(), scale(), - shear(), rotate(), setWorldMatrix(), setViewport() and setWindow() - functions. The deviceMatrix() returns the matrix that transforms + shear(), rotate(), setWorldTransform(), setViewport() and setWindow() + functions. The deviceTransform() returns the matrix that transforms from logical coordinates to device coordinates of the platform dependent paint device. The latter function is only needed when using platform painting commands on the platform dependent handle, @@ -1229,11 +1229,11 @@ void QPainterPrivate::updateState(QPainterState *newState) When drawing with QPainter, we specify points using logical coordinates which then are converted into the physical coordinates of the paint device. The mapping of the logical coordinates to the - physical coordinates are handled by QPainter's combinedMatrix(), a - combination of viewport() and window() and worldMatrix(). The + physical coordinates are handled by QPainter's combinedTransform(), a + combination of viewport() and window() and worldTransform(). The viewport() represents the physical coordinates specifying an arbitrary rectangle, the window() describes the same rectangle in - logical coordinates, and the worldMatrix() is identical with the + logical coordinates, and the worldTransform() is identical with the transformation matrix. See also \l {The Coordinate System} documentation. @@ -2677,6 +2677,7 @@ void QPainter::setClipRegion(const QRegion &r, Qt::ClipOperation op) /*! \since 4.2 + \obsolete Sets the transformation matrix to \a matrix and enables transformations. @@ -2715,7 +2716,7 @@ void QPainter::setClipRegion(const QRegion &r, Qt::ClipOperation op) and window-viewport conversion, see \l {The Coordinate System} documentation. - \sa worldMatrixEnabled(), QMatrix + \sa setWorldTransform(), QTransform */ void QPainter::setWorldMatrix(const QMatrix &matrix, bool combine) @@ -2725,6 +2726,7 @@ void QPainter::setWorldMatrix(const QMatrix &matrix, bool combine) /*! \since 4.2 + \obsolete Returns the world transformation matrix. @@ -2774,6 +2776,7 @@ const QMatrix &QPainter::matrix() const /*! \since 4.2 + \obsolete Returns the transformation matrix combining the current window/viewport and world transformation. @@ -2781,7 +2784,7 @@ const QMatrix &QPainter::matrix() const It is advisable to use combinedTransform() instead of this function to preserve the properties of perspective transformations. - \sa setWorldMatrix(), setWindow(), setViewport() + \sa setWorldTransform(), setWindow(), setViewport() */ QMatrix QPainter::combinedMatrix() const { @@ -2790,6 +2793,8 @@ QMatrix QPainter::combinedMatrix() const /*! + \obsolete + Returns the matrix that transforms from logical coordinates to device coordinates of the platform dependent paint device. @@ -2817,6 +2822,8 @@ const QMatrix &QPainter::deviceMatrix() const } /*! + \obsolete + Resets any transformations that were made using translate(), scale(), shear(), rotate(), setWorldMatrix(), setViewport() and setWindow(). @@ -2841,7 +2848,7 @@ void QPainter::resetMatrix() transformations if \a enable is false. The world transformation matrix is not changed. - \sa worldMatrixEnabled(), worldMatrix(), {QPainter#Coordinate + \sa worldMatrixEnabled(), worldTransform(), {QPainter#Coordinate Transformations}{Coordinate Transformations} */ @@ -2870,7 +2877,7 @@ void QPainter::setWorldMatrixEnabled(bool enable) Returns true if world transformation is enabled; otherwise returns false. - \sa setWorldMatrixEnabled(), worldMatrix(), {The Coordinate System} + \sa setWorldMatrixEnabled(), worldTransform(), {The Coordinate System} */ bool QPainter::worldMatrixEnabled() const @@ -2912,7 +2919,7 @@ bool QPainter::matrixEnabled() const /*! Scales the coordinate system by (\a{sx}, \a{sy}). - \sa setWorldMatrix() {QPainter#Coordinate Transformations}{Coordinate + \sa setWorldTransform() {QPainter#Coordinate Transformations}{Coordinate Transformations} */ @@ -2936,7 +2943,7 @@ void QPainter::scale(qreal sx, qreal sy) /*! Shears the coordinate system by (\a{sh}, \a{sv}). - \sa setWorldMatrix(), {QPainter#Coordinate Transformations}{Coordinate + \sa setWorldTransform(), {QPainter#Coordinate Transformations}{Coordinate Transformations} */ @@ -2962,7 +2969,7 @@ void QPainter::shear(qreal sh, qreal sv) Rotates the coordinate system the given \a angle clockwise. - \sa setWorldMatrix(), {QPainter#Coordinate Transformations}{Coordinate + \sa setWorldTransform(), {QPainter#Coordinate Transformations}{Coordinate Transformations} */ @@ -2987,7 +2994,7 @@ void QPainter::rotate(qreal a) Translates the coordinate system by the given \a offset; i.e. the given \a offset is added to points. - \sa setWorldMatrix(), {QPainter#Coordinate Transformations}{Coordinate + \sa setWorldTransform(), {QPainter#Coordinate Transformations}{Coordinate Transformations} */ void QPainter::translate(const QPointF &offset) @@ -6769,7 +6776,7 @@ QPainter::RenderHints QPainter::renderHints() const Returns true if view transformation is enabled; otherwise returns false. - \sa setViewTransformEnabled(), worldMatrix() + \sa setViewTransformEnabled(), worldTransform() */ bool QPainter::viewTransformEnabled() const @@ -6925,7 +6932,7 @@ QRect QPainter::viewport() const /*! \fn void QPainter::resetXForm() \compat - Use resetMatrix() instead. + Use resetTransform() instead. */ /*! \fn void QPainter::setViewXForm(bool enabled) @@ -6971,14 +6978,16 @@ void QPainter::setViewTransformEnabled(bool enable) #ifdef QT3_SUPPORT /*! - Use the worldMatrix() combined with QMatrix::dx() instead. + \obsolete + + Use the worldTransform() combined with QTransform::dx() instead. \oldcode QPainter painter(this); qreal x = painter.translationX(); \newcode QPainter painter(this); - qreal x = painter.worldMatrix().dx(); + qreal x = painter.worldTransform().dx(); \endcode */ qreal QPainter::translationX() const @@ -6992,14 +7001,16 @@ qreal QPainter::translationX() const } /*! - Use the worldMatrix() combined with QMatrix::dy() instead. + \obsolete + + Use the worldTransform() combined with QTransform::dy() instead. \oldcode QPainter painter(this); qreal y = painter.translationY(); \newcode QPainter painter(this); - qreal y = painter.worldMatrix().dy(); + qreal y = painter.worldTransform().dy(); \endcode */ qreal QPainter::translationY() const @@ -7097,7 +7108,7 @@ QPolygon QPainter::xForm(const QPolygon &a) const QPolygon transformed = painter.xForm(polygon, index, count) \newcode QPainter painter(this); - QPolygon transformed = polygon.mid(index, count) * painter.combinedMatrix(); + QPolygon transformed = polygon.mid(index, count) * painter.combinedTransform(); \endcode */ @@ -7112,15 +7123,16 @@ QPolygon QPainter::xForm(const QPolygon &av, int index, int npoints) const /*! \fn QPoint QPainter::xFormDev(const QPoint &point) const \overload + \obsolete - Use combinedTransform() combined with QMatrix::inverted() instead. + Use combinedTransform() combined with QTransform::inverted() instead. \oldcode QPainter painter(this); QPoint transformed = painter.xFormDev(point); \newcode QPainter painter(this); - QPoint transformed = point * painter.combinedMatrix().inverted(); + QPoint transformed = point * painter.combinedTransform().inverted(); \endcode */ @@ -7139,15 +7151,16 @@ QPoint QPainter::xFormDev(const QPoint &p) const /*! \fn QRect QPainter::xFormDev(const QRect &rectangle) const \overload + \obsolete - Use mapRect() combined with QMatrix::inverted() instead. + Use combinedTransform() combined with QTransform::inverted() instead. \oldcode QPainter painter(this); QRect transformed = painter.xFormDev(rectangle); \newcode QPainter painter(this); - QRect transformed = painter.combinedMatrix().inverted(rectangle); + QRect transformed = painter.combinedTransform().inverted(rectangle); \endcode */ @@ -7167,16 +7180,16 @@ QRect QPainter::xFormDev(const QRect &r) const \overload \fn QPoint QPainter::xFormDev(const QPolygon &polygon) const - \overload + \obsolete - Use combinedMatrix() combined with QMatrix::inverted() instead. + Use combinedTransform() combined with QTransform::inverted() instead. \oldcode QPainter painter(this); QPolygon transformed = painter.xFormDev(rectangle); \newcode QPainter painter(this); - QPolygon transformed = polygon * painter.combinedMatrix().inverted(); + QPolygon transformed = polygon * painter.combinedTransform().inverted(); \endcode */ @@ -7195,15 +7208,16 @@ QPolygon QPainter::xFormDev(const QPolygon &a) const /*! \fn QPolygon QPainter::xFormDev(const QPolygon &polygon, int index, int count) const \overload + \obsolete - Use combinedMatrix() combined with QPolygon::mid() and QMatrix::inverted() instead. + Use combinedTransform() combined with QPolygon::mid() and QTransform::inverted() instead. \oldcode QPainter painter(this); QPolygon transformed = painter.xFormDev(polygon, index, count); \newcode QPainter painter(this); - QPolygon transformed = polygon.mid(index, count) * painter.combinedMatrix().inverted(); + QPolygon transformed = polygon.mid(index, count) * painter.combinedTransform().inverted(); \endcode */ @@ -8107,7 +8121,7 @@ void bitBlt(QPaintDevice *dst, int dx, int dy, \row \o QPaintEngine::DirtyClipRegion \o clipRegion() \row \o QPaintEngine::DirtyCompositionMode \o compositionMode() \row \o QPaintEngine::DirtyFont \o font() - \row \o QPaintEngine::DirtyTransform \o matrix() + \row \o QPaintEngine::DirtyTransform \o transform() \row \o QPaintEngine::DirtyClipEnabled \o isClipEnabled() \row \o QPaintEngine::DirtyPen \o pen() \row \o QPaintEngine::DirtyHints \o renderHints() @@ -8226,10 +8240,14 @@ QFont QPaintEngineState::font() const /*! \since 4.2 + \obsolete Returns the matrix in the current paint engine state. + \note It is advisable to use transform() instead of this function to + preserve the properties of perspective transformations. + This variable should only be used when the state() returns a combination which includes the QPaintEngine::DirtyTransform flag. @@ -8534,7 +8552,7 @@ const QTransform & QPainter::worldTransform() const Returns the transformation matrix combining the current window/viewport and world transformation. - \sa setWorldMatrix(), setWindow(), setViewport() + \sa setWorldTransform(), setWindow(), setViewport() */ QTransform QPainter::combinedTransform() const -- cgit v0.12