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

Last change on this file since 898 was 846, checked in by Dmitry A. Kuminov, 15 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 (qt-info@nokia.com)
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 qt-info@nokia.com.
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)
296 \o \l{Object Model}
297 \row
298 \o qmake and the Qt build system
299 \o \l{qmake Manual}
300 \endtable
301
302 \section2 Creating a .pro file
303
304 For this example, we write our own \c .pro file instead of
305 using \c qmake's \c -project option.
306
307 \code
308 HEADERS = notepad.h
309 SOURCES = notepad.cpp \
310 main.cpp
311 \endcode
312
313 The following shell commands build the example.
314
315 \code
316 qmake
317 make
318 \endcode
319
320 \section1 Using a QMainWindow
321
322 Many applications will benefit from using a QMainWindow, which has
323 its own layout to which you can add a menu bar, dock widgets, tool
324 bars, and a status bar. QMainWindow has a center area that can be
325 occupied by any kind of widget. In our case, we will place our
326 text edit there.
327
328 \image gs4.png
329
330 Let us look at the new \c Notepad class definition.
331
332 \code
333 #include <QtGui>
334
335 class Notepad : public QMainWindow
336 {
337 Q_OBJECT
338
339 public:
340 Notepad();
341
342 private slots:
343 void open();
344 void save();
345 void quit();
346
347 private:
348 QTextEdit *textEdit;
349
350 QAction *openAction;
351 QAction *saveAction;
352 QAction *exitAction;
353
354 QMenu *fileMenu;
355 };
356 \endcode
357
358 We include two more slots that can save and open a document. We
359 will implement these in the next section.
360
361 Often, in a main window, the same slot should be invoked by
362 several widgets. Examples are menu items and buttons on a tool
363 bar. To make this easier, Qt provides QAction, which can be given
364 to several widgets, and be connected to a slot. For instance, both
365 QMenu and QToolBar can create menu items and tool buttons from the
366 same \l{QAction}s. We will see how this works shortly.
367
368 As before, we use the \c {Notepad}s constructor to set up the
369 GUI.
370
371 \code
372 Notepad::Notepad()
373 {
374 saveAction = new QAction(tr("&Open"), this);
375 saveAction = new QAction(tr("&Save"), this);
376 exitAction = new QAction(tr("E&xit"), this);
377
378 connect(openAction, SIGNAL(triggered()), this, SLOT(open()));
379 connect(saveAction, SIGNAL(triggered()), this, SLOT(save()));
380 connect(exitAction, SIGNAL(triggered()), qApp, SLOT(quit()));
381
382 fileMenu = menuBar()->addMenu(tr("&File"));
383 fileMenu->addAction(openAction);
384 fileMenu->addAction(saveAction);
385 fileMenu->addSeparator();
386 fileMenu->addAction(exitAction);
387
388 textEdit = new QTextEdit;
389 setCentralWidget(textEdit);
390
391 setWindowTitle(tr("Notepad"));
392 }
393 \endcode
394
395 \l{QAction}s are created with the text that should appear on the
396 widgets that we add them to (in our case, menu items). If we also
397 wanted to add them to a tool bar, we could have given
398 \l{QIcon}{icons} to the actions.
399
400 When a menu item is clicked now, the item will trigger the action,
401 and the respective slot will be invoked.
402
403 \section2 Learn More
404
405 \table
406 \header
407 \o About
408 \o Here
409 \row
410 \o Main windows and main window classes
411 \o \l{Application Main Window},
412 \l{Main Window Examples}
413 \row
414 \o MDI applications
415 \o QMdiArea,
416 \l{MDI Example}
417 \endtable
418
419 \section1 Saving and Loading
420
421 In this example, we will implement the functionality of the \c
422 open() and \c save() slots that we added in the previous example.
423
424 \image gs5.png
425
426 We will start with the \c open() slot:
427
428 \code
429 QString fileName = QFileDialog::getOpenFileName(this, tr("Open File"), "",
430 tr("Text Files (*.txt);;C++ Files (*.cpp *.h)"));
431
432 if (fileName != "") {
433 QFile file(fileName);
434 if (!file.open(QIODevice::ReadOnly)) {
435 QMessageBox::critical(this, tr("Error"),
436 tr("Could not open file"));
437 return;
438 }
439 QString contents = file.readAll().constData();
440 textEdit->setPlainText(contents);
441 file.close();
442 }
443 \endcode
444
445 The first step is asking the user for the name of the file to
446 open. Qt comes with QFileDialog, which is a dialog from which the
447 user can select a file. The image above shows the dialog on
448 Kubuntu. The static \l{QFileDialog::}{getOpenFileName()} function
449 displays a modal file dialog, and does not return until the user
450 has selected a file. It returns the file path of the file
451 selected, or an empty string if the user canceled the dialog.
452
453 If we have a file name, we try to open the file with
454 \l{QIODevice::}{open()}, which returns true if the file could be
455 opened. We will not go into error handling here, but you can follow
456 the links from the learn more section. If the file could not be
457 opened, we use QMessageBox to display a dialog with an error
458 message (see the QMessageBox class description for further
459 details).
460
461 Actually reading in the data is trivial using the
462 \l{QIODevice::}{readAll()} function, which returns all data in the
463 file in a QByteArray. The \l{QByteArray::}{constData()} returns all
464 data in the array as a const char*, which QString has a
465 constructor for. The contents can then be displayed in the text
466 edit. We then \l{QIODevice::}{close()} the file to return the file
467 descriptor back to the operating system.
468
469 Now, let us move on to the the \c save() slot.
470
471 \code
472 QString fileName = QFileDialog::getSaveFileName(this, tr("Save File"), "",
473 tr("Text Files (*.txt);;C++ Files (*.cpp *.h)"));
474
475 if (fileName != "") {
476 QFile file(fileName);
477 if (!file.open(QIODevice::WriteOnly)) {
478 // error message
479 } else {
480 QTextStream stream(&file);
481 stream << textEdit->toPlainText();
482 stream.flush();
483 file.close();
484 }
485 }
486 \endcode
487
488 When we write the contents of the text edit to the file, we use
489 the QTextStream class, which wraps the QFile object. The text
490 stream can write QStrings directly to the file; QFile only accepts
491 raw data (char*) with the \l{QIODevice::}{write()} functions of
492 QIODevice.
493
494 \section2 Learn More
495
496 \table
497 \header
498 \o About
499 \o Here
500 \row
501 \o Files and I/O devices
502 \o QFile, QIODevice
503 \endtable
504
505 \omit
506 \section1 Moving On
507
508 This may not be true for the first release.
509 The Qt documentation comes with three getting started guides. You
510 have come to the end of the first, which concerns itself with
511 basic Qt concepts. We also have guides covering intermediate and
512 advanced topics. They are found here: You may also have noticed that the learn more sections in
513 this guide frequently linked to them.
514 Basic Qt Architecture
515 \endomit
516*/
517
Note: See TracBrowser for help on using the repository browser.