1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the QtGui module of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*!

    43     \class QGraphicsAnchorLayout

    44     \brief The QGraphicsAnchorLayout class provides a layout where one can anchor widgets

    45     together in Graphics View.

    46     \since 4.6

    47     \ingroup appearance

    48     \ingroup geomanagement

    49     \ingroup graphicsview-api

    50 

    51     The anchor layout is a layout where one can specify how widgets should be placed relative to

    52     each other. The specification is called an anchor, and it is set up by calling anchor().

    53     Anchors are always set up between edges of an item, where the "center" is also considered to

    54     be an edge. Considering this example:

    55     \code

    56         QGraphicsAnchorLayout *l = new QGraphicsAnchorLayout;

    57         QGraphicsWidget *a = new QGraphicsWidget;

    58         QGraphicsWidget *b = new QGraphicsWidget;

    59         l->anchor(a, Qt::AnchorRight, b, Qt::AnchorLeft);

    60     \endcode

    61 

    62     Here is the right edge of item A anchored to the left edge of item B, with the result that

    63     item B will be placed to the right of item A, with a spacing between A and B. If the

    64     spacing is negative, the items will overlap to some extent. Items that are anchored are

    65     automatically added to the layout, and if items are removed, all their anchors will be

    66     automatically removed

    67 

    68     \section1 Size Hints and Size Policies in QGraphicsAnchorLayout

    69 

    70     QGraphicsAnchorLayout respects each item's size hints and size policies. However it does

    71     not respect stretch factors currently. This might change in the future, so please refrain

    72     from using stretch factors in anchor layout to avoid any future regressions.

    73 

    74     \section1 Spacing within QGraphicsAnchorLayout

    75 

    76     Between the items, the layout can distribute some space. If the spacing has not been

    77     explicitly specified, the actual amount of space will usually be 0, but if the first edge

    78     is the "opposite" of the second edge (i.e. Right is anchored to Left or vice-versa), the

    79     size of the anchor will be queried from the style through the pixelMetric

    80     PM_LayoutHorizontalSpacing (or PM_LayoutVerticalSpacing for vertical anchors).

    81 */

    82 

    83 /*!

    84     \class QGraphicsAnchor

    85     \brief The QGraphicsAnchor class represents an anchor between two items in a

    86            QGraphicsAnchorLayout.

    87     \since 4.6

    88     \ingroup appearance

    89     \ingroup geomanagement

    90     \ingroup graphicsview-api

    91 

    92     The graphics anchor provides an API that enables you to query and manipulate the

    93     properties an anchor has. When an anchor is added to the layout with

    94     QGraphicsAnchorLayout::addAnchor(), a QGraphicsAnchor instance is returned where the properties

    95     are initialized to their default values. The properties can then be further changed, and they

    96     will be picked up the next time the layout is activated.

    97 

    98     \sa QGraphicsAnchorLayout::anchor()

    99 

   100 */

   101 #include "qgraphicsanchorlayout_p.h"

   102 

   103 QT_BEGIN_NAMESPACE

   104 

   105 QGraphicsAnchor::QGraphicsAnchor(QGraphicsAnchorLayout *parentLayout)

   106     : QObject(*(new QGraphicsAnchorPrivate))

   107 {

   108     Q_D(QGraphicsAnchor);

   109     Q_ASSERT(parentLayout);

   110     d->layoutPrivate = parentLayout->d_func();

   111 }

   112 

   113 /*!

   114     Removes the QGraphicsAnchor object from the layout and destroys it.

   115 */

   116 QGraphicsAnchor::~QGraphicsAnchor()

   117 {

   118 }

   119 

   120 /*!

   121     \property QGraphicsAnchor::sizePolicy

   122     \brief the size policy for the QGraphicsAnchor.

   123 

   124     By setting the size policy on an anchor you can configure how the item can resize itself

   125     from its preferred spacing. For instance, if the anchor has the size policy

   126     QSizePolicy::Minimum, the spacing is the minimum size of the anchor. However, its size

   127     can grow up to the anchors maximum size. If the default size policy is QSizePolicy::Fixed,

   128     the anchor can neither grow or shrink, which means that the only size the anchor can have

   129     is the spacing. QSizePolicy::Fixed is the default size policy.

   130     QGraphicsAnchor always has a minimum spacing of 0 and a very large maximum spacing.

   131 

   132     \sa QGraphicsAnchor::spacing

   133 */

   134 

   135 void QGraphicsAnchor::setSizePolicy(QSizePolicy::Policy policy)

   136 {

   137     Q_D(QGraphicsAnchor);

   138     d->setSizePolicy(policy);

   139 }

   140 

   141 QSizePolicy::Policy QGraphicsAnchor::sizePolicy() const

   142 {

   143     Q_D(const QGraphicsAnchor);

   144     return d->sizePolicy;

   145 }

   146 

   147 /*!

   148     \property QGraphicsAnchor::spacing

   149     \brief the preferred space between items in the QGraphicsAnchorLayout.

   150 

   151     Depending on the anchor type, the default spacing is either

   152     0 or a value returned from the style.

   153 

   154     \sa QGraphicsAnchorLayout::addAnchor()

   155 */

   156 void QGraphicsAnchor::setSpacing(qreal spacing)

   157 {

   158     Q_D(QGraphicsAnchor);

   159     d->setSpacing(spacing);

   160 }

   161 

   162 qreal QGraphicsAnchor::spacing() const

   163 {

   164     Q_D(const QGraphicsAnchor);

   165     return d->spacing();

   166 }

   167 

   168 void QGraphicsAnchor::unsetSpacing()

   169 {

   170     Q_D(QGraphicsAnchor);

   171     d->unsetSpacing();

   172 }

   173 

   174 /*!

   175     Constructs a QGraphicsAnchorLayout instance.  \a parent is passed to

   176     QGraphicsLayout's constructor.

   177   */

   178 QGraphicsAnchorLayout::QGraphicsAnchorLayout(QGraphicsLayoutItem *parent)

   179     : QGraphicsLayout(*new QGraphicsAnchorLayoutPrivate(), parent)

   180 {

   181     Q_D(QGraphicsAnchorLayout);

   182     d->createLayoutEdges();

   183 }

   184 

   185 /*!

   186     Destroys the QGraphicsAnchorLayout object.

   187 */

   188 QGraphicsAnchorLayout::~QGraphicsAnchorLayout()

   189 {

   190     Q_D(QGraphicsAnchorLayout);

   191 

   192     for (int i = count() - 1; i >= 0; --i) {

   193         QGraphicsLayoutItem *item = d->items.at(i);

   194         removeAt(i);

   195         if (item) {

   196             if (item->ownedByLayout())

   197                 delete item;

   198         }

   199     }

   200 

   201     d->removeCenterConstraints(this, QGraphicsAnchorLayoutPrivate::Horizontal);

   202     d->removeCenterConstraints(this, QGraphicsAnchorLayoutPrivate::Vertical);

   203     d->deleteLayoutEdges();

   204 

   205     Q_ASSERT(d->itemCenterConstraints[0].isEmpty());

   206     Q_ASSERT(d->itemCenterConstraints[1].isEmpty());

   207     Q_ASSERT(d->items.isEmpty());

   208     Q_ASSERT(d->m_vertexList.isEmpty());

   209 }

   210 

   211 /*!

   212     Creates an anchor between the edge \a firstEdge of item \a firstItem and the edge \a secondEdge

   213     of item \a secondItem. The magnitude of the anchor is picked up from the style. Anchors

   214     between a layout edge and an item edge will have a size of 0.

   215     If there is already an anchor between the edges, the the new anchor will replace the old one.

   216 

   217     \a firstItem and \a secondItem are automatically added to the layout if they are not part

   218     of the layout. This means that count() can increase with up to 2.

   219 

   220     The spacing an anchor will get depends on the type of anchor. For instance, anchors from the

   221     Right edge of one item to the Left edge of another (or vice versa) will use the default

   222     horizontal spacing. The same behaviour applies to Bottom to Top anchors, (but they will use

   223     the default vertical spacing). For all other anchor combinations, the spacing will be 0.

   224     All anchoring functions will follow this rule.

   225 

   226     The spacing can also be set manually by using QGraphicsAnchor::setSpacing() method.

   227 

   228     Calling this function where \a firstItem or \a secondItem are ancestors of the layout have

   229     undefined behaviour.

   230 

   231     \sa addCornerAnchors(), addAnchors()

   232  */

   233 QGraphicsAnchor *

   234 QGraphicsAnchorLayout::addAnchor(QGraphicsLayoutItem *firstItem, Qt::AnchorPoint firstEdge,

   235                                  QGraphicsLayoutItem *secondItem, Qt::AnchorPoint secondEdge)

   236 {

   237     Q_D(QGraphicsAnchorLayout);

   238     QGraphicsAnchor *a = d->addAnchor(firstItem, firstEdge, secondItem, secondEdge);

   239     invalidate();

   240     return a;

   241 }

   242 

   243 /*!

   244     Returns the anchor between the anchor points defined by \a firstItem and \a firstEdge and

   245     \a secondItem and \a secondEdge. If there is no such anchor, the function will return 0.

   246 */

   247 QGraphicsAnchor *

   248 QGraphicsAnchorLayout::anchor(QGraphicsLayoutItem *firstItem, Qt::AnchorPoint firstEdge,

   249                               QGraphicsLayoutItem *secondItem, Qt::AnchorPoint secondEdge)

   250 {

   251     Q_D(QGraphicsAnchorLayout);

   252     return d->getAnchor(firstItem, firstEdge, secondItem, secondEdge);

   253 }

   254 

   255 /*!

   256     Creates two anchors between \a firstItem and \a secondItem, where one is for the horizontal

   257     edge and another one for the vertical edge that the corners \a firstCorner and \a

   258     secondCorner specifies.

   259     The magnitude of the anchors is picked up from the style.

   260 

   261     This is a convenience function, since anchoring corners can be expressed as anchoring two edges.

   262     For instance,

   263     \code

   264       layout->addAnchor(layout, Qt::AnchorTop, b, Qt::AnchorTop);

   265       layout->addAnchor(layout, Qt::AnchorLeft, b, Qt::AnchorLeft);

   266     \endcode

   267 

   268     has the same effect as

   269 

   270     \code

   271       layout->addCornerAnchors(layout, Qt::TopLeft, b, Qt::TopLeft);

   272     \endcode

   273 

   274     If there is already an anchor between the edge pairs, it will be replaced by the anchors that

   275     this function specifies.

   276 

   277     \a firstItem and \a secondItem are automatically added to the layout if they are not part of the

   278     layout. This means that count() can increase with up to 2.

   279 */

   280 void QGraphicsAnchorLayout::addCornerAnchors(QGraphicsLayoutItem *firstItem,

   281                                              Qt::Corner firstCorner,

   282                                              QGraphicsLayoutItem *secondItem,

   283                                              Qt::Corner secondCorner)

   284 {

   285     Q_D(QGraphicsAnchorLayout);

   286 

   287     // Horizontal anchor

   288     Qt::AnchorPoint firstEdge = (firstCorner & 1 ? Qt::AnchorRight: Qt::AnchorLeft);

   289     Qt::AnchorPoint secondEdge = (secondCorner & 1 ? Qt::AnchorRight: Qt::AnchorLeft);

   290     d->addAnchor(firstItem, firstEdge, secondItem, secondEdge);

   291 

   292     // Vertical anchor

   293     firstEdge = (firstCorner & 2 ? Qt::AnchorBottom: Qt::AnchorTop);

   294     secondEdge = (secondCorner & 2 ? Qt::AnchorBottom: Qt::AnchorTop);

   295     d->addAnchor(firstItem, firstEdge, secondItem, secondEdge);

   296 

   297     invalidate();

   298 }

   299 

   300 /*!

   301     Anchors two or four edges of \a firstItem with the corresponding

   302     edges of \a secondItem, so that \a firstItem has the same size as

   303     \a secondItem in the dimensions specified by \a orientations.

   304 

   305     Calling this convenience function with the following arguments

   306     \code

   307     l->addAnchors(firstItem, secondItem, Qt::Horizontal)

   308     \endcode

   309 

   310     is the same as

   311 

   312     \code

   313     l->addAnchor(firstItem, Qt::AnchorLeft, secondItem, Qt::AnchorLeft);

   314     l->addAnchor(firstItem, Qt::AnchorRight, secondItem, Qt::AnchorRight);

   315     \endcode

   316 */

   317 void QGraphicsAnchorLayout::addAnchors(QGraphicsLayoutItem *firstItem,

   318                                        QGraphicsLayoutItem *secondItem,

   319                                        Qt::Orientations orientations)

   320 {

   321     if (orientations & Qt::Horizontal) {

   322         addAnchor(secondItem, Qt::AnchorLeft, firstItem, Qt::AnchorLeft);

   323         addAnchor(firstItem, Qt::AnchorRight, secondItem, Qt::AnchorRight);

   324     }

   325     if (orientations & Qt::Vertical) {

   326         addAnchor(secondItem, Qt::AnchorTop, firstItem, Qt::AnchorTop);

   327         addAnchor(firstItem, Qt::AnchorBottom, secondItem, Qt::AnchorBottom);

   328     }

   329 }

   330 

   331 /*!

   332     Sets the default horizontal spacing for the anchor layout to \a spacing.

   333 

   334     \sa horizontalSpacing(), setVerticalSpacing(), setSpacing()

   335 */

   336 void QGraphicsAnchorLayout::setHorizontalSpacing(qreal spacing)

   337 {

   338     Q_D(QGraphicsAnchorLayout);

   339 

   340     // ### We don't support negative spacing yet

   341     if (spacing < 0) {

   342         spacing = 0;

   343         qWarning() << "QGraphicsAnchorLayout does not support negative spacing.";

   344     }

   345 

   346     d->spacings[0] = spacing;

   347     invalidate();

   348 }

   349 

   350 /*!

   351     Sets the default vertical spacing for the anchor layout to \a spacing.

   352 

   353     \sa verticalSpacing(), setHorizontalSpacing(), setSpacing()

   354 */

   355 void QGraphicsAnchorLayout::setVerticalSpacing(qreal spacing)

   356 {

   357     Q_D(QGraphicsAnchorLayout);

   358 

   359     // ### We don't support negative spacing yet

   360     if (spacing < 0) {

   361         spacing = 0;

   362         qWarning() << "QGraphicsAnchorLayout does not support negative spacing.";

   363     }

   364 

   365     d->spacings[1] = spacing;

   366     invalidate();

   367 }

   368 

   369 /*!

   370     Sets the default horizontal and the default vertical spacing for the anchor layout to \a spacing.

   371 

   372     If an item is anchored with no spacing associated with the anchor, it will use the default

   373     spacing.

   374 

   375     Currently QGraphicsAnchorLayout does not support negative default spacings.

   376 

   377     \sa setHorizontalSpacing(), setVerticalSpacing()

   378 */

   379 void QGraphicsAnchorLayout::setSpacing(qreal spacing)

   380 {

   381     Q_D(QGraphicsAnchorLayout);

   382 

   383     // ### Currently we do not support negative anchors inside the graph.

   384     // To avoid those being created by a negative spacing, we must

   385     // make this test.

   386     if (spacing < 0) {

   387         spacing = 0;

   388         qWarning() << "QGraphicsAnchorLayout does not support negative spacing.";

   389     }

   390 

   391     d->spacings[0] = d->spacings[1] = spacing;

   392     invalidate();

   393 }

   394 

   395 /*!

   396     Returns the default horizontal spacing for the anchor layout.

   397 

   398     \sa verticalSpacing(), setHorizontalSpacing()

   399 */

   400 qreal QGraphicsAnchorLayout::horizontalSpacing() const

   401 {

   402     Q_D(const QGraphicsAnchorLayout);

   403     return d->effectiveSpacing(QGraphicsAnchorLayoutPrivate::Horizontal);

   404 }

   405 

   406 /*!

   407     Returns the default vertical spacing for the anchor layout.

   408 

   409     \sa horizontalSpacing(), setVerticalSpacing()

   410 */

   411 qreal QGraphicsAnchorLayout::verticalSpacing() const

   412 {

   413     Q_D(const QGraphicsAnchorLayout);

   414     return d->effectiveSpacing(QGraphicsAnchorLayoutPrivate::Vertical);

   415 }

   416 

   417 /*!

   418     \reimp

   419 */

   420 void QGraphicsAnchorLayout::setGeometry(const QRectF &geom)

   421 {

   422     Q_D(QGraphicsAnchorLayout);

   423 

   424     QGraphicsLayout::setGeometry(geom);

   425     d->calculateVertexPositions(QGraphicsAnchorLayoutPrivate::Horizontal);

   426     d->calculateVertexPositions(QGraphicsAnchorLayoutPrivate::Vertical);

   427     d->setItemsGeometries(geom);

   428 }

   429 

   430 /*!

   431     Removes the layout item at \a index without destroying it. Ownership of

   432     the item is transferred to the caller.

   433 

   434     Removing an item will also remove any of the anchors associated with it.

   435 

   436     \sa itemAt(), count()

   437 */

   438 void QGraphicsAnchorLayout::removeAt(int index)

   439 {

   440     Q_D(QGraphicsAnchorLayout);

   441     QGraphicsLayoutItem *item = d->items.value(index);

   442 

   443     if (!item)

   444         return;

   445 

   446     // Removing an item affects both horizontal and vertical graphs

   447     d->restoreSimplifiedGraph(QGraphicsAnchorLayoutPrivate::Horizontal);

   448     d->restoreSimplifiedGraph(QGraphicsAnchorLayoutPrivate::Vertical);

   449 

   450     d->removeCenterConstraints(item, QGraphicsAnchorLayoutPrivate::Horizontal);

   451     d->removeCenterConstraints(item, QGraphicsAnchorLayoutPrivate::Vertical);

   452     d->removeAnchors(item);

   453     d->items.remove(index);

   454 

   455     item->setParentLayoutItem(0);

   456     invalidate();

   457 }

   458 

   459 /*!

   460     \reimp

   461 */

   462 int QGraphicsAnchorLayout::count() const

   463 {

   464     Q_D(const QGraphicsAnchorLayout);

   465     return d->items.size();

   466 }

   467 

   468 /*!

   469     \reimp

   470 */

   471 QGraphicsLayoutItem *QGraphicsAnchorLayout::itemAt(int index) const

   472 {

   473     Q_D(const QGraphicsAnchorLayout);

   474     return d->items.value(index);

   475 }

   476 

   477 /*!

   478     \reimp

   479 */

   480 void QGraphicsAnchorLayout::invalidate()

   481 {

   482     Q_D(QGraphicsAnchorLayout);

   483     QGraphicsLayout::invalidate();

   484     d->calculateGraphCacheDirty = 1;

   485 }

   486 

   487 /*!

   488     \reimp

   489 */

   490 QSizeF QGraphicsAnchorLayout::sizeHint(Qt::SizeHint which, const QSizeF &constraint) const

   491 {

   492     Q_UNUSED(constraint);

   493     Q_D(const QGraphicsAnchorLayout);

   494 

   495     // Some setup calculations are delayed until the information is

   496     // actually needed, avoiding unnecessary recalculations when

   497     // adding multiple anchors.

   498 

   499     // sizeHint() / effectiveSizeHint() already have a cache

   500     // mechanism, using invalidate() to force recalculation. However

   501     // sizeHint() is called three times after invalidation (for max,

   502     // min and pref), but we just need do our setup once.

   503 

   504     const_cast<QGraphicsAnchorLayoutPrivate *>(d)->calculateGraphs();

   505 

   506     // ### apply constraint!

   507     QSizeF engineSizeHint(

   508         d->sizeHints[QGraphicsAnchorLayoutPrivate::Horizontal][which],

   509         d->sizeHints[QGraphicsAnchorLayoutPrivate::Vertical][which]);

   510 

   511     qreal left, top, right, bottom;

   512     getContentsMargins(&left, &top, &right, &bottom);

   513 

   514     return engineSizeHint + QSizeF(left + right, top + bottom);

   515 }

   516 

   517 QT_END_NAMESPACE