/****************************************************************************
**
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia.  For licensing terms and
** conditions see http://qt.digia.com/licensing.  For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file.  Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page widgets-tutorial.html
    \title Widgets 教程
    \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 教程
    \nextpage {Widgets 教程 — 创建窗口}


    \section1 简介

    Widget 是使用 Qt 编写的图形用户界面 (GUI) 应用程序的基本生成块。每个 GUI 组件，如按钮、标签或文本编辑器，都是一个 widget ，并可以放置在现有的用户界面中或作为单独的窗口显示。每种类型的组件都是由 QWidget 的特殊子类提供的，而 QWidget 自身又是 QObject 的子类。

    QWidget 不是一个抽象类；它可用作其他 widget 的容器，并很容易作为子类使用来创建定制 widget。它经常用来创建放置其他 widget 的窗口。

    至于 QObject，可使用父对象创建 widget 以表明其所属关系，这可确保删除不再使用的对象。使用 widget，这些父子关系就有了更多的意义：每个子类都显示在其父级所拥有的屏幕区域内。也就是说，当删除窗口时，其包含的所有 widget 也都自动删除。

    \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 教程}{目录}
    \previouspage {Widgets 教程}
    \nextpage {Widgets 教程 — Child Widgets}
    \example tutorials/widgets/toplevel
    \title Widgets 教程 — 创建窗口

    如果 widget 未使用父级进行创建，则在显示时视为窗口或\e{顶层 widget}。由于顶层 widget 没有父级对象类来确保在其不再使用时就删除，因此需要开发人员在应用程序中对其进行跟踪。

    在下例中，我们使用 QWidget 创建和显示具有默认大小的窗口：

    \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 教程}{目录}
    \previouspage {Widgets 教程 — 创建窗口}
    \nextpage {Widgets 教程 — 使用布局}
    \example tutorials/widgets/childwidget
    \title Widgets 教程 — Child Widgets

    我们可以通过将 \c window 作为父级传递给其构造器来向窗口添加子 widget。在这种情况下，我们向窗口添加按钮并将其放置在特定位置：

    \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

    该按钮现在为窗口的子项，并在删除窗口时一同删除。请注意，隐藏或关闭窗口不会自动删除该按钮。
*/

/*!
    \page widgets-tutorial-windowlayout.html
    \contentspage {Widgets 教程}{目录}
    \previouspage {Widgets 教程 — Child Widgets}
    \nextpage {Widgets 教程 — Nested Layouts}
    \example tutorials/widgets/windowlayout
    \title Widgets 教程 — 使用布局

    通常，子 widget 是通过使用布局对象在窗口中进行排列，而不是通过指定位置和大小进行排列。在此处，我们构造要并排排列的标签和行编辑框 widget。

    \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

    我们构造的布局对象管理通过 \l{QHBoxLayout::}{addWidget()} 函数提供的 widget 的位置和大小。布局本身是通过调用 \l{QWidget::}{setLayout()} 提供给窗口的。布局仅可通过其对所管理的 widget（和其他布局）的效果才可显示。

    在上文示例中，每个 widget 的所属关系并不明显。由于我们未使用父级对象构造 widget 和布局，我们会看到一个空窗口和两个包含了标签与行编辑框的窗口。不过，如果我们告知布局来管理标签和行编辑框，并在窗口中设置布局，两个 widget 与布局本身就都会成为窗口的子项。
*/

/*!
    \page widgets-tutorial-nestedlayouts.html
    \contentspage {Widgets 教程}{目录}
    \previouspage {Widgets 教程 — 使用布局}
    \example tutorials/widgets/nestedlayouts
    \title Widgets 教程 — Nested Layouts

    由于 widget 可包含其他 widget，布局可用来提供按不同层次分组的 widget。这里，我们要在显示查询结果的表视图上方、窗口顶部的行编辑框旁，显示一个标签。

    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.

    除了 QHBoxLayout 和 QVBoxLayout，Qt 还提供了 QGridLayout 和 QFormLayout 类来协助实现更复杂的用户界面。
    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.
*/
