Basics, Tools, and First Code
1.1 Our First Qt Program
Following in the tradition of many programming books and tutorials, this book will start with the obligatory “Hello, world!” program. This minimal Qt application, which we will save in a file called main.cpp, simply opens a window displaying the text Hello, world! when it is run:
// helloWorld/main.cpp
#include <QApplication>
#include <QLabel>
int main(int argc, char *argv[]) {
QApplication a(argc, argv);
QLabel label("Hello World");
label.show();
return a.exec();
}
For this purpose, the first two lines of code include the header files for the Qt classes that we want to use in the following code. In our case these header files contain the interface descriptions for the classes QApplication and QLabel.
In Qt 4 there is precisely one header file for each Qt class, which is namedwithout the otherwise standard filename extension .h: Its name corresponds exactly to the class name.1 When you give the #include directive, make sure that you capitalize the header filename correctly.
The fourth line of the listing onward shows what a typical main() function of a Qt program looks like. First you create a QApplication object and pass to its constructor the command-line arguments that the user supplied when invoking the finished program. No GUI program can manage without a QApplication object, because, among other things, QApplication makes available anevent loop. This loop ensures that the application continues running until its window is closed.
Next we create a QLabel object that displays the text “Hello, world!”. Initially, this object is invisible. We must call its show() function in order to make it appear—as shown in Figure 1.1—in a window.
Figure 1.1:
The first Qt program
Finally the call to exec() starts the event loop which is in charge of forwarding ap-plication events to the appropriate objects. Such events are caused by user actions, such as clicking a button. In our first example we will leave event handling entirely to Qt itself. Section 1.3 (page 35) shows how additional user interaction can be implemented.
The event loop is terminated when the quit() function of the QApplication object is called. In our example, this happens indirectly when the last main window of the application (which in this case is label) closes and is deleted from memory.
1 In reality, these files themselves just contain a directive that loads the corresponding .h file.
These are not documented, however, so that you can never be quite sure whether Trolltech might have made unannounced changes.
1.1.1 Compiling a Qt Program
When compiling this program, you are faced with a problem: Qt is supported on various platforms, and the details of the compilation process differ for each type of system. The Qt vendor Trolltech solves this problem with a simple program that is used to create projects on a cross-platform basis: qmake.
qmake generates a Makefile from a project file that describes the application in a form that is independent of the operating system on which the application is actually compiled. The generated Makefile contains all the information required to compile the C++ application code on a specific platform. (In Windows it is also possible to generate Visual Studio projects from qmake project files.)
Generating Project Files and Makefiles withqmake
To generate a project file for the “Hello, world!” program, it is sufficient to call qmake with the -project option.2 To do this, open a shell and change the current directory to the directory containing the source file. If the source text is located in the directory helloWorld and has the name, as in our case, main.cpp,3then the command
user@linux:helloWorld$ qmake -project
will generate a file called helloWorld.pro with the following contents:
#helloWorld/helloWorld.pro
#####################################
# Automatically generated by qmake
#####################################
TEMPLATE = app CONFIG -= moc DEPENDPATH += . INCLUDEPATH += .
# Input
SOURCES += main.cpp
2 Please make sure that you really do use the Qt 4 qmake, which differs significantly from the Qt 3 version. Use of the latter on Qt 4 projects causes errors. Many Linux distributions contain both Qt 3 and Qt 4; in Ubuntu Breezy Badger and Dapper Drake, for example, qmake is linked by default to qmake-qt3. The Qt 4 version of the tool can be run with qmake-qt4; if you seldom need the third edition, change the corresponding link to /etc/alternatives.
3 Although qmake does not require main.cpp to contain the main() function, this convention has become established.
The interesting entries here are the ones for TEMPLATE and SOURCES.4The value of TEMPLATE specifies whether we want to create an application (app) or a library (lib); that of SOURCES specifies the source text files of which the project consists.
Simply running qmake is then sufficient to generate the Makefile from the project file:
user@linux:helloWorld$ qmake
In Windows this command generates three files: Makefile, Makefile.Debug, and Makefile.Release. Makefile here is a metafile that refers to the two other files.
Makefile.Debug and Makefile.Release describe how the make program should put the project together.
On Unix platforms (including Linux and Mac OS X projects built with qmake -spec mac-g++, as described below), qmake generates only the Makefile file, which cre-ates an executable of the program that includes debug output after make is run, unless the debug variants of the Qt libraries used by the program are missing.5 To ensure that these are installed, on Unix systems you should search for the li-brary files with _debug.so in the name, for example, libQtCore_debug.so.4 for the debug version of the QtCore library. In Windows you should look for the corre-sponding DLL files with names ending in d before the version number, for example, qtcored4.dll for the debug version of QtCore. Clicking the entry Build debug li-braries in the start menu folder Program ensures that Qt builds its debug lili-braries.
Furthermore, in order to achieve the same results with qmake in Unix as in Win-dows, not only must the debug libraries be available, but the following line must also be included in helloWorld.pro:
CONFIG += debug_and_release
The operator += here has the same function as in C++: It adds a further option to the variable, without overwriting the ones already set. The -= operator is used similarly to remove individual options.
Alternatively you can set the environment variable QMAKEFLAGS to the value ’CON-FIG+=debug_and_release’ (don’t forget the apostrophes!) before running qmake. But the entry in the .pro file simplifies development if several programmers are all working on the code (or working with one program on several computers) using a version control system such as CVS, Subversion, or Visual Source Safe.
4 The other entries are not required; qmake can be too cautious when automatically generating a project. CONFIG = -moc specifies that we do not need the meta-object compiler for this project, and in the entries for INCLUDEPATH and DEPENDPATH we can specify directories in which the compiler should search for include files.
5 The debug libraries may need to be installed separately in, for example, Kubuntu (libqt4-debug, libqt4-debug-dev) and SUSE (qt-debug, qt-devel).
If you just want the debug-enabled variation of the executable application, the CONFIG variable should include the value debug. Likewise, you can include release if you just want to generate executable files without extra debugging support, suitable for release to the end user.
Compiling the Project
The make command issued without any target or with the release target, for ex-ample,
user@linux:helloWorld$ make release
creates a release version of the project, whereas
user@linux:helloWorld$ make debug
accordingly creates a debug version. If you use Microsoft Visual Studio, change the command make to nmake. In either case, the executable file is stored in the release or debug subdirectory, as appropriate.
Once the application is compiled in this way and executed on Unix systems with either ./release/helloWorld or ./debug/helloWorld, the window opens as shown in Figure 1.1 on page 26.