source: trunk/doc/src/getting-started/gettingstartedqt.qdoc@ 973

Last change on this file since 973 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: 17.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 gettingstartedqt.html
30
31 \title Getting Started Programming with Qt
32 \ingroup gettingStarted
33
34 Welcome to the world of Qt--the cross-platform GUI toolkit. In
35 this getting started guide, we teach basic Qt knowledge by
36 implementing a simple Notepad application. After reading this
37 guide, you should be ready to delve into our overviews and API
38 documentation, and find the information you need for the
39 application you are developing.
40
41 \section1 Hello Notepad
42
43 In this first example, we simply create and show a text edit in a
44 window frame on the desktop. This represents the simplest possible
45 Qt program that has a GUI.
46
47 \image gs1.png
48
49 Here is the code:
50
51 \code
52 1 #include <QApplication>
53 2 #include <QTextEdit>
54 3
55 4 int main(int argv, char **args)
56 5 {
57 6 QApplication app(argv, args);
58 7
59 8 QTextEdit textEdit;
60 9 textEdit.show();
6110
6211 return app.exec();
6312 }
64 \endcode
65
66 Let us go through the code line by line. In the first two lines, we
67 include the header files for QApplication and QTextEdit, which are
68 the two classes that we need for this example. All Qt classes have
69 a header file named after them.
70
71 Line 6 creates a QApplication object. This object manages
72 application-wide resources and is necessary to run any Qt program
73 that has a GUI. It needs \c argv and \c args because Qt accepts a
74 few command line arguments.
75
76 Line 8 creates a QTextEdit object. A text edit is a visual element
77 in the GUI. In Qt, we call such elements widgets. Examples of
78 other widgets are scroll bars, labels, and radio buttons. A widget
79 can also be a container for other widgets; a dialog or a main
80 application window, for example.
81
82 Line 9 shows the text edit on the screen in its own window frame.
83 Since widgets also function as containers (for instance a
84 QMainWindow, which has toolbars, menus, a status bar, and a few
85 other widgets), it is possible to show a single widget in its own
86 window. Widgets are not visible by default; the function
87 \l{QWidget::}{show()} makes the widget visible.
88
89 Line 11 makes the QApplication enter its event loop. When a Qt
90 application is running, events are generated and sent to the
91 widgets of the application. Examples of events are mouse presses
92 and key strokes. When you type text in the text edit widget, it
93 receives key pressed events and responds by drawing the text
94 typed.
95
96 To run the application, open a command prompt, and enter the
97 directory in which you have the \c .cpp file of the program. The
98 following shell commands build the program.
99
100 \code
101 qmake -project
102 qmake
103 make
104 \endcode
105
106 This will leave an executable in the \c part1 directory (note that
107 on Windows, you may have to use \c nmake instead of \c make. Also,
108 the executable will be placed in part1/debug or part1/release). \c
109 qmake is Qt's build tool, which takes a configuration file. \c
110 qmake generates this for us when given the \c{-project} argument.
111 Given the configuration file (suffixed .pro), \c qmake produces a
112 \c make file that will build the program for you. We will look
113 into writing our own \c .pro files later.
114
115 \section2 Learn More
116
117 \table
118 \header
119 \o About
120 \o Here
121 \row
122 \o Widgets and Window Geometry
123 \o \l{Window and Dialog Widgets}
124 \row
125 \o Events and event handling
126 \o \l{The Event System}
127 \endtable
128
129 \section1 Adding a Quit Button
130
131 In a real application, you will normally need more than one
132 widget. We will now introduce a QPushButton beneath the text edit.
133 The button will exit the Notepad application when pushed (i.e.,
134 clicked on with the mouse).
135
136 \image gs2.png
137
138 Let us take a look at the code.
139
140 \code
141 1 #include <QtGui>
142 2
143 3 int main(int argv, char **args)
144 4 {
145 5 QApplication app(argv, args);
146 6
147 7 QTextEdit textEdit;
148 8 QPushButton quitButton("Quit");
149 9
15010 QObject::connect(&quitButton, SIGNAL(clicked()), qApp, SLOT(quit()));
15111
15212 QVBoxLayout layout;
15313 layout.addWidget(&textEdit);
15414 layout.addWidget(&quitButton);
15515
15616 QWidget window;
15717 window.setLayout(&layout);
15818
15919 window.show();
16020
16121 return app.exec();
16222 }
163 \endcode
164
165 Line 1 includes QtGui, which contains all of Qt's GUI classes.
166
167 Line 10 uses Qt's Signals and Slots mechanism to make the
168 application exit when the \gui {Quit button} is pushed. A slot is
169 a function that can be invoked at runtime using its name (as a
170 literal string). A signal is a function that when called will
171 invoke slots registered with it; we call that to connect the slot
172 to the signal and to emit the signal.
173
174 \l{QApplication::}{quit()} is a slot of QApplication that exits
175 the application. \l{QPushButton::}{clicked()} is a signal that
176 QPushButton emits when it is pushed. The static
177 QObject::connect() function takes care of connecting the slot to
178 the signal. SIGNAL() and SLOT() are two macros that take the
179 function signatures of the signal and slot to connect. We also
180 need to give pointers to the objects that should send and receive
181 the signal.
182
183 Line 12 creates a QVBoxLayout. As mentioned, widgets can contain
184 other widgets. It is possible to set the bounds (the location and
185 size) of child widgets directly, but it is usually easier to use a
186 layout. A layout manages the bounds of a widget's children.
187 QVBoxLayout, for instance, places the children in a vertical row.
188
189 Line 13 and 14 adds the text edit and button to the layout. In
190 line 17, we set the layout on a widget.
191
192 \section2 Learn More
193
194 \table
195 \header
196 \o About
197 \o Here
198 \row
199 \o Signals and slots
200 \o \l{Signals & Slots}
201 \row
202 \o Layouts
203 \o \l{Layout Management},
204 \l{Widgets and Layouts},
205 \l{Layout Examples}
206 \row
207 \o The widgets that come with Qt
208 \o \l{Qt Widget Gallery},
209 \l{Widget Examples}
210 \endtable
211
212 \section1 Subclassing QWidget
213
214 When the user wants to quit an application, you might want to
215 pop-up a dialog that asks whether he/she really wants to quit. In
216 this example, we subclass QWidget, and add a slot that we connect
217 to the \gui {Quit button}.
218
219 \image gs3.png
220
221 Let us look at the code:
222
223 \code
224 5 class Notepad : public QWidget
225 6 {
226 7 Q_OBJECT
227 8
228 9 public:
22910 Notepad();
23011
23112 private slots:
23213 void quit();
23314
23415 private:
23516 QTextEdit *textEdit;
23617 QPushButton *quitButton;
23718 };
238 \endcode
239
240 The \c Q_OBJECT macro must be first in the class definition, and
241 declares our class as a \c QObject (Naturally, it must also
242 inherit from QObject). A \l{QObject} adds several abilities to a
243 normal C++ class. Notably, the class name and slot names can be
244 queried at run-time. It is also possible to query a slot's
245 parameter types and invoke it.
246
247 Line 13 declares the slot \c quit(). This is easy using the \c
248 slots macro. The \c quit() slot can now be connected to signals
249 with a matching signature (any signal that takes no parameters).
250
251 Instead of setting up the GUI and connecting the slot in the \c
252 main() function, we now use \c{Notepad}'s constructor.
253
254 \code
255 Notepad::Notepad()
256 {
257 textEdit = new QTextEdit;
258 quitButton = new QPushButton(tr("Quit"));
259
260 connect(quitButton, SIGNAL(clicked()), this, SLOT(quit()));
261
262 QVBoxLayout *layout = new QVBoxLayout;
263 layout->addWidget(textEdit);
264 layout->addWidget(quitButton);
265
266 setLayout(layout);
267
268 setWindowTitle(tr("Notepad"));
269 }
270 \endcode
271
272 As you saw in the class definition, we use pointers to our \l
273 {QObject}s (\c textEdit and \c quitButton). As a rule, you should
274 always allocate \l{QObject}s on the heap and never copy them.
275
276 We now use the function \l{QObject::}{tr()} around our user
277 visible strings. This function is necessary when you want to
278 provide your application in more than one language (e.g. English
279 and Chinese). We will not go into details here, but you can follow
280 the \c {Qt Linguist} link from the learn more table.
281
282 \section2 Learn More
283
284 \table
285 \header
286 \o About
287 \o Here
288 \row
289 \o tr() and internationalization
290 \o \l{Qt Linguist Manual},
291 \l{Writing Source Code for Translation},
292 \l{Hello tr() Example},
293 \l{Internationalization with Qt}
294 \row
295 \o QObjects and the Qt Object model (This is essential to understand Qt)