Doc: First attempt at a simpler widgets tutorial.

Task-number: 253710
Reviewed-by: Trust Me

11 files changed, 449 insertions, 11 deletions

diff --git a/doc/src/snippets/widgets-tutorial/template.cpp b/doc/src/snippets/widgets-tutorial/template.cpp
new file mode 100644
index 0000000..5958676
--- /dev/null
+++ b/doc/src/snippets/widgets-tutorial/template.cpp
@@ -0,0 +1,14 @@
+#include <QtGui>
+
+// Include header files for application components.
+// ...
+
+int main(int argc, char *argv[])
+{
+    QApplication app(argc, argv);
+
+    // Set up and show widgets.
+    // ...
+
+    return app.exec();
+}
diff --git a/doc/src/tutorials/widgets-tutorial.qdoc b/doc/src/tutorials/widgets-tutorial.qdoc
index ead44af..1e89431 100644
--- a/doc/src/tutorials/widgets-tutorial.qdoc
+++ b/doc/src/tutorials/widgets-tutorial.qdoc
@@ -41,11 +41,14 @@
 
 /*!
     \page widgets-tutorial.html
+    \startpage {index.html}{Qt Reference Documentation}
+    \nextpage {tutorials/widgets/toplevel}{Creating a Window}
 
     \title Widgets Tutorial
     \ingroup tutorials
 
-    \brief This tutorial covers basic usage of widgets and layouts, showing how they are used to build GUI applications.
+    \brief This tutorial covers basic usage of widgets and layouts, showing how
+    they are used to build GUI applications.
 
     \section1 Introduction
 
@@ -68,7 +71,60 @@
     occupied by its parent. This means that, when a window is deleted, all
     the widgets it contains are automatically deleted.
 
-    \section1 Creating a Window
+    \section1 Writing a main Function
+
+    Many of the GUI examples in Qt follow the pattern of having a \c{main.cpp}
+    file containing code to initialize the application, and a number of other
+    source and header files containing the application logic and custom GUI
+    components.
+
+    A typical \c main() function, written in \c{main.cpp}, looks like this:
+
+    \quotefile doc/src/snippets/widgets-tutorial/template.cpp
+
+    We first construct a QApplication object which is configured using any
+    arguments passed in from the command line. After any widgets have been
+    created and shown, we call QApplication::exec() to start Qt's event loop.
+    Control passes to Qt until this function returns, at which point we return
+    the value we obtain from this function.
+
+    In each part of this tutorial, we provide an example that is written
+    entirely within a \c main() function. In more sophisticated examples, the
+    code to set up widgets and layouts is written in other parts of the
+    example. For example, the GUI for a main window may be set up in the
+    constructor of a QMainWindow subclass.
+
+    The \l{Qt Examples#Widgets}{Widgets examples} are a good place to look for
+    more complex and complete examples and applications.
+
+    \section1 Building Examples and Tutorials
+
+    If you obtained a binary package of Qt or compiled it yourself, the
+    examples described in this tutorial should already be ready to run.
+    However, if you may wish to modify them and recompile them, you need to
+    perform the following steps:
+
+    \list 1
+    \o At the command line, enter the directory containing the example you
+       wish to recompile.
+    \o Type \c qmake and press \key{Return}. If this doesn't work, make sure
+       that the executable is on your path, or enter its full location.
+    \o On Linux/Unix and Mac OS X, type \c make and press \key{Return};
+       on Windows with Visual Studio, type \c nmake and press \key{Return}.
+    \endlist
+
+    An executable file should have been created within the current directory.
+    On Windows, this file may be located within a \c debug or \c release
+    subdirectory. You can run this file to see the example code at work.
+*/
+
+/*!
+    \page widgets-tutorial-toplevel.html
+    \contentspage {Widgets Tutorial}{Contents}
+    \previouspage {Widgets Tutorial}
+    \nextpage {Widgets Tutorial - Child Widgets}
+    \example tutorials/widgets/toplevel
+    \title Widgets Tutorial - Creating a Window
 
     If a widget is created without a parent, it is treated as a window, or
     \e{top-level widget}, when it is shown. Since it has no parent object to
@@ -82,7 +138,7 @@
     <table align="left" width="100%">
     <tr class="qt-code"><td>
     \endraw
-    \snippet snippets/widgets-tutorial/toplevel/main.cpp create, resize and show
+    \snippet tutorials/widgets/toplevel/main.cpp main program
     \raw HTML
     </td><td align="right">
     \endraw
@@ -92,15 +148,28 @@
     </table>
     \endraw
 
-    We can add a child widget to this window by passing \c window as the
-    parent to its constructor. In this case, we add a button to the window
-    and place it in a specific location:
+    To create a real GUI, we need to place widgets inside the window. To do
+    this, we pass a QWidget instance to a widget's constructor, as we will
+    demonstrate in the next part of this tutorial.
+*/
+
+/*!
+    \page widgets-tutorial-childwidget.html
+    \contentspage {Widgets Tutorial}{Contents}
+    \previouspage {Widgets Tutorial - Creating a Window}
+    \nextpage {Widgets Tutorial - Using Layouts}
+    \example tutorials/widgets/childwidget
+    \title Widgets Tutorial - Child Widgets
+
+    We can add a child widget to the window created in the previous example by
+    passing \c window as the parent to its constructor. In this case, we add a
+    button to the window and place it in a specific location:
 
     \raw HTML
     <table align="left" width="100%">
     <tr class="qt-code"><td>
     \endraw
-    \snippet snippets/widgets-tutorial/childwidget/main.cpp create, position and show
+    \snippet tutorials/widgets/childwidget/main.cpp main program
     \raw HTML
     </td><td align="right">
     \endraw
@@ -112,9 +181,16 @@
 
     The button is now a child of the window and will be deleted when the
     window is destroyed. Note that hiding or closing the window does not
-    automatically destroy it.
+    automatically destroy it. It will be destroyed when the example exits.
+*/
 
-    \section1 Using Layouts
+/*!
+    \page widgets-tutorial-windowlayout.html
+    \contentspage {Widgets Tutorial}{Contents}
+    \previouspage {Widgets Tutorial - Child Widgets}
+    \nextpage {Widgets Tutorial - Nested Layouts}
+    \example tutorials/widgets/windowlayout
+    \title Widgets Tutorial - Using Layouts
 
     Usually, child widgets are arranged inside a window using layout objects
     rather than by specifying positions and sizes explicitly. Here, we
@@ -125,7 +201,7 @@
     <table align="left" width="100%">
     <tr class="qt-code"><td>
     \endraw
-    \snippet snippets/widgets-tutorial/windowlayout/main.cpp create, lay out widgets and show
+    \snippet tutorials/widgets/windowlayout/main.cpp main program
     \raw HTML
     </td><td align="right">
     \endraw
@@ -149,17 +225,31 @@
     manage the label and line edit and set the layout on the window, both the
     widgets and the layout itself are ''reparented'' to become children of
     the window.
+*/
+
+/*!
+    \page widgets-tutorial-nestedlayouts.html
+    \contentspage {Widgets Tutorial}{Contents}
+    \previouspage {Widgets Tutorial - Using Layouts}
+    \example tutorials/widgets/nestedlayouts
+    \title Widgets Tutorial - Nested Layouts
 
     Just as widgets can contain other widgets, layouts can be used to provide
     different levels of grouping for widgets. Here, we want to display a
     label alongside a line edit at the top of a window, above a table view
     showing the results of a query.
 
+    We achieve this by creating two layouts: \c{queryLayout} is a QHBoxLayout
+    that contains QLabel and QLineEdit widgets placed side-by-side;
+    \c{mainLayout} is a QVBoxLayout that contains \c{queryLayout} and a
+    QTableView arranged vertically.
+
     \raw HTML
     <table align="left" width="100%">
     <tr class="qt-code"><td>
     \endraw
-    \snippet snippets/widgets-tutorial/nestedlayouts/main.cpp create, lay out widgets and show
+    \snippet tutorials/widgets/nestedlayouts/main.cpp first part
+    \snippet tutorials/widgets/nestedlayouts/main.cpp last part
     \raw HTML
     </td><td align="right">
     \endraw
@@ -169,6 +259,26 @@
     </table>
     \endraw
 
+    Note that we call the \c{mainLayout}'s \l{QBoxLayout::}{addLayout()}
+    function to insert the \c{queryLayout} above the \c{resultView} table.
+
+    We have omitted the code that sets up the model containing the data shown
+    by the QTableView widget, \c resultView. For completeness, we show this below.
+
     As well as QHBoxLayout and QVBoxLayout, Qt also provides QGridLayout
     and QFormLayout classes to help with more complex user interfaces.
+    These can be seen if you run \l{Qt Designer}.
+
+    \section1 Setting up the Model
+
+    In the code above, we did not show where the table's data came from
+    because we wanted to concentrate on the use of layouts. Here, we see
+    that the model holds a number of items corresponding to rows, each of
+    which is set up to contain data for two columns.
+
+    \snippet tutorials/widgets/nestedlayouts/main.cpp set up the model
+
+    The use of models and views is covered in the
+    \l{Qt Examples#Item Views}{item view examples} and in the
+    \l{Model/View Programming} overview.
 */
diff --git a/examples/tutorials/widgets/childwidget/childwidget.pro b/examples/tutorials/widgets/childwidget/childwidget.pro
new file mode 100644
index 0000000..37ae98e
--- /dev/null
+++ b/examples/tutorials/widgets/childwidget/childwidget.pro
@@ -0,0 +1,7 @@
+SOURCES = main.cpp
+
+# install
+target.path = $$[QT_INSTALL_EXAMPLES]/tutorials/widgets/childwidget
+sources.files = $$SOURCES $$HEADERS $$RESOURCES $$FORMS childwidget.pro
+sources.path = $$[QT_INSTALL_EXAMPLES]/tutorials/widgets/childwidget
+INSTALLS += target sources
diff --git a/examples/tutorials/widgets/childwidget/main.cpp b/examples/tutorials/widgets/childwidget/main.cpp
new file mode 100644
index 0000000..99235bd
--- /dev/null
+++ b/examples/tutorials/widgets/childwidget/main.cpp
@@ -0,0 +1,60 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (qt-info@nokia.com)
+**
+** This file is part of the documentation 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$
+**
+****************************************************************************/
+
+//! [main program]
+#include <QtGui>
+
+int main(int argc, char *argv[])
+{
+    QApplication app(argc, argv);
+    QWidget *window = new QWidget();
+    window->resize(320, 240);
+    window->setWindowTitle(tr("Child widget"));
+    window->show();
+
+//! [create, position and show]
+    QPushButton *button = new QPushButton(tr("Press me"), window);
+    button->move(100, 100);
+    button->show();
+//! [create, position and show]
+    return app.exec();
+}
+//! [main program]
diff --git a/examples/tutorials/widgets/nestedlayouts/main.cpp b/examples/tutorials/widgets/nestedlayouts/main.cpp
new file mode 100644
index 0000000..29996c6
--- /dev/null
+++ b/examples/tutorials/widgets/nestedlayouts/main.cpp
@@ -0,0 +1,100 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (qt-info@nokia.com)
+**
+** This file is part of the documentation 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$
+**
+****************************************************************************/
+
+//! [main program]
+//! [first part]
+#include <QtGui>
+
+int main(int argc, char *argv[])
+{
+    QApplication app(argc, argv);
+    QWidget *window = new QWidget();
+
+    QLabel *queryLabel = new QLabel(tr("Query:"));
+    QLineEdit *queryEdit = new QLineEdit();
+    QTableView *resultView = new QTableView();
+
+    QHBoxLayout *queryLayout = new QHBoxLayout();
+    queryLayout->addWidget(queryLabel);
+    queryLayout->addWidget(queryEdit);
+
+    QVBoxLayout *mainLayout = new QVBoxLayout();
+    mainLayout->addLayout(queryLayout);
+    mainLayout->addWidget(resultView);
+    window->setLayout(mainLayout);
+
+    // Set up the model and configure the view...
+//! [first part]
+
+//! [set up the model]
+    QStandardItemModel model;
+    model.setHorizontalHeaderLabels(QStringList() << tr("Name") << tr("Office"));
+
+    QList<QStringList> rows = QList<QStringList>()
+        << (QStringList() << "Verne Nilsen" << "123")
+        << (QStringList() << "Carlos Tang" << "77")
+        << (QStringList() << "Bronwyn Hawcroft" << "119")
+        << (QStringList() << "Alessandro Hanssen" << "32")
+        << (QStringList() << "Andrew John Bakken" << "54")
+        << (QStringList() << "Vanessa Weatherley" << "85")
+        << (QStringList() << "Rebecca Dickens" << "17")
+        << (QStringList() << "David Bradley" << "42")
+        << (QStringList() << "Knut Walters" << "25")
+        << (QStringList() << "Andrea Jones" << "34");
+
+    foreach (QStringList row, rows) {
+        QList<QStandardItem *> items;
+        foreach (QString text, row)
+            items.append(new QStandardItem(text));
+        model.appendRow(items);
+    }
+
+    resultView->setModel(&model);
+    resultView->verticalHeader()->hide();
+    resultView->horizontalHeader()->setStretchLastSection(true);
+//! [set up the model]
+//! [last part]
+    window->setWindowTitle(tr("Nested layouts"));
+    window->show();
+    return app.exec();
+}
+//! [last part]
+//! [main program]
diff --git a/examples/tutorials/widgets/nestedlayouts/nestedlayouts.pro b/examples/tutorials/widgets/nestedlayouts/nestedlayouts.pro
new file mode 100644
index 0000000..a7f141c
--- /dev/null
+++ b/examples/tutorials/widgets/nestedlayouts/nestedlayouts.pro
@@ -0,0 +1,7 @@
+SOURCES = main.cpp
+
+# install
+target.path = $$[QT_INSTALL_EXAMPLES]/tutorials/widgets/nestedlayouts
+sources.files = $$SOURCES $$HEADERS $$RESOURCES $$FORMS nestedlayouts.pro
+sources.path = $$[QT_INSTALL_EXAMPLES]/tutorials/widgets/nestedlayouts
+INSTALLS += target sources
diff --git a/examples/tutorials/widgets/toplevel/main.cpp b/examples/tutorials/widgets/toplevel/main.cpp
new file mode 100644
index 0000000..c966037
--- /dev/null
+++ b/examples/tutorials/widgets/toplevel/main.cpp
@@ -0,0 +1,56 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (qt-info@nokia.com)
+**
+** This file is part of the documentation 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$
+**
+****************************************************************************/
+
+//! [main program]
+#include <QtGui>
+
+int main(int argc, char *argv[])
+{
+    QApplication app(argc, argv);
+//! [create, resize and show]
+    QWidget *window = new QWidget();
+    window->resize(320, 240);
+    window->show();
+//! [create, resize and show]
+    window->setWindowTitle(tr("Top-level widget"));
+    return app.exec();
+}
+//! [main program]
diff --git a/examples/tutorials/widgets/toplevel/toplevel.pro b/examples/tutorials/widgets/toplevel/toplevel.pro
new file mode 100644
index 0000000..58d59c5
--- /dev/null
+++ b/examples/tutorials/widgets/toplevel/toplevel.pro
@@ -0,0 +1,7 @@
+SOURCES = main.cpp
+
+# install
+target.path = $$[QT_INSTALL_EXAMPLES]/tutorials/widgets/toplevel
+sources.files = $$SOURCES $$HEADERS $$RESOURCES $$FORMS toplevel.pro
+sources.path = $$[QT_INSTALL_EXAMPLES]/tutorials/widgets/toplevel
+INSTALLS += target sources
diff --git a/examples/tutorials/widgets/widgets.pro b/examples/tutorials/widgets/widgets.pro
new file mode 100644
index 0000000..7a870e7
--- /dev/null
+++ b/examples/tutorials/widgets/widgets.pro
@@ -0,0 +1,8 @@
+TEMPLATE  = subdirs
+SUBDIRS   = toplevel childwidget windowlayout nestedlayouts
+
+# install
+target.path = $$[QT_INSTALL_EXAMPLES]/tutorials/widgets
+sources.files = $$SOURCES $$HEADERS $$RESOURCES $$FORMS widgets.pro README
+sources.path = $$[QT_INSTALL_EXAMPLES]/tutorials/widgets
+INSTALLS += target sources
diff --git a/examples/tutorials/widgets/windowlayout/main.cpp b/examples/tutorials/widgets/windowlayout/main.cpp
new file mode 100644
index 0000000..d7c75a3
--- /dev/null
+++ b/examples/tutorials/widgets/windowlayout/main.cpp
@@ -0,0 +1,62 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (qt-info@nokia.com)
+**
+** This file is part of the documentation 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$
+**
+****************************************************************************/
+
+//! [main program]
+#include <QtGui>
+
+int main(int argc, char *argv[])
+{
+    QApplication app(argc, argv);
+    QWidget *window = new QWidget();
+//! [create, lay out widgets and show]
+    QLabel *label = new QLabel(tr("Name:"));
+    QLineEdit *lineEdit = new QLineEdit();
+
+    QHBoxLayout *layout = new QHBoxLayout();
+    layout->addWidget(label);
+    layout->addWidget(lineEdit);
+    window->setLayout(layout);
+//! [create, lay out widgets and show]
+    window->setWindowTitle(tr("Window layout"));
+    window->show();
+    return app.exec();
+}
+//! [main program]
diff --git a/examples/tutorials/widgets/windowlayout/windowlayout.pro b/examples/tutorials/widgets/windowlayout/windowlayout.pro
new file mode 100644
index 0000000..408f6ef
--- /dev/null
+++ b/examples/tutorials/widgets/windowlayout/windowlayout.pro
@@ -0,0 +1,7 @@
+SOURCES = main.cpp
+
+# install
+target.path = $$[QT_INSTALL_EXAMPLES]/tutorials/widgets/windowlayout
+sources.files = $$SOURCES $$HEADERS $$RESOURCES $$FORMS windowlayout.pro
+sources.path = $$[QT_INSTALL_EXAMPLES]/tutorials/widgets/windowlayout
+INSTALLS += target sources