Doc: Reviewed and revised QGraphicsAnchorLayout documentation.

Reviewed-by: Trust Me

5 files changed, 216 insertions, 59 deletions

diff --git a/doc/src/images/simpleanchorlayout-example.png b/doc/src/images/simpleanchorlayout-example.png
new file mode 100644
index 0000000000..1d5c8ac048
--- /dev/null
+++ b/doc/src/images/simpleanchorlayout-example.png
diff --git a/examples/graphicsview/anchorlayout/anchorlayout.pro b/examples/graphicsview/anchorlayout/anchorlayout.pro
index c2a1beadc8..fd085cc330 100644
--- a/examples/graphicsview/anchorlayout/anchorlayout.pro
+++ b/examples/graphicsview/anchorlayout/anchorlayout.pro
@@ -1,9 +1,4 @@
-######################################################################
-# Automatically generated by qmake (2.01a) Tue May 12 15:22:25 2009
-######################################################################
-
-# Input
-SOURCES += main.cpp
+SOURCES   = main.cpp
 
 # install
 target.path = $$[QT_INSTALL_EXAMPLES]/graphicsview/anchorlayout
@@ -11,5 +6,4 @@ sources.files = $$SOURCES $$HEADERS $$RESOURCES anchorlayout.pro
 sources.path = $$[QT_INSTALL_EXAMPLES]/graphicsview/anchorlayout
 INSTALLS += target sources
 
-TARGET = anchorlayout_example
-CONFIG+=console
\ No newline at end of file
+TARGET = anchorlayout
diff --git a/examples/graphicsview/simpleanchorlayout/main.cpp b/examples/graphicsview/simpleanchorlayout/main.cpp
new file mode 100644
index 0000000000..493b00f178
--- /dev/null
+++ b/examples/graphicsview/simpleanchorlayout/main.cpp
@@ -0,0 +1,134 @@
+/****************************************************************************
+**
+** 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 examples 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$
+**
+****************************************************************************/
+
+#include <QtGui>
+
+class Widget : public QGraphicsWidget
+{
+public:
+    Widget(const QColor &color, const QColor &textColor, const QString &caption,
+           QGraphicsItem *parent = 0)
+        : QGraphicsWidget(parent), caption(caption), color(color), textColor(textColor)
+    {
+    }
+
+    void paint(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget = 0)
+    {
+        QFont font;
+        font.setPixelSize(0.75 * qMin(boundingRect().width(), boundingRect().height()));
+
+        painter->fillRect(boundingRect(), color);
+        painter->save();
+        painter->setFont(font);
+        painter->setPen(textColor);
+        painter->drawText(boundingRect(), Qt::AlignCenter, caption);
+        painter->restore();
+    }
+
+private:
+    QString caption;
+    QColor color;
+    QColor textColor;
+};
+
+int main(int argc, char *argv[])
+{
+    QApplication app(argc, argv);
+
+    QGraphicsScene *scene = new QGraphicsScene();
+
+    Widget *a = new Widget(Qt::blue, Qt::white, "a");
+    a->setPreferredSize(100, 100);
+    Widget *b = new Widget(Qt::green, Qt::black, "b");
+    b->setPreferredSize(100, 100);
+    Widget *c = new Widget(Qt::red, Qt::black, "c");
+    c->setPreferredSize(100, 100);
+
+    QGraphicsAnchorLayout *layout = new QGraphicsAnchorLayout();
+/*
+    //! [adding a corner anchor in two steps]
+    layout->addAnchor(a, Qt::AnchorTop, layout, Qt::AnchorTop);
+    layout->addAnchor(a, Qt::AnchorLeft, layout, Qt::AnchorLeft);
+    //! [adding a corner anchor in two steps]
+*/
+    //! [adding a corner anchor]
+    layout->addCornerAnchors(a, Qt::TopLeftCorner, layout, Qt::TopLeftCorner);
+    //! [adding a corner anchor]
+
+    //! [adding anchors]
+    layout->addAnchor(b, Qt::AnchorLeft, a, Qt::AnchorRight);
+    layout->addAnchor(b, Qt::AnchorTop, a, Qt::AnchorBottom);
+    //! [adding anchors]
+
+    // Place a third widget below the second.
+    layout->addAnchor(b, Qt::AnchorBottom, c, Qt::AnchorTop);
+
+/*
+    //! [adding anchors to match sizes in two steps]
+    layout->addAnchor(b, Qt::AnchorLeft, c, Qt::AnchorLeft);
+    layout->addAnchor(b, Qt::AnchorRight, c, Qt::AnchorRight);
+    //! [adding anchors to match sizes in two steps]
+*/
+
+    //! [adding anchors to match sizes]
+    layout->addAnchors(b, c, Qt::Horizontal);
+    //! [adding anchors to match sizes]
+
+    // Anchor the bottom-right corner of the third widget to the bottom-right
+    // corner of the layout.
+    layout->addCornerAnchors(c, Qt::BottomRightCorner, layout, Qt::BottomRightCorner);
+
+    QGraphicsWidget *w = new QGraphicsWidget(0, Qt::Window | Qt::CustomizeWindowHint | Qt::WindowTitleHint);
+    w->setPos(20, 20);
+    w->setMinimumSize(100, 100);
+    w->setPreferredSize(320, 240);
+    w->setLayout(layout);
+    w->setWindowTitle(QApplication::translate("simpleanchorlayout", "QGraphicsAnchorLayout in use"));
+    scene->addItem(w);
+
+    QGraphicsView *view = new QGraphicsView();
+    view->setScene(scene);
+    view->setWindowTitle(QApplication::translate("simpleanchorlayout", "Simple Anchor Layout"));
+    view->resize(360, 320);
+    view->show();
+
+    return app.exec();
+}
diff --git a/examples/graphicsview/simpleanchorlayout/simpleanchorlayout.pro b/examples/graphicsview/simpleanchorlayout/simpleanchorlayout.pro
new file mode 100644
index 0000000000..e1c7aeb446
--- /dev/null
+++ b/examples/graphicsview/simpleanchorlayout/simpleanchorlayout.pro
@@ -0,0 +1,9 @@
+SOURCES   = main.cpp
+
+# install
+target.path = $$[QT_INSTALL_EXAMPLES]/graphicsview/simpleanchorlayout
+sources.files = $$SOURCES $$HEADERS $$RESOURCES simpleanchorlayout.pro
+sources.path = $$[QT_INSTALL_EXAMPLES]/graphicsview/simpleanchorlayout
+INSTALLS += target sources
+
+TARGET = simpleanchorlayout
diff --git a/src/gui/graphicsview/qgraphicsanchorlayout.cpp b/src/gui/graphicsview/qgraphicsanchorlayout.cpp
index 081572f2bc..e21cd999c7 100644
--- a/src/gui/graphicsview/qgraphicsanchorlayout.cpp
+++ b/src/gui/graphicsview/qgraphicsanchorlayout.cpp
@@ -48,36 +48,60 @@
     \ingroup geomanagement
     \ingroup graphicsview-api
 
-    The anchor layout is a layout where one can specify how widgets should be placed relative to
-    each other. The specification is called an anchor, and it is set up by calling anchor().
+    The anchor layout allows developers to specify how widgets should be placed relative to
+    each other, and to the layout itself. The specification is made by adding anchors to the
+    layout by calling addAnchor(), addAnchors() or addCornerAnchors().
+
+    Existing anchors in the layout can be accessed with the anchor() function.
+    Items that are anchored are automatically added to the layout, and if items
+    are removed, all their anchors will be automatically removed.
+
+    \beginfloatleft
+    \inlineimage simpleanchorlayout-example.png Using an anchor layout to align simple colored widgets.
+    \endfloat
+
     Anchors are always set up between edges of an item, where the "center" is also considered to
-    be an edge. Considering this example:
-    \code
-        QGraphicsAnchorLayout *l = new QGraphicsAnchorLayout;
-        QGraphicsWidget *a = new QGraphicsWidget;
-        QGraphicsWidget *b = new QGraphicsWidget;
-        l->anchor(a, Qt::AnchorRight, b, Qt::AnchorLeft);
-    \endcode
-
-    Here is the right edge of item A anchored to the left edge of item B, with the result that
-    item B will be placed to the right of item A, with a spacing between A and B. If the
-    spacing is negative, the items will overlap to some extent. Items that are anchored are
-    automatically added to the layout, and if items are removed, all their anchors will be
-    automatically removed
-
-    \section1 Size Hints and Size Policies in QGraphicsAnchorLayout
+    be an edge. Consider the following example:
+
+    \snippet examples/graphicsview/simpleanchorlayout/main.cpp adding anchors
+
+    Here, the right edge of item \c a is anchored to the left edge of item \c b and the bottom
+    edge of item \c a is anchored to the top edge of item \c b, with the result that
+    item \c b will be placed diagonally to the right and below item \c b.
+
+    The addCornerAnchors() function provides a simpler way of anchoring the corners
+    of two widgets than the two individual calls to addAnchor() shown in the code
+    above. Here, we see how a widget can be anchored to the top-left corner of the enclosing
+    layout:
+
+    \snippet examples/graphicsview/simpleanchorlayout/main.cpp adding a corner anchor
+
+    In cases where anchors are used to match the widths or heights of widgets, it is
+    convenient to use the addAnchors() function. As with the other functions for specifying
+    anchors, it can also be used to anchor a widget to a layout.
+
+    \clearfloat
+    \section1 Size Hints and Size Policies in an Anchor Layout
 
     QGraphicsAnchorLayout respects each item's size hints and size policies. However it does
-    not respect stretch factors currently. This might change in the future, so please refrain
-    from using stretch factors in anchor layout to avoid any future regressions.
+    not currently respect their stretch factors. This might change in the future, so avoid
+    using stretch factors in anchor layouts if you want to avoid any future regressions in
+    behavior.
+
+    \section1 Spacing within an Anchor Layout
+
+    The layout may distribute some space between the items. If the spacing has not been
+    explicitly specified, the actual amount of space will usually be 0.
+
+    However, if the first edge is the \e opposite of the second edge (e.g., the right edge
+    of the first widget is anchored to the left edge of the second widget), the size of the
+    anchor will be queried from the style through a pixel metric:
+    \l{QStyle::}{PM_LayoutHorizontalSpacing} for horizontal anchors and
+    \l{QStyle::}{PM_LayoutVerticalSpacing} for vertical anchors.
 
-    \section1 Spacing within QGraphicsAnchorLayout
+    If the spacing is negative, the items will overlap to some extent.
 
-    Between the items, the layout can distribute some space. If the spacing has not been
-    explicitly specified, the actual amount of space will usually be 0, but if the first edge
-    is the "opposite" of the second edge (i.e. Right is anchored to Left or vice-versa), the
-    size of the anchor will be queried from the style through the pixelMetric
-    PM_LayoutHorizontalSpacing (or PM_LayoutVerticalSpacing for vertical anchors).
+    \sa QGraphicsLinearLayout, QGraphicsGridLayout, QGraphicsLayout
 */
 
 /*!
@@ -215,7 +239,7 @@ QGraphicsAnchorLayout::~QGraphicsAnchorLayout()
     If there is already an anchor between the edges, the the new anchor will replace the old one.
 
     \a firstItem and \a secondItem are automatically added to the layout if they are not part
-    of the layout. This means that count() can increase with up to 2.
+    of the layout. This means that count() can increase by up to 2.
 
     The spacing an anchor will get depends on the type of anchor. For instance, anchors from the
     Right edge of one item to the Left edge of another (or vice versa) will use the default
@@ -228,7 +252,7 @@ QGraphicsAnchorLayout::~QGraphicsAnchorLayout()
     Calling this function where \a firstItem or \a secondItem are ancestors of the layout have
     undefined behaviour.
 
-    \sa addCornerAnchors(), addAnchors()
+    \sa addAnchors(), addCornerAnchors()
  */
 QGraphicsAnchor *
 QGraphicsAnchorLayout::addAnchor(QGraphicsLayoutItem *firstItem, Qt::AnchorPoint firstEdge,
@@ -253,29 +277,26 @@ QGraphicsAnchorLayout::anchor(QGraphicsLayoutItem *firstItem, Qt::AnchorPoint fi
 }
 
 /*!
-    Creates two anchors between \a firstItem and \a secondItem, where one is for the horizontal
-    edge and another one for the vertical edge that the corners \a firstCorner and \a
-    secondCorner specifies.
-    The magnitude of the anchors is picked up from the style.
+    Creates two anchors between \a firstItem and \a secondItem specified by the corners,
+    \a firstCorner and \a secondCorner, where one is for the horizontal edge and another
+    one for the vertical edge.
 
-    This is a convenience function, since anchoring corners can be expressed as anchoring two edges.
-    For instance,
-    \code
-      layout->addAnchor(layout, Qt::AnchorTop, b, Qt::AnchorTop);
-      layout->addAnchor(layout, Qt::AnchorLeft, b, Qt::AnchorLeft);
-    \endcode
+    This is a convenience function, since anchoring corners can be expressed as anchoring
+    two edges. For instance:
 
-    has the same effect as
+    \snippet examples/graphicsview/simpleanchorlayout/main.cpp adding a corner anchor in two steps
 
-    \code
-      layout->addCornerAnchors(layout, Qt::TopLeft, b, Qt::TopLeft);
-    \endcode
+    This can also be achieved with the following line of code:
+
+    \snippet examples/graphicsview/simpleanchorlayout/main.cpp adding a corner anchor
 
     If there is already an anchor between the edge pairs, it will be replaced by the anchors that
     this function specifies.
 
     \a firstItem and \a secondItem are automatically added to the layout if they are not part of the
-    layout. This means that count() can increase with up to 2.
+    layout. This means that count() can increase by up to 2.
+
+    \sa addAnchor(), addAnchors()
 */
 void QGraphicsAnchorLayout::addCornerAnchors(QGraphicsLayoutItem *firstItem,
                                              Qt::Corner firstCorner,
@@ -302,17 +323,16 @@ void QGraphicsAnchorLayout::addCornerAnchors(QGraphicsLayoutItem *firstItem,
     edges of \a secondItem, so that \a firstItem has the same size as
     \a secondItem in the dimensions specified by \a orientations.
 
-    Calling this convenience function with the following arguments
-    \code
-    l->addAnchors(firstItem, secondItem, Qt::Horizontal)
-    \endcode
+    For example, the following example anchors the left and right edges of two items
+    to match their widths:
+
+    \snippet examples/graphicsview/simpleanchorlayout/main.cpp adding anchors to match sizes in two steps
+
+    This can also be achieved using the following line of code:
 
-    is the same as
+    \snippet examples/graphicsview/simpleanchorlayout/main.cpp adding anchors to match sizes
 
-    \code
-    l->addAnchor(firstItem, Qt::AnchorLeft, secondItem, Qt::AnchorLeft);
-    l->addAnchor(firstItem, Qt::AnchorRight, secondItem, Qt::AnchorRight);
-    \endcode
+    \sa addAnchor(), addCornerAnchors()
 */
 void QGraphicsAnchorLayout::addAnchors(QGraphicsLayoutItem *firstItem,
                                        QGraphicsLayoutItem *secondItem,