summaryrefslogtreecommitdiff
path: root/src/gui/graphicsview/qgraphicslayout.cpp
diff options
context:
space:
mode:
Diffstat (limited to 'src/gui/graphicsview/qgraphicslayout.cpp')
-rw-r--r--src/gui/graphicsview/qgraphicslayout.cpp423
1 files changed, 423 insertions, 0 deletions
diff --git a/src/gui/graphicsview/qgraphicslayout.cpp b/src/gui/graphicsview/qgraphicslayout.cpp
new file mode 100644
index 0000000000..f78b8c81b6
--- /dev/null
+++ b/src/gui/graphicsview/qgraphicslayout.cpp
@@ -0,0 +1,423 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (qt-info@nokia.com)
+**
+** This file is part of the QtGui module 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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at qt-sales@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include "qapplication.h"
+
+#ifndef QT_NO_GRAPHICSVIEW
+#include "qgraphicslayout.h"
+#include "qgraphicslayout_p.h"
+#include "qgraphicslayoutitem.h"
+#include "qgraphicslayoutitem_p.h"
+#include "qgraphicswidget.h"
+#include "qgraphicswidget_p.h"
+#include "qgraphicsscene.h"
+
+QT_BEGIN_NAMESPACE
+
+/*!
+ \class QGraphicsLayout
+ \brief The QGraphicsLayout class provides the base class for all layouts
+ in Graphics View.
+ \since 4.4
+ \ingroup multimedia
+ \ingroup graphicsview-api
+
+ QGraphicsLayout is an abstract class that defines a virtual API for
+ arranging QGraphicsWidget children and other QGraphicsLayoutItem objects
+ for a QGraphicsWidget. QGraphicsWidget assigns responsibility to a
+ QGraphicsLayout through QGraphicsWidget::setLayout(). As the widget
+ is resized, the layout will automatically arrange the widget's children.
+ QGraphicsLayout inherits QGraphicsLayoutItem, so, it can be managed by
+ any layout, including its own subclasses.
+
+ \section1 Writing a Custom Layout
+
+ You can use QGraphicsLayout as a base to write your own custom layout
+ (e.g., a flowlayout), but it is more common to use one of its subclasses
+ instead - QGraphicsLinearLayout or QGraphicsGridLayout. When creating
+ a custom layout, the following functions must be reimplemented as a bare
+ minimum:
+
+ \table
+ \header \o Function \o Description
+ \row \o QGraphicsLayoutItem::setGeometry()
+ \o Notifies you when the geometry of the layout is set. You can
+ store the geometry in your own layout class in a reimplementation
+ of this function.
+ \row \o QGraphicsLayoutItem::sizeHint()
+ \o Returns the layout's size hints.
+ \row \o QGraphicsLayout::count()
+ \o Returns the number of items in your layout.
+ \row \o QGraphicsLayout::itemAt()
+ \o Returns a pointer to an item in your layout.
+ \row \o QGraphicsLayout::removeAt()
+ \o Removes an item from your layout without destroying it.
+ \endtable
+
+ For more details on how to implement each function, refer to the individual
+ function documentation.
+
+ Each layout defines its own API for arranging widgets and layout items.
+ For example, with a grid layout, you require a row and a
+ column index with optional row and column spans, alignment, spacing, and more.
+ A linear layout, however, requires a single row or column index to position its
+ items. For a grid layout, the order of insertion does not affect the layout in
+ any way, but for a linear layout, the order is essential. When writing your own
+ layout subclass, you are free to choose the API that best suits your layout.
+
+ \section1 Activating the Layout
+
+ When the layout's geometry changes, QGraphicsLayout immediately rearranges
+ all of its managed items by calling setGeometry() on each item. This
+ rearrangement is called \e activating the layout.
+
+ QGraphicsLayout updates its own geometry to match the contentsRect() of the
+ QGraphicsLayoutItem it is managing. Thus, it will automatically rearrange all
+ its items when the widget is resized. QGraphicsLayout caches the sizes of all
+ its managed items to avoid calling setGeometry() too often.
+
+ \note A QGraphicsLayout will have the same geometry as the contentsRect()
+ of the widget (not the layout) it is assigned to.
+
+ \section2 Activating the Layout Implicitly
+
+ The layout can be activated implicitly using one of two ways: by calling
+ activate() or by calling invalidate(). Calling activate() activates the layout
+ immediately. In contrast, calling invalidate() is delayed, as it posts a
+ \l{QEvent::LayoutRequest}{LayoutRequest} event to the managed widget. Due
+ to event compression, the activate() will only be called once after control has
+ returned to the event loop. This is referred to as \e invalidating the layout.
+ Invalidating the layout also invalidates any cached information. Also, the
+ invalidate() function is a virtual function. So, you can invalidate your own
+ cache in a subclass of QGraphicsLayout by reimplementing this function.
+
+ \section1 Event Handling
+
+ QGraphicsLayout listens to events for the widget it manages through the
+ virtual widgetEvent() event handler. When the layout is assigned to a
+ widget, all events delivered to the widget are first processed by
+ widgetEvent(). This allows the layout to be aware of any relevant state
+ changes on the widget such as visibility changes or layout direction changes.
+
+ \section1 Margin Handling
+
+ The margins of a QGraphicsLayout can be modified by reimplementing
+ setContentsMargins() and getContentsMargins().
+
+*/
+
+/*!
+ Contructs a QGraphicsLayout object.
+
+ \a parent is passed to QGraphicsLayoutItem's constructor and the
+ QGraphicsLayoutItem's isLayout argument is set to \e true.
+*/
+QGraphicsLayout::QGraphicsLayout(QGraphicsLayoutItem *parent)
+ : QGraphicsLayoutItem(*new QGraphicsLayoutPrivate)
+{
+ setParentLayoutItem(parent);
+ if (parent && !parent->isLayout()) {
+ // If a layout has a parent that is not a layout it must be a QGraphicsWidget.
+ QGraphicsItem *itemParent = parent->graphicsItem();
+ if (itemParent && itemParent->isWidget()) {
+ static_cast<QGraphicsWidget *>(itemParent)->d_func()->setLayout_helper(this);
+ } else {
+ qWarning("QGraphicsLayout::QGraphicsLayout: Attempt to create a layout with a parent that is"
+ " neither a QGraphicsWidget nor QGraphicsLayout");
+ }
+ }
+ setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Expanding, QSizePolicy::DefaultType);
+ setOwnedByLayout(true);
+}
+
+/*!
+ \internal
+*/
+QGraphicsLayout::QGraphicsLayout(QGraphicsLayoutPrivate &dd, QGraphicsLayoutItem *parent)
+ : QGraphicsLayoutItem(dd)
+{
+ setParentLayoutItem(parent);
+ if (parent && !parent->isLayout()) {
+ // If a layout has a parent that is not a layout it must be a QGraphicsWidget.
+ QGraphicsItem *itemParent = parent->graphicsItem();
+ if (itemParent && itemParent->isWidget()) {
+ static_cast<QGraphicsWidget *>(itemParent)->d_func()->setLayout_helper(this);
+ } else {
+ qWarning("QGraphicsLayout::QGraphicsLayout: Attempt to create a layout with a parent that is"
+ " neither a QGraphicsWidget nor QGraphicsLayout");
+ }
+ }
+ setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Expanding, QSizePolicy::DefaultType);
+ setOwnedByLayout(true);
+}
+
+/*!
+ Destroys the QGraphicsLayout object.
+*/
+QGraphicsLayout::~QGraphicsLayout()
+{
+}
+
+/*!
+ Sets the contents margins to \a left, \a top, \a right and \a bottom. The
+ default contents margins for toplevel layouts are style dependent
+ (by querying the pixelMetric for QStyle::PM_LayoutLeftMargin,
+ QStyle::PM_LayoutTopMargin, QStyle::PM_LayoutRightMargin and
+ QStyle::PM_LayoutBottomMargin).
+
+ For sublayouts the default margins are 0.
+
+ Changing the contents margins automatically invalidates the layout.
+
+ \sa invalidate()
+*/
+void QGraphicsLayout::setContentsMargins(qreal left, qreal top, qreal right, qreal bottom)
+{
+ Q_D(QGraphicsLayout);
+ if (d->left == left && d->top == top && d->right == right && d->bottom == bottom)
+ return;
+ d->left = left;
+ d->right = right;
+ d->top = top;
+ d->bottom = bottom;
+ invalidate();
+}
+
+/*!
+ \reimp
+*/
+void QGraphicsLayout::getContentsMargins(qreal *left, qreal *top, qreal *right, qreal *bottom) const
+{
+ Q_D(const QGraphicsLayout);
+ d->getMargin(left, d->left, QStyle::PM_LayoutLeftMargin);
+ d->getMargin(top, d->top, QStyle::PM_LayoutTopMargin);
+ d->getMargin(right, d->right, QStyle::PM_LayoutRightMargin);
+ d->getMargin(bottom, d->bottom, QStyle::PM_LayoutBottomMargin);
+}
+
+/*!
+ Activates the layout, causing all items in the layout to be immediately
+ rearranged. This function is based on calling count() and itemAt(), and
+ then calling setGeometry() on all items sequentially. When activated,
+ the layout will adjust its geometry to its parent's contentsRect().
+ The parent will then invalidate any layout of its own.
+
+ If called in sequence or recursively, e.g., by one of the arranged items
+ in response to being resized, this function will do nothing.
+
+ Note that the layout is free to use geometry caching to optimize this
+ process. To forcefully invalidate any such cache, you can call
+ invalidate() before calling activate().
+
+ \sa invalidate()
+*/
+void QGraphicsLayout::activate()
+{
+ Q_D(QGraphicsLayout);
+ if (d->activated)
+ return;
+
+ d->activateRecursive(this);
+
+ // we don't call activate on a sublayout, but somebody might.
+ // Therefore, we walk to the parentitem of the toplevel layout.
+ QGraphicsLayoutItem *parentItem = this;
+ while (parentItem && parentItem->isLayout())
+ parentItem = parentItem->parentLayoutItem();
+ if (!parentItem)
+ return;
+ Q_ASSERT(!parentItem->isLayout());
+
+ setGeometry(parentItem->contentsRect()); // relayout children
+
+ // ### bug, should be parentItem ?
+ parentLayoutItem()->updateGeometry(); // bubble up; will set activated to false
+ // ### too many resizes? maybe we should walk up the chain to the
+ // ### top-level layouted layoutItem and call activate there.
+}
+
+/*!
+ Returns true if the layout is currently being activated; otherwise,
+ returns false. If the layout is being activated, this means that it is
+ currently in the process of rearranging its items (i.e., the activate()
+ function has been called, and has not yet returned).
+
+ \sa activate(), invalidate()
+*/
+bool QGraphicsLayout::isActivated() const
+{
+ Q_D(const QGraphicsLayout);
+ return d->activated;
+}
+
+/*!
+ Clears any cached geometry and size hint information in the layout, and
+ posts a \l{QEvent::LayoutRequest}{LayoutRequest} event to the managed
+ parent QGraphicsLayoutItem.
+
+ \sa activate(), setGeometry()
+*/
+void QGraphicsLayout::invalidate()
+{
+ // only mark layouts as invalid (activated = false) if we can post a LayoutRequest event.
+ QGraphicsLayoutItem *layoutItem = this;
+ while (layoutItem && layoutItem->isLayout()) {
+ // we could call updateGeometry(), but what if that method
+ // does not call the base implementation? In addition, updateGeometry()
+ // does more than we need.
+ layoutItem->d_func()->sizeHintCacheDirty = true;
+ layoutItem = layoutItem->parentLayoutItem();
+ }
+ if (layoutItem)
+ layoutItem->d_func()->sizeHintCacheDirty = true;
+
+ bool postIt = layoutItem ? !layoutItem->isLayout() : false;
+ if (postIt) {
+ layoutItem = this;
+ while (layoutItem && layoutItem->isLayout()
+ && static_cast<QGraphicsLayout*>(layoutItem)->d_func()->activated) {
+ static_cast<QGraphicsLayout*>(layoutItem)->d_func()->activated = false;
+ layoutItem = layoutItem->parentLayoutItem();
+ }
+ if (layoutItem && !layoutItem->isLayout()) {
+ // If a layout has a parent that is not a layout it must be a QGraphicsWidget.
+ QApplication::postEvent(static_cast<QGraphicsWidget *>(layoutItem), new QEvent(QEvent::LayoutRequest));
+ }
+ }
+}
+
+/*!
+ \reimp
+*/
+void QGraphicsLayout::updateGeometry()
+{
+ QGraphicsLayoutItem::updateGeometry();
+ if (QGraphicsLayoutItem *parentItem = parentLayoutItem()) {
+ if (parentItem->isLayout()) {
+ parentItem->updateGeometry();
+ } else {
+ invalidate();
+ }
+ }
+}
+
+/*!
+ This virtual event handler receives all events for the managed
+ widget. QGraphicsLayout uses this event handler to listen for layout
+ related events such as geometry changes, layout changes or layout
+ direction changes.
+
+ \a e is a pointer to the event.
+
+ You can reimplement this event handler to track similar events for your
+ own custom layout.
+
+ \sa QGraphicsWidget::event(), QGraphicsItem::sceneEvent()
+*/
+void QGraphicsLayout::widgetEvent(QEvent *e)
+{
+ switch (e->type()) {
+ case QEvent::GraphicsSceneResize:
+ if (isActivated()) {
+ setGeometry(parentLayoutItem()->contentsRect());
+ } else {
+ activate(); // relies on that activate() will call updateGeometry()
+ }
+ break;
+ case QEvent::LayoutRequest:
+ activate();
+ break;
+ case QEvent::LayoutDirectionChange:
+ invalidate();
+ break;
+ default:
+ break;
+ }
+}
+
+/*!
+ \fn virtual int QGraphicsLayout::count() const = 0
+
+ This pure virtual function must be reimplemented in a subclass of
+ QGraphicsLayout to return the number of items in the layout.
+
+ The subclass is free to decide how to store the items.
+
+ \sa itemAt(), removeAt()
+*/
+
+/*!
+ \fn virtual QGraphicsLayoutItem *QGraphicsLayout::itemAt(int i) const = 0
+
+ This pure virtual function must be reimplemented in a subclass of
+ QGraphicsLayout to return a pointer to the item at index \a i. The
+ reimplementation can assume that \a i is valid (i.e., it respects the
+ value of count()).
+
+ The subclass is free to decide how to store the items.
+
+ \sa count(), removeAt()
+*/
+
+/*!
+ \fn virtual void QGraphicsLayout::removeAt(int index) = 0
+
+ This pure virtual function must be reimplemented in a subclass of
+ QGraphicsLayout to remove the item at \a index. The
+ reimplementation can assume that \a index is valid (i.e., it
+ respects the value of count()).
+
+ The implementation must ensure that the parentLayoutItem() of
+ the removed item does not point to this layout, since the item is
+ considered to be removed from the layout hierarchy.
+
+ If the layout is to be reused between applications, we recommend
+ that the layout deletes the item, but the graphics view framework
+ does not depend on this.
+
+ The subclass is free to decide how to store the items.
+
+ \sa itemAt(), count()
+*/
+
+QT_END_NAMESPACE
+
+#endif //QT_NO_GRAPHICSVIEW