Long live Qt!

1 files changed, 193 insertions, 0 deletions

diff --git a/doc/src/tutorials/widgets-tutorial.qdoc b/doc/src/tutorials/widgets-tutorial.qdoc
new file mode 100644
index 0000000..ce977f3
--- /dev/null
+++ b/doc/src/tutorials/widgets-tutorial.qdoc
@@ -0,0 +1,193 @@
+/****************************************************************************
+**
+** 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$
+**
+****************************************************************************/
+
+/*!
+    \page widgets-tutorial.html
+
+    \title Widgets Tutorial
+    \ingroup tutorials
+
+    \brief This tutorial covers basic usage of widgets and layouts, showing how they are used to build GUI applications.
+
+    \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 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><td>
+    \endraw
+    \snippet snippets/widgets-tutorial/toplevel/main.cpp create, resize and show
+    \raw HTML
+    </td><td align="right">
+    \endraw
+    \inlineimage widgets-tutorial-toplevel.png
+    \raw HTML
+    </td></tr>
+    </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:
+
+    \raw HTML
+    <table align="left" width="100%">
+    <tr><td>
+    \endraw
+    \snippet snippets/widgets-tutorial/childwidget/main.cpp create, position and show
+    \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.
+
+    \section1 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><td>
+    \endraw
+    \snippet snippets/widgets-tutorial/windowlayout/main.cpp create, lay out widgets and show
+    \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.
+
+    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.
+
+    \raw HTML
+    <table align="left" width="100%">
+    <tr><td>
+    \endraw
+    \snippet snippets/widgets-tutorial/nestedlayouts/main.cpp create, lay out widgets and show
+    \raw HTML
+    </td><td align="right">
+    \endraw
+    \inlineimage widgets-tutorial-nestedlayouts.png
+    \raw HTML
+    </td></tr>
+    </table>
+    \endraw
+
+    As well as QHBoxLayout and QVBoxLayout, Qt also provides QGridLayout
+    and QFormLayout classes to help with more complex user interfaces.
+
+    
+
+    \omit
+    In the simple example below, the widget is created on the stack and will
+    automatically be deleted when the \c{main()} function exits.
+
+    {{{#include <QtGui>
+
+    int main(int argc, char *argv[])
+    {
+        QApplication app(argc, argv);
+        QWidget window;
+        window.resize(480, 360);
+        window.show();
+        return app.exec();
+    }
+    }}}
+    \endomit
+*/