source: trunk/doc/src/tutorials/widgets-tutorial.qdoc@ 846

Last change on this file since 846 was 846, checked in by Dmitry A. Kuminov, 14 years ago

trunk: Merged in qt 4.7.2 sources from branches/vendor/nokia/qt.
File size: 10.0 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4** All rights reserved.
5** Contact: Nokia Corporation ([email protected])
6**
7** This file is part of the documentation of the Qt Toolkit.
8**
9** $QT_BEGIN_LICENSE:FDL$
10** Commercial Usage
11** Licensees holding valid Qt Commercial licenses may use this file in
12** accordance with the Qt Commercial License Agreement provided with the
13** Software or, alternatively, in accordance with the terms contained in a
14** written agreement between you and Nokia.
15**
16** GNU Free Documentation License
17** Alternatively, this file may be used under the terms of the GNU Free
18** Documentation License version 1.3 as published by the Free Software
19** Foundation and appearing in the file included in the packaging of this
20** file.
21**
22** If you have questions regarding the use of this file, please contact
23** Nokia at [email protected].
24** $QT_END_LICENSE$
25**
26****************************************************************************/
27
28/*!
29 \page widgets-tutorial.html
30 \title Widgets Tutorial
31 \brief This tutorial covers basic usage of widgets and layouts, showing how
32 they are used to build GUI applications.
33
34 \section1 Introduction
35
36 Widgets are the basic building blocks for graphical user interface
37 (GUI) applications built with Qt. Each GUI component (e.g.
38 buttons, labels, text editor) is a \l{QWidget}{widget} that is
39 placed somewhere within a user interface window, or is displayed
40 as an independent window. Each type of widge is provided by a
41 subclass of QWidget, which is itself a subclass of QObject.
42
43 QWidget is not an abstract class. It can be used as a container
44 for other widgets, and it can be subclassed with minimal effort to
45 create new, custom widgets. QWidget is often used to create a
46 window inside which other \l{QWidget}s are placed.
47
48 As with \l{QObject}s, \l{QWidget}s can be created with parent
49 objects to indicate ownership, ensuring that objects are deleted
50 when they are no longer used. With widgets, these parent-child
51 relationships have an additional meaning: Each child widget is
52 displayed within the screen area occupied by its parent widget.
53 This means that when you delete a window widget, all the child
54 widgets it contains are also deleted.
55
56 \section1 Writing a main Function
57
58 Many of the GUI examples provided with Qt follow the pattern of
59 having a \c{main.cpp} file, which contains the standard code to
60 initialize the application, plus any number of other source/header
61 files that contain the application logic and custom GUI components.
62
63 A typical \c main() function in \c{main.cpp} looks like this:
64
65 \snippet doc/src/snippets/widgets-tutorial/template.cpp main.cpp body
66
67 First, a QApplication object is constructed, which can be
68 configured with arguments passed in from the command line. After
69 the widgets have been created and shown, QApplication::exec() is
70 called to start Qt's event loop. Control passes to Qt until this
71 function returns. Finally, \c{main()} returns the value returned
72 by QApplication::exec().
73
74 \section1 Simple widget examples
75
76 Each of theses simple widget examples is written entirely within
77 the \c main() function.
78
79 \list
80 \o \l {tutorials/widgets/toplevel} {Creating a window}
81
82 \o \l {tutorials/widgets/childwidget} {Creating child widgets}
83
84 \o \l {tutorials/widgets/windowlayout} {Using layouts}
85
86 \o \l {tutorials/widgets/nestedlayouts} {Nested layouts}
87 \endlist
88
89 \section1 Real world widget examples
90
91 In these \l{Widget examples} {more advanced examples}, the code
92 that creates the widgets and layouts is stored in other files. For
93 example, the GUI for a main window may be created in the
94 constructor of a QMainWindow subclass.
95
96 \section1 Building The Examples
97
98 If you installed a binary package to get Qt, or if you compiled Qt
99 yourself, the examples described in this tutorial should already
100 be built and ready to run. If you wish to modify and recompile
101 them, follow these steps:
102
103 \list 1
104
105 \o From a command prompt, enter the directory containing the
106 example you have modified.
107
108 \o Type \c qmake and press \key{Return}. If this doesn't work,
109 make sure that the executable is on your path, or enter its
110 full location.
111
112 \o On Linux/Unix and Mac OS X, type \c make and press
113 \key{Return}; on Windows with Visual Studio, type \c nmake and
114 press \key{Return}.
115
116 \endlist
117
118 An executable file is created in the current directory. On
119 Windows, this file may be located in a \c debug or \c release
120 subdirectory. You can run this executable to see the example code
121 at work.
122*/
123
124/*!
125 \example tutorials/widgets/toplevel
126 \title Widgets Tutorial - Creating a Window
127
128 If a widget is created without a parent, it is treated as a window, or
129 \e{top-level widget}, when it is shown. Since it has no parent object to
130 ensure that it is deleted when no longer needed, it is up to the
131 developer to keep track of the top-level widgets in an application.
132
133 In the following example, we use QWidget to create and show a window with
134 a default size:
135
136 \raw HTML
137 <table align="left" width="100%">
138 <tr class="qt-code"><td>
139 \endraw
140 \snippet tutorials/widgets/toplevel/main.cpp main program
141 \raw HTML
142 </td><td align="right">
143 \endraw
144 \inlineimage widgets-tutorial-toplevel.png
145 \raw HTML
146 </td></tr>
147 </table>
148 \endraw
149
150 To create a real GUI, we need to place widgets inside the window. To do
151 this, we pass a QWidget instance to a widget's constructor, as we will