diff options
author | Lars Knoll <lars.knoll@nokia.com> | 2009-03-23 09:34:13 (GMT) |
---|---|---|
committer | Simon Hausmann <simon.hausmann@nokia.com> | 2009-03-23 09:34:13 (GMT) |
commit | 67ad0519fd165acee4a4d2a94fa502e9e4847bd0 (patch) | |
tree | 1dbf50b3dff8d5ca7e9344733968c72704eb15ff /doc/src/tutorials/widgets-tutorial.qdoc | |
download | Qt-67ad0519fd165acee4a4d2a94fa502e9e4847bd0.zip Qt-67ad0519fd165acee4a4d2a94fa502e9e4847bd0.tar.gz Qt-67ad0519fd165acee4a4d2a94fa502e9e4847bd0.tar.bz2 |
Long live Qt!
Diffstat (limited to 'doc/src/tutorials/widgets-tutorial.qdoc')
-rw-r--r-- | doc/src/tutorials/widgets-tutorial.qdoc | 193 |
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 +*/ |