--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/tutorials/widgets-tutorial.qdoc	Mon Jan 11 14:00:40 2010 +0000
@@ -0,0 +1,283 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (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 Technology Preview License Agreement accompanying
+** this package.
+**
+** 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.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page widgets-tutorial.html
+    \title Widgets Tutorial
+    \brief This tutorial covers basic usage of widgets and layouts, showing how
+    they are used to build GUI applications.
+
+    \startpage {index.html}{Qt Reference Documentation}
+    \contentspage Tutorials
+    \nextpage {tutorials/widgets/toplevel}{Creating a Window}
+
+
+    \section1 Introduction
+
+    Widgets are the basic building blocks of graphical user interface (GUI)
+    applications made with Qt. Each GUI component, such as a button, label or
+    text editor, is a widget and can be placed within an existing user
+    interface or displayed as an independent window. Each type of component
+    is provided by a particular subclass of QWidget, which is itself a
+    subclass of QObject.
+
+    QWidget is not an abstract class; it can be used as a container for other
+    widgets, and can be subclassed with minimal effort to create custom
+    widgets. It is most often used to create windows in which other widgets
+    are placed.
+
+    As with \l{QObject}s, widgets can be created with parent objects to
+    indicate ownership, ensuring that objects are deleted when they are no
+    longer used. With widgets, these parent-child relationships have an
+    additional meaning: each child is displayed within the screen area
+    occupied by its parent. This means that, when a window is deleted, all
+    the widgets it contains are automatically deleted.
+
+    \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:
+
+    \snippet doc/src/snippets/widgets-tutorial/template.cpp main.cpp body
+
+    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{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
+    ensure that it is deleted when no longer needed, it is up to the
+    developer to keep track of the top-level widgets in an application.
+
+    In the following example, we use QWidget to create and show a window with
+    a default size:
+
+    \raw HTML
+    <table align="left" width="100%">
+    <tr class="qt-code"><td>
+    \endraw
+    \snippet tutorials/widgets/toplevel/main.cpp main program
+    \raw HTML
+    </td><td align="right">
+    \endraw
+    \inlineimage widgets-tutorial-toplevel.png
+    \raw HTML
+    </td></tr>
+    </table>
+    \endraw
+
+    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 tutorials/widgets/childwidget/main.cpp main program
+    \raw HTML
+    </td><td align="right">
+    \endraw
+    \inlineimage widgets-tutorial-childwidget.png
+    \raw HTML
+    </td></tr>
+    </table>
+    \endraw
+
+    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. It will be destroyed when the example exits.
+*/
+
+/*!
+    \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
+    construct a label and line edit widget that we would like to arrange
+    side-by-side.
+
+    \raw HTML
+    <table align="left" width="100%">
+    <tr class="qt-code"><td>
+    \endraw
+    \snippet tutorials/widgets/windowlayout/main.cpp main program
+    \raw HTML
+    </td><td align="right">
+    \endraw
+    \inlineimage widgets-tutorial-windowlayout.png
+    \raw HTML
+    </td></tr>
+    </table>
+    \endraw
+
+    The \c layout object we construct manages the positions and sizes of
+    widgets supplied to it with the \l{QHBoxLayout::}{addWidget()} function.
+    The layout itself is supplied to the window itself in the call to
+    \l{QWidget::}{setLayout()}. Layouts are only visible through the effects
+    they have on the widgets (and other layouts) they are responsible for
+    managing.
+
+    In the example above, the ownership of each widget is not immediately
+    clear. Since we construct the widgets and the layout without parent
+    objects, we would expect to see an empty window and two separate windows
+    containing a label and a line edit. However, when we tell the layout to
+    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 tutorials/widgets/nestedlayouts/main.cpp first part
+    \snippet tutorials/widgets/nestedlayouts/main.cpp last part
+    \raw HTML
+    </td><td align="right">
+    \endraw
+    \inlineimage widgets-tutorial-nestedlayouts.png
+    \raw HTML
+    </td></tr>
+    </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{Item Views Examples} and in the \l{Model/View Programming} overview.
+*/