Writing Qt Examples

This page is part of the Qt Writing Guidelines.

Qt examples follows the Qt Project's QUIP policy system.

In particular, QUIP-13 specifies the construction of the example, how to name the files, and other conventions that examples should follow.

• QUIP-13 Qt Examples

Additionally, here are wiki pages that clarify or extend the official QUIP, by giving tips and hints for examples and its documentation.

• Writing Example Documentation and Tutorials - writing example documentation and tutorials
• Contributing Examples to Qt - configuring QDoc and submitting examples to Qt repositories
• Qt Examples in Qt Creator - how to ensure the example shows up in Qt Creator

File Names

The examples are as modularized as Qt itself. Each submodule can have a examples directory containing examples. Examples within a submodule are organized in a directory hierarchy, e.g. qtbase/examples/itemviews/dirview or qtbase/examples/widgets/tetrix. The hierarchy is there only to group related examples together. The examples should have unique names even if the hierarchy didn't exist. All examples should be at the same depth in the hierarchy.

The example's .pro file should have the same name as the directory it's in (e.g. tetrix.pro for widgets/tetrix). The example name should only contain lowercase letters and digits, no hyphens, no underscores.

In general, each class should be defined in its own header file and implemented in a corresponding .cpp file, e.g. MainWindow in mainwindow.h and mainwindow.cpp. Try to avoid defining more than one class per header file, since it confuses Java people and it's usually unnecessary, unless you have lots of small classes (e.g. an undo/redo framework, with one class per type of action).

Local classes may be defined in a .cpp file. Do not use the #include "foo.moc" trick in an example. (Don't worry if you don't understand what I'm talking about.)

Always put your main() function in a separate file called main.cpp, and try to keep it as simple as possible. Most users have understood that main() is usually boring and seldom take the time to read it. It's therefore not the place to do unusual stuff.

• Exception: If your example is very simple and requires only one file containing a main() function and (hopefully) a few other functions, call this file the same as your example (e.g. tetrix.cpp), not main.cpp.

If you need images or other resources, use the resource mechanism. Call the resource file the same thing as the example, but with the .qrc extension (e.g. tetrix.qrc). See the mainwindows/application example for an example of how to do this right.

Include Files and Forward Declarations

Order the #include declaration alphabetically:

#include <QApplication>
#include <QComboBox>
#include <QStringList>

In your .h files, try to include as few headers as possible, using forward declarations when feasible in alphabetical order. Unless the example is meant to be a very simple one, appealing to a novice programmer, make your the example "Qt namespace aware" by wrapping the declarations of Qt classes in QT_BEGIN_NAMESPACE/QT_END_NAMESPACE:

#include <QDialog>

class MyClass;
class YourClass;

QT_BEGIN_NAMESPACE
class QCheckBox;
class QLineEdit;
class QPushButton;
QT_END_NAMESPACE

Best practice is to avoid "module includes", such as #include <QtGui>, and use individual #include <QClass> preprocessor directives instead. However, as the module includes reduces visual clutter you may use the <QtGui>, <QtXml>, etc., headers.

If you need standard C++ headers, use the new style of headers (e.g. <iostream>) and put a using namespace std; after all the includes in .cpp files. Never use using directives in global namespace in header files.

• Exception: For C headers, check whether you have use the .h name (<math.h>, not <cmath>) because the new name isn't supported by all compilers

Note: Right now, some recommendations are different from Qt/Qt Creator Coding style, see https://doc-snapshots.qt.io/qtcreator-extending/coding-style.html