Home · All Classes · Overviews

[Tutorials] [Next: Creating a Window]

Widgets Tutorial

Introduction

Widgets are the basic building blocks of graphical user interface (GUI) applications made with Qt. Each GUI component, such as a button, label or text editor, is a widget and can be placed within an existing user interface or displayed as an independent window. Each type of component is provided by a particular subclass of QWidget, which is itself a subclass of QObject.

QWidget is not an abstract class; it can be used as a container for other widgets, and can be subclassed with minimal effort to create custom widgets. It is most often used to create windows in which other widgets are placed.

As with QObjects, widgets can be created with parent objects to indicate ownership, ensuring that objects are deleted when they are no longer used. With widgets, these parent-child relationships have an additional meaning: each child is displayed within the screen area occupied by its parent. This means that, when a window is deleted, all the widgets it contains are automatically deleted.

Writing a main Function

Many of the GUI examples in Qt follow the pattern of having a main.cpp file containing code to initialize the application, and a number of other source and header files containing the application logic and custom GUI components.

A typical main() function, written in main.cpp, looks like this:

 /****************************************************************************
 **
 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
 ** Contact: Nokia Corporation (qt-info@nokia.com)
 **
 ** This file is part of the documentation of the Qt Toolkit.
 **
 ** $QT_BEGIN_LICENSE:LGPL$
 ** No Commercial Usage
 ** This file contains pre-release code and may not be distributed.
 ** You may use this file in accordance with the terms and conditions
 ** contained in the Technology Preview License Agreement accompanying
 ** this package.
 **
 ** GNU Lesser General Public License Usage
 ** Alternatively, this file may be used under the terms of the GNU Lesser
 ** General Public License version 2.1 as published by the Free Software
 ** Foundation and appearing in the file LICENSE.LGPL included in the
 ** packaging of this file.  Please review the following information to
 ** ensure the GNU Lesser General Public License version 2.1 requirements
 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
 **
 ** In addition, as a special exception, Nokia gives you certain
 ** additional rights.  These rights are described in the Nokia Qt LGPL
 ** Exception version 1.1, included in the file LGPL_EXCEPTION.txt in this
 ** package.
 **
 ** If you have questions regarding the use of this file, please contact
 ** Nokia at qt-info@nokia.com.
 **
 **
 **
 **
 **
 **
 **
 **
 ** $QT_END_LICENSE$
 **
 ****************************************************************************/

 #include <QtGui>

 // Include header files for application components.
 // ...

 int main(int argc, char *argv[])
 {
     QApplication app(argc, argv);

     // Set up and show widgets.
     // ...

     return app.exec();
 }

We first construct a QApplication object which is configured using any arguments passed in from the command line. After any widgets have been created and shown, we call QApplication::exec() to start Qt's event loop. Control passes to Qt until this function returns, at which point we return the value we obtain from this function.

In each part of this tutorial, we provide an example that is written entirely within a main() function. In more sophisticated examples, the code to set up widgets and layouts is written in other parts of the example. For example, the GUI for a main window may be set up in the constructor of a QMainWindow subclass.

The Widgets examples are a good place to look for more complex and complete examples and applications.

Building Examples and Tutorials

If you obtained a binary package of Qt or compiled it yourself, the examples described in this tutorial should already be ready to run. However, if you may wish to modify them and recompile them, you need to perform the following steps:

1. At the command line, enter the directory containing the example you wish to recompile.
2. Type qmake and press Return. If this doesn't work, make sure that the executable is on your path, or enter its full location.
3. On Linux/Unix and Mac OS X, type make and press Return; on Windows with Visual Studio, type nmake and press Return.

An executable file should have been created within the current directory. On Windows, this file may be located within a debug or release subdirectory. You can run this file to see the example code at work.

[Tutorials] [Next: Creating a Window]