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 "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 class QStackedWidgetPrivate : public QFramePrivate

    53 {

    54     Q_DECLARE_PUBLIC(QStackedWidget)

    55 public:

    56     QStackedWidgetPrivate():layout(0){}

    57     QStackedLayout *layout;

    58     bool blockChildAdd;

    59 };

    60 

    61 /*!

    62     \class QStackedWidget

    63     \brief The QStackedWidget class provides a stack of widgets where

    64     only one widget is visible at a time.

    65 

    66     \ingroup organizers

    67     \ingroup geomanagement

    68 

    69 

    70     QStackedWidget can be used to create a user interface similar to

    71     the one provided by QTabWidget. It is a convenience layout widget

    72     built on top of the QStackedLayout class.

    73 

    74     Like QStackedLayout, QStackedWidget can be constructed and

    75     populated with a number of child widgets ("pages"):

    76 

    77     \snippet doc/src/snippets/qstackedwidget/main.cpp 0

    78     \snippet doc/src/snippets/qstackedwidget/main.cpp 2

    79     \snippet doc/src/snippets/qstackedwidget/main.cpp 3

    80 

    81     QStackedWidget provides no intrinsic means for the user to switch

    82     page. This is typically done through a QComboBox or a QListWidget

    83     that stores the titles of the QStackedWidget's pages. For

    84     example:

    85 

    86     \snippet doc/src/snippets/qstackedwidget/main.cpp 1

    87 

    88     When populating a stacked widget, the widgets are added to an

    89     internal list. The indexOf() function returns the index of a

    90     widget in that list. The widgets can either be added to the end of

    91     the list using the addWidget() function, or inserted at a given

    92     index using the insertWidget() function. The removeWidget()

    93     function removes a widget from the stacked widget. The number of

    94     widgets contained in the stacked widget, can

    95     be obtained using the count() function.

    96 

    97     The widget() function returns the widget at a given index

    98     position. The index of the widget that is shown on screen is given

    99     by currentIndex() and can be changed using setCurrentIndex(). In a

   100     similar manner, the currently shown widget can be retrieved using

   101     the currentWidget() function, and altered using the

   102     setCurrentWidget() function.

   103 

   104     Whenever the current widget in the stacked widget changes or a

   105     widget is removed from the stacked widget, the currentChanged()

   106     and widgetRemoved() signals are emitted respectively.

   107 

   108     \sa QStackedLayout, QTabWidget, {Config Dialog Example}

   109 */

   110 

   111 /*!

   112     \fn void QStackedWidget::currentChanged(int index)

   113 

   114     This signal is emitted whenever the current widget changes.

   115 

   116     The parameter holds the \a index of the new current widget, or -1

   117     if there isn't a new one (for example, if there are no widgets in

   118     the QStackedWidget).

   119 

   120     \sa currentWidget(), setCurrentWidget()

   121 */

   122 

   123 /*!

   124     \fn void QStackedWidget::widgetRemoved(int index)

   125 

   126     This signal is emitted whenever a widget is removed. The widget's

   127     \a index is passed as parameter.

   128 

   129     \sa removeWidget()

   130 */

   131 

   132 /*!

   133     Constructs a QStackedWidget with the given \a parent.

   134 

   135     \sa addWidget(), insertWidget()

   136 */

   137 QStackedWidget::QStackedWidget(QWidget *parent)

   138     : QFrame(*new QStackedWidgetPrivate, parent)

   139 {

   140     Q_D(QStackedWidget);

   141     d->layout = new QStackedLayout(this);

   142     connect(d->layout, SIGNAL(widgetRemoved(int)), this, SIGNAL(widgetRemoved(int)));

   143     connect(d->layout, SIGNAL(currentChanged(int)), this, SIGNAL(currentChanged(int)));

   144 }

   145 

   146 /*!

   147     Destroys this stacked widget, and frees any allocated resources.

   148 */

   149 QStackedWidget::~QStackedWidget()

   150 {

   151 }

   152 

   153 /*!

   154     Appends the given \a widget to the QStackedWidget and returns the

   155     index position. Ownership of \a widget is passed on to the

   156     QStackedWidget.

   157 

   158     If the QStackedWidget is empty before this function is called,

   159     \a widget becomes the current widget.

   160 

   161     \sa insertWidget(), removeWidget(), setCurrentWidget()

   162 */

   163 int QStackedWidget::addWidget(QWidget *widget)

   164 {

   165     return d_func()->layout->addWidget(widget);

   166 }

   167 

   168 /*!

   169     Inserts the given \a widget at the given \a index in the

   170     QStackedWidget. Ownership of \a widget is passed on to the

   171     QStackedWidget. If \a index is out of range, the \a widget is

   172     appended (in which case it is the actual index of the \a widget

   173     that is returned).

   174 

   175     If the QStackedWidget was empty before this function is called,

   176     the given \a widget becomes the current widget.

   177 

   178     Inserting a new widget at an index less than or equal to the current index

   179     will increment the current index, but keep the current widget.

   180 

   181     \sa addWidget(), removeWidget(), setCurrentWidget()

   182 */

   183 int QStackedWidget::insertWidget(int index, QWidget *widget)

   184 {

   185     return d_func()->layout->insertWidget(index, widget);

   186 }

   187 

   188 /*!

   189     Removes the given \a widget from the QStackedWidget. The widget

   190     is \e not deleted.

   191 

   192     \sa addWidget(), insertWidget(), currentWidget()

   193 */

   194 void QStackedWidget::removeWidget(QWidget *widget)

   195 {

   196     d_func()->layout->removeWidget(widget);

   197 }

   198 

   199 /*!

   200     \property QStackedWidget::currentIndex

   201     \brief the index position of the widget that is visible

   202 

   203     The current index is -1 if there is no current widget.

   204 

   205     By default, this property contains a value of -1 because the stack

   206     is initially empty.

   207 

   208     \sa currentWidget(), indexOf()

   209 */

   210 

   211 void QStackedWidget::setCurrentIndex(int index)

   212 {

   213     d_func()->layout->setCurrentIndex(index);

   214 }

   215 

   216 int QStackedWidget::currentIndex() const

   217 {

   218     return d_func()->layout->currentIndex();

   219 }

   220 

   221 /*!

   222     Returns the current widget, or 0 if there are no child widgets.

   223 

   224     \sa currentIndex(), setCurrentWidget()

   225 */

   226 QWidget *QStackedWidget::currentWidget() const

   227 {

   228     return d_func()->layout->currentWidget();

   229 }

   230 

   231 

   232 /*!

   233     \fn void QStackedWidget::setCurrentWidget(QWidget *widget)

   234 

   235     Sets the current widget to be the specified \a widget. The new

   236     current widget must already be contained in this stacked widget.

   237 

   238     \sa currentWidget(), setCurrentIndex()

   239  */

   240 void QStackedWidget::setCurrentWidget(QWidget *widget)

   241 {

   242     Q_D(QStackedWidget);

   243     if (d->layout->indexOf(widget) == -1) {

   244         qWarning("QStackedWidget::setCurrentWidget: widget %p not contained in stack", widget);

   245         return;

   246     }

   247     d->layout->setCurrentWidget(widget);

   248 }

   249 

   250 /*!

   251     Returns the index of the given \a widget, or -1 if the given \a

   252     widget is not a child of the QStackedWidget.

   253 

   254     \sa currentIndex(), widget()

   255 */

   256 int QStackedWidget::indexOf(QWidget *widget) const

   257 {

   258     return d_func()->layout->indexOf(widget);

   259 }

   260 

   261 /*!

   262     Returns the widget at the given \a index, or 0 if there is no such

   263     widget.

   264 

   265     \sa currentWidget(), indexOf()

   266 */

   267 QWidget *QStackedWidget::widget(int index) const

   268 {

   269     return d_func()->layout->widget(index);

   270 }

   271 

   272 /*!

   273     \property QStackedWidget::count

   274     \brief the number of widgets contained by this stacked widget

   275 

   276     By default, this property contains a value of 0.

   277 

   278     \sa currentIndex(), widget()

   279 */

   280 int QStackedWidget::count() const

   281 {

   282     return d_func()->layout->count();

   283 }

   284 

   285 /*! \reimp */

   286 bool QStackedWidget::event(QEvent *e)

   287 {

   288     return QFrame::event(e);

   289 }

   290 

   291 QT_END_NAMESPACE

   292 

   293 #endif // QT_NO_STACKEDWIDGET