src/widgets/widgets/qstackedwidget.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the QtGui module of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:LGPL$
   9 ** GNU Lesser General Public License Usage
  10 ** This file may be used under the terms of the GNU Lesser General Public
  11 ** License version 2.1 as published by the Free Software Foundation and
  12 ** appearing in the file LICENSE.LGPL included in the packaging of this
  13 ** file. Please review the following information to ensure the GNU Lesser
  14 ** General Public License version 2.1 requirements will be met:
  15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  16 **
  17 ** In addition, as a special exception, Nokia gives you certain additional
  18 ** rights. These rights are described in the Nokia Qt LGPL Exception
  19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  20 **
  21 ** GNU General Public License Usage
  22 ** Alternatively, this file may be used under the terms of the GNU General
  23 ** Public License version 3.0 as published by the Free Software Foundation
  24 ** and appearing in the file LICENSE.GPL included in the packaging of this
  25 ** file. Please review the following information to ensure the GNU General
  26 ** Public License version 3.0 requirements will be met:
  27 ** http://www.gnu.org/copyleft/gpl.html.
  28 **
  29 ** Other Usage
  30 ** Alternatively, this file may be used in accordance with the terms and
  31 ** conditions contained in a signed written agreement between you and Nokia.
  32 **
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #include "qstackedwidget.h"
  43
  44 #ifndef QT_NO_STACKEDWIDGET
  45
  46 #include <qstackedlayout.h>
  47 #include <qevent.h>
  48 #include <private/qframe_p.h>
  49
  50 QT_BEGIN_NAMESPACE
  51
  52 /**
  53    QStackedLayout does not support height for width (simply because it does not reimplement
  54    heightForWidth() and hasHeightForWidth()). That is not possible to fix without breaking
  55    binary compatibility. (QLayout is subject to multiple inheritance).
  56    However, we can fix QStackedWidget by simply using a modified version of QStackedLayout
  57    that reimplements the hfw-related functions:
  58  */
  59 class QStackedLayoutHFW : public QStackedLayout
  60 {
  61 public:
  62     QStackedLayoutHFW(QWidget *parent = 0) : QStackedLayout(parent) {}
  63     bool hasHeightForWidth() const;
  64     int heightForWidth(int width) const;
  65 };
  66
  67 bool QStackedLayoutHFW::hasHeightForWidth() const
  68 {
  69     const int n = count();
  70
  71     for (int i = 0; i < n; ++i) {
  72         if (QLayoutItem *item = itemAt(i)) {
  73             if (item->hasHeightForWidth())
  74                 return true;
  75         }
  76     }
  77     return false;
  78 }
  79
  80 int QStackedLayoutHFW::heightForWidth(int width) const
  81 {
  82     const int n = count();
  83
  84     int hfw = 0;
  85     for (int i = 0; i < n; ++i) {
  86         if (QLayoutItem *item = itemAt(i)) {
  87             hfw = qMax(hfw, item->heightForWidth(width));
  88         }
  89     }
  90     return hfw;
  91 }
  92
  93
  94 class QStackedWidgetPrivate : public QFramePrivate
  95 {
  96     Q_DECLARE_PUBLIC(QStackedWidget)
  97 public:
  98     QStackedWidgetPrivate():layout(0){}
  99     QStackedLayoutHFW *layout;
 100     bool blockChildAdd;
 101 };
 102
 103 /*!
 104     \class QStackedWidget
 105     \brief The QStackedWidget class provides a stack of widgets where
 106     only one widget is visible at a time.
 107
 108     \ingroup organizers
 109     \ingroup geomanagement
 110     \inmodule QtWidgets
 111
 112     QStackedWidget can be used to create a user interface similar to
 113     the one provided by QTabWidget. It is a convenience layout widget
 114     built on top of the QStackedLayout class.
 115
 116     Like QStackedLayout, QStackedWidget can be constructed and
 117     populated with a number of child widgets ("pages"):
 118
 119     \snippet doc/src/snippets/qstackedwidget/main.cpp 0
 120     \snippet doc/src/snippets/qstackedwidget/main.cpp 2
 121     \snippet doc/src/snippets/qstackedwidget/main.cpp 3
 122
 123     QStackedWidget provides no intrinsic means for the user to switch
 124     page. This is typically done through a QComboBox or a QListWidget
 125     that stores the titles of the QStackedWidget's pages. For
 126     example:
 127
 128     \snippet doc/src/snippets/qstackedwidget/main.cpp 1
 129
 130     When populating a stacked widget, the widgets are added to an
 131     internal list. The indexOf() function returns the index of a
 132     widget in that list. The widgets can either be added to the end of
 133     the list using the addWidget() function, or inserted at a given
 134     index using the insertWidget() function. The removeWidget()
 135     function removes a widget from the stacked widget. The number of
 136     widgets contained in the stacked widget, can
 137     be obtained using the count() function.
 138
 139     The widget() function returns the widget at a given index
 140     position. The index of the widget that is shown on screen is given
 141     by currentIndex() and can be changed using setCurrentIndex(). In a
 142     similar manner, the currently shown widget can be retrieved using
 143     the currentWidget() function, and altered using the
 144     setCurrentWidget() function.
 145
 146     Whenever the current widget in the stacked widget changes or a
 147     widget is removed from the stacked widget, the currentChanged()
 148     and widgetRemoved() signals are emitted respectively.
 149
 150     \sa QStackedLayout, QTabWidget, {Config Dialog Example}
 151 */
 152
 153 /*!
 154     \fn void QStackedWidget::currentChanged(int index)
 155
 156     This signal is emitted whenever the current widget changes.
 157
 158     The parameter holds the \a index of the new current widget, or -1
 159     if there isn't a new one (for example, if there are no widgets in
 160     the QStackedWidget).
 161
 162     \sa currentWidget(), setCurrentWidget()
 163 */
 164
 165 /*!
 166     \fn void QStackedWidget::widgetRemoved(int index)
 167
 168     This signal is emitted whenever a widget is removed. The widget's
 169     \a index is passed as parameter.
 170
 171     \sa removeWidget()
 172 */
 173
 174 /*!
 175     Constructs a QStackedWidget with the given \a parent.
 176
 177     \sa addWidget(), insertWidget()
 178 */
 179 QStackedWidget::QStackedWidget(QWidget *parent)
 180     : QFrame(*new QStackedWidgetPrivate, parent)
 181 {
 182     Q_D(QStackedWidget);
 183     d->layout = new QStackedLayoutHFW(this);
 184     connect(d->layout, SIGNAL(widgetRemoved(int)), this, SIGNAL(widgetRemoved(int)));
 185     connect(d->layout, SIGNAL(currentChanged(int)), this, SIGNAL(currentChanged(int)));
 186 }
 187
 188 /*!
 189     Destroys this stacked widget, and frees any allocated resources.
 190 */
 191 QStackedWidget::~QStackedWidget()
 192 {
 193 }
 194
 195 /*!
 196     Appends the given \a widget to the QStackedWidget and returns the
 197     index position. Ownership of \a widget is passed on to the
 198     QStackedWidget.
 199
 200     If the QStackedWidget is empty before this function is called,
 201     \a widget becomes the current widget.
 202
 203     \sa insertWidget(), removeWidget(), setCurrentWidget()
 204 */
 205 int QStackedWidget::addWidget(QWidget *widget)
 206 {
 207     return d_func()->layout->addWidget(widget);
 208 }
 209
 210 /*!
 211     Inserts the given \a widget at the given \a index in the
 212     QStackedWidget. Ownership of \a widget is passed on to the
 213     QStackedWidget. If \a index is out of range, the \a widget is
 214     appended (in which case it is the actual index of the \a widget
 215     that is returned).
 216
 217     If the QStackedWidget was empty before this function is called,
 218     the given \a widget becomes the current widget.
 219
 220     Inserting a new widget at an index less than or equal to the current index
 221     will increment the current index, but keep the current widget.
 222
 223     \sa addWidget(), removeWidget(), setCurrentWidget()
 224 */
 225 int QStackedWidget::insertWidget(int index, QWidget *widget)
 226 {
 227     return d_func()->layout->insertWidget(index, widget);
 228 }
 229
 230 /*!
 231     Removes \a widget from the QStackedWidget. i.e., \a widget is \e
 232     not deleted but simply removed from the stacked layout, causing it
 233     to be hidden.
 234
 235     \b{Note:} Ownership of \a widget reverts to the application.
 236
 237     \sa addWidget(), insertWidget(), currentWidget()
 238 */
 239 void QStackedWidget::removeWidget(QWidget *widget)
 240 {
 241     d_func()->layout->removeWidget(widget);
 242 }
 243
 244 /*!
 245     \property QStackedWidget::currentIndex
 246     \brief the index position of the widget that is visible
 247
 248     The current index is -1 if there is no current widget.
 249
 250     By default, this property contains a value of -1 because the stack
 251     is initially empty.
 252
 253     \sa currentWidget(), indexOf()
 254 */
 255
 256 void QStackedWidget::setCurrentIndex(int index)
 257 {
 258     d_func()->layout->setCurrentIndex(index);
 259 }
 260
 261 int QStackedWidget::currentIndex() const
 262 {
 263     return d_func()->layout->currentIndex();
 264 }
 265
 266 /*!
 267     Returns the current widget, or 0 if there are no child widgets.
 268
 269     \sa currentIndex(), setCurrentWidget()
 270 */
 271 QWidget *QStackedWidget::currentWidget() const
 272 {
 273     return d_func()->layout->currentWidget();
 274 }
 275
 276
 277 /*!
 278     \fn void QStackedWidget::setCurrentWidget(QWidget *widget)
 279
 280     Sets the current widget to be the specified \a widget. The new
 281     current widget must already be contained in this stacked widget.
 282
 283     \sa currentWidget(), setCurrentIndex()
 284  */
 285 void QStackedWidget::setCurrentWidget(QWidget *widget)
 286 {
 287     Q_D(QStackedWidget);
 288     if (d->layout->indexOf(widget) == -1) {
 289         qWarning("QStackedWidget::setCurrentWidget: widget %p not contained in stack", widget);
 290         return;
 291     }
 292     d->layout->setCurrentWidget(widget);
 293 }
 294
 295 /*!
 296     Returns the index of the given \a widget, or -1 if the given \a
 297     widget is not a child of the QStackedWidget.
 298
 299     \sa currentIndex(), widget()
 300 */
 301 int QStackedWidget::indexOf(QWidget *widget) const
 302 {
 303     return d_func()->layout->indexOf(widget);
 304 }
 305
 306 /*!
 307     Returns the widget at the given \a index, or 0 if there is no such
 308     widget.
 309
 310     \sa currentWidget(), indexOf()
 311 */
 312 QWidget *QStackedWidget::widget(int index) const
 313 {
 314     return d_func()->layout->widget(index);
 315 }
 316
 317 /*!
 318     \property QStackedWidget::count
 319     \brief the number of widgets contained by this stacked widget
 320
 321     By default, this property contains a value of 0.
 322
 323     \sa currentIndex(), widget()
 324 */
 325 int QStackedWidget::count() const
 326 {
 327     return d_func()->layout->count();
 328 }
 329
 330 /*! \reimp */
 331 bool QStackedWidget::event(QEvent *e)
 332 {
 333     return QFrame::event(e);
 334 }
 335
 336 QT_END_NAMESPACE
 337
 338 #endif // QT_NO_STACKEDWIDGET