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 #include "qapplication.h"

    43 

    44 #ifndef QT_NO_GRAPHICSVIEW

    45 #include "qgraphicslayout.h"

    46 #include "qgraphicslayout_p.h"

    47 #include "qgraphicslayoutitem.h"

    48 #include "qgraphicslayoutitem_p.h"

    49 #include "qgraphicswidget.h"

    50 #include "qgraphicswidget_p.h"

    51 #include "qgraphicsscene.h"

    52 

    53 QT_BEGIN_NAMESPACE

    54 

    55 /*!

    56     \class QGraphicsLayout

    57     \brief The QGraphicsLayout class provides the base class for all layouts

    58     in Graphics View.

    59     \since 4.4

    60     \ingroup graphicsview-api

    61 

    62     QGraphicsLayout is an abstract class that defines a virtual API for

    63     arranging QGraphicsWidget children and other QGraphicsLayoutItem objects

    64     for a QGraphicsWidget. QGraphicsWidget assigns responsibility to a

    65     QGraphicsLayout through QGraphicsWidget::setLayout(). As the widget

    66     is resized, the layout will automatically arrange the widget's children.

    67     QGraphicsLayout inherits QGraphicsLayoutItem, so, it can be managed by

    68     any layout, including its own subclasses.

    69 

    70     \section1 Writing a Custom Layout

    71 

    72     You can use QGraphicsLayout as a base to write your own custom layout

    73     (e.g., a flowlayout), but it is more common to use one of its subclasses

    74     instead - QGraphicsLinearLayout or QGraphicsGridLayout. When creating

    75     a custom layout, the following functions must be reimplemented as a bare

    76     minimum:

    77 

    78     \table

    79     \header \o Function                     \o Description

    80     \row     \o QGraphicsLayoutItem::setGeometry()

    81                \o Notifies you when the geometry of the layout is set. You can

    82                    store the geometry in your own layout class in a reimplementation

    83                    of this function.

    84     \row    \o QGraphicsLayoutItem::sizeHint()

    85                \o Returns the layout's size hints.

    86     \row    \o QGraphicsLayout::count()

    87               \o Returns the number of items in your layout.

    88     \row    \o QGraphicsLayout::itemAt()

    89               \o Returns a pointer to an item in your layout.

    90     \row    \o QGraphicsLayout::removeAt()

    91               \o Removes an item from your layout without destroying it.

    92     \endtable

    93 

    94     For more details on how to implement each function, refer to the individual

    95     function documentation.

    96 

    97     Each layout defines its own API for arranging widgets and layout items.

    98     For example, with a grid layout, you require a row and a

    99     column index with optional row and column spans, alignment, spacing, and more.

   100     A linear layout, however, requires a single row or column index to position its

   101     items. For a grid layout, the order of insertion does not affect the layout in

   102     any way, but for a linear layout, the order is essential. When writing your own

   103     layout subclass, you are free to choose the API that best suits your layout.

   104 

   105     \section1 Activating the Layout

   106 

   107     When the layout's geometry changes, QGraphicsLayout immediately rearranges

   108     all of its managed items by calling setGeometry() on each item. This

   109     rearrangement is called \e activating the layout.

   110 

   111     QGraphicsLayout updates its own geometry to match the contentsRect() of the

   112     QGraphicsLayoutItem it is managing. Thus, it will automatically rearrange all

   113     its items when the widget is resized. QGraphicsLayout caches the sizes of all

   114     its managed items to avoid calling setGeometry() too often.

   115 

   116     \note A QGraphicsLayout will have the same geometry as the contentsRect()

   117     of the widget (not the layout) it is assigned to.

   118 

   119     \section2 Activating the Layout Implicitly

   120 

   121     The layout can be activated implicitly using one of two ways: by calling

   122     activate() or by calling invalidate(). Calling activate() activates the layout

   123     immediately. In contrast, calling invalidate() is delayed, as it posts a

   124     \l{QEvent::LayoutRequest}{LayoutRequest} event to the managed widget. Due

   125     to event compression, the activate() will only be called once after control has

   126     returned to the event loop. This is referred to as \e invalidating the layout.

   127     Invalidating the layout also invalidates any cached information. Also, the

   128     invalidate() function is a virtual function. So, you can invalidate your own

   129     cache in a subclass of QGraphicsLayout by reimplementing this function.

   130 

   131     \section1 Event Handling

   132 

   133     QGraphicsLayout listens to events for the widget it manages through the

   134     virtual widgetEvent() event handler. When the layout is assigned to a

   135     widget, all events delivered to the widget are first processed by

   136     widgetEvent(). This allows the layout to be aware of any relevant state

   137     changes on the widget such as visibility changes or layout direction changes.

   138 

   139     \section1 Margin Handling

   140 

   141     The margins of a QGraphicsLayout can be modified by reimplementing

   142     setContentsMargins() and getContentsMargins().

   143 

   144 */

   145 

   146 /*!

   147     Contructs a QGraphicsLayout object.

   148     

   149     \a parent is passed to QGraphicsLayoutItem's constructor and the

   150     QGraphicsLayoutItem's isLayout argument is set to \e true.

   151 */

   152 QGraphicsLayout::QGraphicsLayout(QGraphicsLayoutItem *parent)

   153     : QGraphicsLayoutItem(*new QGraphicsLayoutPrivate)

   154 {

   155     setParentLayoutItem(parent);

   156     if (parent && !parent->isLayout()) {

   157         // If a layout has a parent that is not a layout it must be a QGraphicsWidget.

   158         QGraphicsItem *itemParent = parent->graphicsItem();

   159         if (itemParent && itemParent->isWidget()) {

   160             static_cast<QGraphicsWidget *>(itemParent)->d_func()->setLayout_helper(this);

   161         } else {

   162             qWarning("QGraphicsLayout::QGraphicsLayout: Attempt to create a layout with a parent that is"

   163                     " neither a QGraphicsWidget nor QGraphicsLayout");

   164         }

   165     }

   166     setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Expanding, QSizePolicy::DefaultType);

   167     setOwnedByLayout(true);

   168 }

   169 

   170 /*!

   171     \internal

   172 */

   173 QGraphicsLayout::QGraphicsLayout(QGraphicsLayoutPrivate &dd, QGraphicsLayoutItem *parent)

   174     : QGraphicsLayoutItem(dd)

   175 {

   176     setParentLayoutItem(parent);

   177     if (parent && !parent->isLayout()) {

   178         // If a layout has a parent that is not a layout it must be a QGraphicsWidget.

   179         QGraphicsItem *itemParent = parent->graphicsItem();

   180         if (itemParent && itemParent->isWidget()) {

   181             static_cast<QGraphicsWidget *>(itemParent)->d_func()->setLayout_helper(this);

   182         } else {

   183             qWarning("QGraphicsLayout::QGraphicsLayout: Attempt to create a layout with a parent that is"

   184                     " neither a QGraphicsWidget nor QGraphicsLayout");

   185         }

   186     }

   187     setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Expanding, QSizePolicy::DefaultType);

   188     setOwnedByLayout(true);

   189 }

   190 

   191 /*!

   192     Destroys the QGraphicsLayout object.

   193 */

   194 QGraphicsLayout::~QGraphicsLayout()

   195 {

   196 }

   197 

   198 /*!

   199     Sets the contents margins to \a left, \a top, \a right and \a bottom. The

   200     default contents margins for toplevel layouts are style dependent

   201     (by querying the pixelMetric for QStyle::PM_LayoutLeftMargin,

   202     QStyle::PM_LayoutTopMargin, QStyle::PM_LayoutRightMargin and

   203     QStyle::PM_LayoutBottomMargin).

   204 

   205     For sublayouts the default margins are 0.

   206 

   207     Changing the contents margins automatically invalidates the layout.

   208 

   209     \sa invalidate()

   210 */

   211 void QGraphicsLayout::setContentsMargins(qreal left, qreal top, qreal right, qreal bottom)

   212 {

   213     Q_D(QGraphicsLayout);

   214     if (d->left == left && d->top == top && d->right == right && d->bottom == bottom)

   215         return;

   216     d->left = left;

   217     d->right = right;

   218     d->top = top;

   219     d->bottom = bottom;

   220     invalidate();

   221 }

   222 

   223 /*!

   224     \reimp

   225 */

   226 void QGraphicsLayout::getContentsMargins(qreal *left, qreal *top, qreal *right, qreal *bottom) const

   227 {

   228     Q_D(const QGraphicsLayout);

   229     d->getMargin(left, d->left, QStyle::PM_LayoutLeftMargin);

   230     d->getMargin(top, d->top, QStyle::PM_LayoutTopMargin);

   231     d->getMargin(right, d->right, QStyle::PM_LayoutRightMargin);

   232     d->getMargin(bottom, d->bottom, QStyle::PM_LayoutBottomMargin);

   233 }

   234 

   235 /*!

   236     Activates the layout, causing all items in the layout to be immediately

   237     rearranged. This function is based on calling count() and itemAt(), and

   238     then calling setGeometry() on all items sequentially. When activated,

   239     the layout will adjust its geometry to its parent's contentsRect().

   240     The parent will then invalidate any layout of its own.

   241 

   242     If called in sequence or recursively, e.g., by one of the arranged items

   243     in response to being resized, this function will do nothing.

   244 

   245     Note that the layout is free to use geometry caching to optimize this

   246     process.  To forcefully invalidate any such cache, you can call

   247     invalidate() before calling activate().

   248 

   249     \sa invalidate()

   250 */

   251 void QGraphicsLayout::activate()

   252 {

   253     Q_D(QGraphicsLayout);

   254     if (d->activated)

   255         return;

   256 

   257     d->activateRecursive(this);

   258     

   259     // we don't call activate on a sublayout, but somebody might.

   260     // Therefore, we walk to the parentitem of the toplevel layout.

   261     QGraphicsLayoutItem *parentItem = this;

   262     while (parentItem && parentItem->isLayout())

   263         parentItem = parentItem->parentLayoutItem();

   264     if (!parentItem)

   265         return;

   266     Q_ASSERT(!parentItem->isLayout());

   267 

   268     setGeometry(parentItem->contentsRect());    // relayout children

   269     

   270     // ### bug, should be parentItem ?

   271     parentLayoutItem()->updateGeometry();            // bubble up; will set activated to false

   272     // ### too many resizes? maybe we should walk up the chain to the

   273     // ### top-level layouted layoutItem and call activate there.

   274 }

   275 

   276 /*!

   277     Returns true if the layout is currently being activated; otherwise,

   278     returns false. If the layout is being activated, this means that it is

   279     currently in the process of rearranging its items (i.e., the activate()

   280     function has been called, and has not yet returned).

   281 

   282     \sa activate(), invalidate()

   283 */

   284 bool QGraphicsLayout::isActivated() const

   285 {

   286     Q_D(const QGraphicsLayout);

   287     return d->activated;

   288 }

   289 

   290 /*!

   291     Clears any cached geometry and size hint information in the layout, and

   292     posts a \l{QEvent::LayoutRequest}{LayoutRequest} event to the managed

   293     parent QGraphicsLayoutItem.

   294 

   295     \sa activate(), setGeometry()

   296 */

   297 void QGraphicsLayout::invalidate()

   298 {

   299     // only mark layouts as invalid (activated = false) if we can post a LayoutRequest event.

   300     QGraphicsLayoutItem *layoutItem = this;

   301     while (layoutItem && layoutItem->isLayout()) {

   302         // we could call updateGeometry(), but what if that method

   303         // does not call the base implementation? In addition, updateGeometry()

   304         // does more than we need.

   305         layoutItem->d_func()->sizeHintCacheDirty = true;

   306         layoutItem = layoutItem->parentLayoutItem();        

   307     }

   308     if (layoutItem)

   309         layoutItem->d_func()->sizeHintCacheDirty = true;

   310 

   311     bool postIt = layoutItem ? !layoutItem->isLayout() : false;

   312     if (postIt) {

   313         layoutItem = this;

   314         while (layoutItem && layoutItem->isLayout()

   315                 && static_cast<QGraphicsLayout*>(layoutItem)->d_func()->activated) {

   316             static_cast<QGraphicsLayout*>(layoutItem)->d_func()->activated = false;

   317             layoutItem = layoutItem->parentLayoutItem();

   318         }

   319         if (layoutItem && !layoutItem->isLayout()) {

   320             // If a layout has a parent that is not a layout it must be a QGraphicsWidget.

   321             QApplication::postEvent(static_cast<QGraphicsWidget *>(layoutItem), new QEvent(QEvent::LayoutRequest));

   322         }

   323     }

   324 }

   325 

   326 /*!

   327     \reimp

   328 */

   329 void QGraphicsLayout::updateGeometry()

   330 {

   331     QGraphicsLayoutItem::updateGeometry();

   332     if (QGraphicsLayoutItem *parentItem = parentLayoutItem()) {

   333         if (parentItem->isLayout()) {

   334             parentItem->updateGeometry();

   335         } else {

   336             invalidate();

   337         }

   338     }

   339 }

   340 

   341 /*!

   342     This virtual event handler receives all events for the managed

   343     widget. QGraphicsLayout uses this event handler to listen for layout

   344     related events such as geometry changes, layout changes or layout

   345     direction changes.

   346     

   347     \a e is a pointer to the event.

   348 

   349     You can reimplement this event handler to track similar events for your

   350     own custom layout.

   351 

   352     \sa QGraphicsWidget::event(), QGraphicsItem::sceneEvent()

   353 */

   354 void QGraphicsLayout::widgetEvent(QEvent *e)

   355 {

   356     switch (e->type()) {

   357     case QEvent::GraphicsSceneResize:

   358         if (isActivated()) {

   359             setGeometry(parentLayoutItem()->contentsRect());

   360         } else {

   361             activate(); // relies on that activate() will call updateGeometry()

   362         }

   363         break;

   364     case QEvent::LayoutRequest:

   365         activate();

   366         break;

   367     case QEvent::LayoutDirectionChange:

   368         invalidate();

   369         break;

   370     default:

   371         break;

   372     }

   373 }

   374 

   375 /*!

   376     \fn virtual int QGraphicsLayout::count() const = 0

   377 

   378     This pure virtual function must be reimplemented in a subclass of

   379     QGraphicsLayout to return the number of items in the layout.

   380 

   381     The subclass is free to decide how to store the items.

   382 

   383     \sa itemAt(), removeAt()

   384 */

   385 

   386 /*!

   387     \fn virtual QGraphicsLayoutItem *QGraphicsLayout::itemAt(int i) const = 0

   388 

   389     This pure virtual function must be reimplemented in a subclass of

   390     QGraphicsLayout to return a pointer to the item at index \a i. The

   391     reimplementation can assume that \a i is valid (i.e., it respects the

   392     value of count()).

   393     Together with count(), it is provided as a means of iterating over all items in a layout.

   394 

   395     The subclass is free to decide how to store the items, and the visual arrangement

   396     does not have to be reflected through this function.

   397 

   398     \sa count(), removeAt()

   399 */

   400 

   401 /*!

   402     \fn virtual void QGraphicsLayout::removeAt(int index) = 0

   403 

   404     This pure virtual function must be reimplemented in a subclass of

   405     QGraphicsLayout to remove the item at \a index. The

   406     reimplementation can assume that \a index is valid (i.e., it

   407     respects the value of count()).

   408 

   409     The implementation must ensure that the parentLayoutItem() of

   410     the removed item does not point to this layout, since the item is

   411     considered to be removed from the layout hierarchy.

   412 

   413     If the layout is to be reused between applications, we recommend

   414     that the layout deletes the item, but the graphics view framework

   415     does not depend on this.

   416 

   417     The subclass is free to decide how to store the items.

   418 

   419     \sa itemAt(), count()

   420 */

   421 

   422 /*!

   423     \since 4.6

   424 

   425     This function is a convenience function provided for custom layouts, and will go through

   426     all items in the layout and reparent their graphics items to the closest QGraphicsWidget

   427     ancestor of the layout.

   428 

   429     If \a layoutItem is already in a different layout, it will be removed  from that layout.

   430 

   431     If custom layouts want special behaviour they can ignore to use this function, and implement

   432     their own behaviour.

   433 

   434     \sa graphicsItem()

   435  */

   436 void QGraphicsLayout::addChildLayoutItem(QGraphicsLayoutItem *layoutItem)

   437 {

   438     Q_D(QGraphicsLayout);

   439     d->addChildLayoutItem(layoutItem);

   440 }

   441 

   442 QT_END_NAMESPACE

   443 

   444 #endif //QT_NO_GRAPHICSVIEW