Doc: Some final QMatrix cleanups.

4 files changed, 27 insertions, 15 deletions

diff --git a/src/gui/graphicsview/qgraphicsitem.cpp b/src/gui/graphicsview/qgraphicsitem.cpp
index c8e55e3..06f26a1 100644
--- a/src/gui/graphicsview/qgraphicsitem.cpp
+++ b/src/gui/graphicsview/qgraphicsitem.cpp
@@ -303,11 +303,12 @@
     drop shadow effects and for decoration objects that follow the parent
     item's geometry without drawing on top of it.
 
-    \value ItemUsesExtendedStyleOption The item makes use of either
-    QStyleOptionGraphicsItem::exposedRect or QStyleOptionGraphicsItem::matrix.
+    \value ItemUsesExtendedStyleOption The item makes use of either the
+    exposedRect or matrix member of the QStyleOptionGraphicsItem. Implementers
+    of QGraphicsItem subclasses should set that flag if this data is required.
     By default, the exposedRect is initialized to the item's boundingRect and
     the matrix is untransformed. Enable this flag for more fine-grained values.
-    Use QStyleOptionGraphicsItem::levelOfDetailFromTransform for a more
+    Use QStyleOptionGraphicsItem::levelOfDetailFromTransform() for a more
     fine-grained value.
 
     \value ItemHasNoContents The item does not paint anything (i.e., calling
diff --git a/src/gui/graphicsview/qgraphicswidget.cpp b/src/gui/graphicsview/qgraphicswidget.cpp
index 6937584..6f56b84 100644
--- a/src/gui/graphicsview/qgraphicswidget.cpp
+++ b/src/gui/graphicsview/qgraphicswidget.cpp
@@ -2286,6 +2286,7 @@ bool QGraphicsWidget::close()
 #ifdef Q_NO_USING_KEYWORD
 /*!
     \fn const QObjectList &QGraphicsWidget::children() const
+    \internal
 
     This function returns the same value as QObject::children(). It's
     provided to differentiate between the obsolete member
diff --git a/src/gui/painting/qtransform.cpp b/src/gui/painting/qtransform.cpp
index 8a9d6f1..a322fe4 100644
--- a/src/gui/painting/qtransform.cpp
+++ b/src/gui/painting/qtransform.cpp
@@ -1775,7 +1775,7 @@ bool QTransform::quadToQuad(const QPolygonF &one,
     Sets the matrix elements to the specified values, \a m11,
     \a m12, \a m13 \a m21, \a m22, \a m23 \a m31, \a m32 and
     \a m33. Note that this function replaces the previous values.
-    QMatrix provides the translate(), rotate(), scale() and shear()
+    QTransform provides the translate(), rotate(), scale() and shear()
     convenience functions to manipulate the various matrix elements
     based on the currently defined coordinate system.
 
@@ -1953,8 +1953,11 @@ void QTransform::map(int x, int y, int *tx, int *ty) const
 }
 
 /*!
-  Returns the QTransform cast to a QMatrix.
- */
+  Returns the QTransform as an affine matrix.
+
+  \warning If a perspective transformation has been specified,
+  then the conversion will cause loss of data.
+*/
 const QMatrix &QTransform::toAffine() const
 {
     return affine;
diff --git a/src/gui/styles/qstyleoption.cpp b/src/gui/styles/qstyleoption.cpp
index 7547dda..0ff7995 100644
--- a/src/gui/styles/qstyleoption.cpp
+++ b/src/gui/styles/qstyleoption.cpp
@@ -5007,11 +5007,6 @@ QStyleOptionGraphicsItem::QStyleOptionGraphicsItem(int version)
     of the painter used to draw the item. By default, if no
     transformations are applied, its value is 1. If zoomed out 1:2, the level
     of detail will be 0.5, and if zoomed in 2:1, its value is 2.
-
-    For more advanced level-of-detail metrics, use
-    QStyleOptionGraphicsItem::matrix directly.
-
-    \sa QStyleOptionGraphicsItem::matrix
 */
 qreal QStyleOptionGraphicsItem::levelOfDetailFromTransform(const QTransform &worldTransform)
 {
@@ -5038,20 +5033,32 @@ qreal QStyleOptionGraphicsItem::levelOfDetailFromTransform(const QTransform &wor
     Make use of this rectangle to speed up item drawing when only parts of the
     item are exposed. If the whole item is exposed, this rectangle will be the
     same as QGraphicsItem::boundingRect().
+
+    This member is only initialized for items that have the
+    QGraphicsItem::ItemUsesExtendedStyleOption flag set.
 */
 
 /*!
      \variable QStyleOptionGraphicsItem::matrix
      \brief the complete transformation matrix for the item
+     \obsolete
 
-     This matrix is the sum of the item's scene matrix and the matrix of the
-     painter used for drawing the item. It is provided for convenience,
+     The QMatrix provided through this member does include information about
+     any perspective transformations applied to the view or item. To get the
+     correct transformation matrix, use QPainter::transform() on the painter
+     passed into the QGraphicsItem::paint() implementation.
+
+     This matrix is the combination of the item's scene matrix and the matrix
+     of the painter used for drawing the item. It is provided for convenience,
      allowing anvanced level-of-detail metrics that can be used to speed up
      item drawing.
 
-     To find the dimentions of an item in screen coordinates (i.e., pixels),
+     To find the dimensions of an item in screen coordinates (i.e., pixels),
      you can use the mapping functions of QMatrix, such as QMatrix::map().
 
+     This member is only initialized for items that have the
+     QGraphicsItem::ItemUsesExtendedStyleOption flag set.
+
      \sa QStyleOptionGraphicsItem::levelOfDetailFromTransform()
 */
 
@@ -5059,7 +5066,7 @@ qreal QStyleOptionGraphicsItem::levelOfDetailFromTransform(const QTransform &wor
     \variable QStyleOptionGraphicsItem::levelOfDetail
     \obsolete
 
-    Use QStyleOptionGraphicsItem::levelOfDetailFromTransform
+    Use QStyleOptionGraphicsItem::levelOfDetailFromTransform()
     together with QPainter::worldTransform() instead.
 */