|
1 /**************************************************************************** |
|
2 ** |
|
3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). |
|
4 ** All rights reserved. |
|
5 ** Contact: Nokia Corporation (qt-info@nokia.com) |
|
6 ** |
|
7 ** This file is part of the documentation of the Qt Toolkit. |
|
8 ** |
|
9 ** $QT_BEGIN_LICENSE:LGPL$ |
|
10 ** No Commercial Usage |
|
11 ** This file contains pre-release code and may not be distributed. |
|
12 ** You may use this file in accordance with the terms and conditions |
|
13 ** contained in the Technology Preview License Agreement accompanying |
|
14 ** this package. |
|
15 ** |
|
16 ** GNU Lesser General Public License Usage |
|
17 ** Alternatively, this file may be used under the terms of the GNU Lesser |
|
18 ** General Public License version 2.1 as published by the Free Software |
|
19 ** Foundation and appearing in the file LICENSE.LGPL included in the |
|
20 ** packaging of this file. Please review the following information to |
|
21 ** ensure the GNU Lesser General Public License version 2.1 requirements |
|
22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. |
|
23 ** |
|
24 ** In addition, as a special exception, Nokia gives you certain additional |
|
25 ** rights. These rights are described in the Nokia Qt LGPL Exception |
|
26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. |
|
27 ** |
|
28 ** If you have questions regarding the use of this file, please contact |
|
29 ** Nokia at qt-info@nokia.com. |
|
30 ** |
|
31 ** |
|
32 ** |
|
33 ** |
|
34 ** |
|
35 ** |
|
36 ** |
|
37 ** |
|
38 ** $QT_END_LICENSE$ |
|
39 ** |
|
40 ****************************************************************************/ |
|
41 |
|
42 /*! |
|
43 \page widgets-tutorial.html |
|
44 \title Widgets Tutorial |
|
45 \brief This tutorial covers basic usage of widgets and layouts, showing how |
|
46 they are used to build GUI applications. |
|
47 |
|
48 \startpage {index.html}{Qt Reference Documentation} |
|
49 \contentspage Tutorials |
|
50 \nextpage {tutorials/widgets/toplevel}{Creating a Window} |
|
51 |
|
52 |
|
53 \section1 Introduction |
|
54 |
|
55 Widgets are the basic building blocks of graphical user interface (GUI) |
|
56 applications made with Qt. Each GUI component, such as a button, label or |
|
57 text editor, is a widget and can be placed within an existing user |
|
58 interface or displayed as an independent window. Each type of component |
|
59 is provided by a particular subclass of QWidget, which is itself a |
|
60 subclass of QObject. |
|
61 |
|
62 QWidget is not an abstract class; it can be used as a container for other |
|
63 widgets, and can be subclassed with minimal effort to create custom |
|
64 widgets. It is most often used to create windows in which other widgets |
|
65 are placed. |
|
66 |
|
67 As with \l{QObject}s, widgets can be created with parent objects to |
|
68 indicate ownership, ensuring that objects are deleted when they are no |
|
69 longer used. With widgets, these parent-child relationships have an |
|
70 additional meaning: each child is displayed within the screen area |
|
71 occupied by its parent. This means that, when a window is deleted, all |
|
72 the widgets it contains are automatically deleted. |
|
73 |
|
74 \section1 Writing a main Function |
|
75 |
|
76 Many of the GUI examples in Qt follow the pattern of having a \c{main.cpp} |
|
77 file containing code to initialize the application, and a number of other |
|
78 source and header files containing the application logic and custom GUI |
|
79 components. |
|
80 |
|
81 A typical \c main() function, written in \c{main.cpp}, looks like this: |
|
82 |
|
83 \snippet doc/src/snippets/widgets-tutorial/template.cpp main.cpp body |
|
84 |
|
85 We first construct a QApplication object which is configured using any |
|
86 arguments passed in from the command line. After any widgets have been |
|
87 created and shown, we call QApplication::exec() to start Qt's event loop. |
|
88 Control passes to Qt until this function returns, at which point we return |
|
89 the value we obtain from this function. |
|
90 |
|
91 In each part of this tutorial, we provide an example that is written |
|
92 entirely within a \c main() function. In more sophisticated examples, the |
|
93 code to set up widgets and layouts is written in other parts of the |
|
94 example. For example, the GUI for a main window may be set up in the |
|
95 constructor of a QMainWindow subclass. |
|
96 |
|
97 The \l{Widgets examples} are a good place to look for |
|
98 more complex and complete examples and applications. |
|
99 |
|
100 \section1 Building Examples and Tutorials |
|
101 |
|
102 If you obtained a binary package of Qt or compiled it yourself, the |
|
103 examples described in this tutorial should already be ready to run. |
|
104 However, if you may wish to modify them and recompile them, you need to |
|
105 perform the following steps: |
|
106 |
|
107 \list 1 |
|
108 \o At the command line, enter the directory containing the example you |
|
109 wish to recompile. |
|
110 \o Type \c qmake and press \key{Return}. If this doesn't work, make sure |
|
111 that the executable is on your path, or enter its full location. |
|
112 \o On Linux/Unix and Mac OS X, type \c make and press \key{Return}; |
|
113 on Windows with Visual Studio, type \c nmake and press \key{Return}. |
|
114 \endlist |
|
115 |
|
116 An executable file should have been created within the current directory. |
|
117 On Windows, this file may be located within a \c debug or \c release |
|
118 subdirectory. You can run this file to see the example code at work. |
|
119 */ |
|
120 |
|
121 /*! |
|
122 \page widgets-tutorial-toplevel.html |
|
123 \contentspage {Widgets Tutorial}{Contents} |
|
124 \previouspage {Widgets Tutorial} |
|
125 \nextpage {Widgets Tutorial - Child Widgets} |
|
126 \example tutorials/widgets/toplevel |
|
127 \title Widgets Tutorial - Creating a Window |
|
128 |
|
129 If a widget is created without a parent, it is treated as a window, or |
|
130 \e{top-level widget}, when it is shown. Since it has no parent object to |
|
131 ensure that it is deleted when no longer needed, it is up to the |
|
132 developer to keep track of the top-level widgets in an application. |
|
133 |
|
134 In the following example, we use QWidget to create and show a window with |
|
135 a default size: |
|
136 |
|
137 \raw HTML |
|
138 <table align="left" width="100%"> |
|
139 <tr class="qt-code"><td> |
|
140 \endraw |
|
141 \snippet tutorials/widgets/toplevel/main.cpp main program |
|
142 \raw HTML |
|
143 </td><td align="right"> |
|
144 \endraw |
|
145 \inlineimage widgets-tutorial-toplevel.png |
|
146 \raw HTML |
|
147 </td></tr> |
|
148 </table> |
|
149 \endraw |
|
150 |
|
151 To create a real GUI, we need to place widgets inside the window. To do |
|
152 this, we pass a QWidget instance to a widget's constructor, as we will |
|
153 demonstrate in the next part of this tutorial. |
|
154 */ |
|
155 |
|
156 /*! |
|
157 \page widgets-tutorial-childwidget.html |
|
158 \contentspage {Widgets Tutorial}{Contents} |
|
159 \previouspage {Widgets Tutorial - Creating a Window} |
|
160 \nextpage {Widgets Tutorial - Using Layouts} |
|
161 \example tutorials/widgets/childwidget |
|
162 \title Widgets Tutorial - Child Widgets |
|
163 |
|
164 We can add a child widget to the window created in the previous example by |
|
165 passing \c window as the parent to its constructor. In this case, we add a |
|
166 button to the window and place it in a specific location: |
|
167 |
|
168 \raw HTML |
|
169 <table align="left" width="100%"> |
|
170 <tr class="qt-code"><td> |
|
171 \endraw |
|
172 \snippet tutorials/widgets/childwidget/main.cpp main program |
|
173 \raw HTML |
|
174 </td><td align="right"> |
|
175 \endraw |
|
176 \inlineimage widgets-tutorial-childwidget.png |
|
177 \raw HTML |
|
178 </td></tr> |
|
179 </table> |
|
180 \endraw |
|
181 |
|
182 The button is now a child of the window and will be deleted when the |
|
183 window is destroyed. Note that hiding or closing the window does not |
|
184 automatically destroy it. It will be destroyed when the example exits. |
|
185 */ |
|
186 |
|
187 /*! |
|
188 \page widgets-tutorial-windowlayout.html |
|
189 \contentspage {Widgets Tutorial}{Contents} |
|
190 \previouspage {Widgets Tutorial - Child Widgets} |
|
191 \nextpage {Widgets Tutorial - Nested Layouts} |
|
192 \example tutorials/widgets/windowlayout |
|
193 \title Widgets Tutorial - Using Layouts |
|
194 |
|
195 Usually, child widgets are arranged inside a window using layout objects |
|
196 rather than by specifying positions and sizes explicitly. Here, we |
|
197 construct a label and line edit widget that we would like to arrange |
|
198 side-by-side. |
|
199 |
|
200 \raw HTML |
|
201 <table align="left" width="100%"> |
|
202 <tr class="qt-code"><td> |
|
203 \endraw |
|
204 \snippet tutorials/widgets/windowlayout/main.cpp main program |
|
205 \raw HTML |
|
206 </td><td align="right"> |
|
207 \endraw |
|
208 \inlineimage widgets-tutorial-windowlayout.png |
|
209 \raw HTML |
|
210 </td></tr> |
|
211 </table> |
|
212 \endraw |
|
213 |
|
214 The \c layout object we construct manages the positions and sizes of |
|
215 widgets supplied to it with the \l{QHBoxLayout::}{addWidget()} function. |
|
216 The layout itself is supplied to the window itself in the call to |
|
217 \l{QWidget::}{setLayout()}. Layouts are only visible through the effects |
|
218 they have on the widgets (and other layouts) they are responsible for |
|
219 managing. |
|
220 |
|
221 In the example above, the ownership of each widget is not immediately |
|
222 clear. Since we construct the widgets and the layout without parent |
|
223 objects, we would expect to see an empty window and two separate windows |
|
224 containing a label and a line edit. However, when we tell the layout to |
|
225 manage the label and line edit and set the layout on the window, both the |
|
226 widgets and the layout itself are ''reparented'' to become children of |
|
227 the window. |
|
228 */ |
|
229 |
|
230 /*! |
|
231 \page widgets-tutorial-nestedlayouts.html |
|
232 \contentspage {Widgets Tutorial}{Contents} |
|
233 \previouspage {Widgets Tutorial - Using Layouts} |
|
234 \example tutorials/widgets/nestedlayouts |
|
235 \title Widgets Tutorial - Nested Layouts |
|
236 |
|
237 Just as widgets can contain other widgets, layouts can be used to provide |
|
238 different levels of grouping for widgets. Here, we want to display a |
|
239 label alongside a line edit at the top of a window, above a table view |
|
240 showing the results of a query. |
|
241 |
|
242 We achieve this by creating two layouts: \c{queryLayout} is a QHBoxLayout |
|
243 that contains QLabel and QLineEdit widgets placed side-by-side; |
|
244 \c{mainLayout} is a QVBoxLayout that contains \c{queryLayout} and a |
|
245 QTableView arranged vertically. |
|
246 |
|
247 \raw HTML |
|
248 <table align="left" width="100%"> |
|
249 <tr class="qt-code"><td> |
|
250 \endraw |
|
251 \snippet tutorials/widgets/nestedlayouts/main.cpp first part |
|
252 \snippet tutorials/widgets/nestedlayouts/main.cpp last part |
|
253 \raw HTML |
|
254 </td><td align="right"> |
|
255 \endraw |
|
256 \inlineimage widgets-tutorial-nestedlayouts.png |
|
257 \raw HTML |
|
258 </td></tr> |
|
259 </table> |
|
260 \endraw |
|
261 |
|
262 Note that we call the \c{mainLayout}'s \l{QBoxLayout::}{addLayout()} |
|
263 function to insert the \c{queryLayout} above the \c{resultView} table. |
|
264 |
|
265 We have omitted the code that sets up the model containing the data shown |
|
266 by the QTableView widget, \c resultView. For completeness, we show this below. |
|
267 |
|
268 As well as QHBoxLayout and QVBoxLayout, Qt also provides QGridLayout |
|
269 and QFormLayout classes to help with more complex user interfaces. |
|
270 These can be seen if you run \l{Qt Designer}. |
|
271 |
|
272 \section1 Setting up the Model |
|
273 |
|
274 In the code above, we did not show where the table's data came from |
|
275 because we wanted to concentrate on the use of layouts. Here, we see |
|
276 that the model holds a number of items corresponding to rows, each of |
|
277 which is set up to contain data for two columns. |
|
278 |
|
279 \snippet tutorials/widgets/nestedlayouts/main.cpp set up the model |
|
280 |
|
281 The use of models and views is covered in the |
|
282 \l{Item Views Examples} and in the \l{Model/View Programming} overview. |
|
283 */ |