Doc: First attempt at a simpler widgets tutorial.

Task-number: 253710
Reviewed-by: Trust Me

2 files changed, 135 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.
 */