Qt Examples in Qt Creator

Qt Creator features a list of examples and tutorials in its Welcome mode. If you wonder how to add examples here, or debug why examples & tutorials do not show up, read on.

Hint: The implementation for most of this can be found in the Qt Creator source code in src/plugins/qtsupport/examplelistmodel.cpp

Hint: Set the QTC_DEBUG_EXAMPLESMODEL environment variable to some value to get some useful debug output about what happens. This will also show examples in Qt Creator's example browser which normally would be hidden because Qt Creator thinks they are invalid (for testing purposes).

The process that Qt Creator uses to load examples & demos can be split into two phases:

1. Searching for possible example sources and putting an entry for them into the combo box on the example browser page
2. Parsing the example source that is selected in the combo box, verifying each example's settings for sanity, and showing them in the browser

Sources

$QTCREATORDIR/share/qtcreator/welcomescreen/qtcreator_tutorials.xml

These are the built-in tutorials that ship with Qt Creator, and are shown on the tutorials tab of the welcome page.

Help/InstalledExamples (QtCreator.ini)

Qt Creator reads a string list from the the key "Help/InstalledExamples" in its settings. Each string is expected to be a triple of strings separated by a "|" character. The triples are interpreted as display name, documentation path (where to look for the manifest files), and examples path, in that order. These are handled similar to a Qt version with the given display name, documentation path and examples path, and shown in the combo box on the examples page, in addition to the ones from the Qt versions. Qt versions that have the same documentation path as one of the example sets from the setting are hidden.

Examples from registered Qt Versions

Qt Creator shows an entry for each registered Qt version with an existing documentation and example path in the combo box on the examples page.

Qt Creator looks up 'examples-manifest.xml' and 'demos-manifest.xml' files from subdirectories of the Qt doc directory (the one qmake -query QT_INSTALL_DOCS returns).

An example: If qmake -query QT_INSTALL_DOCS returns D:.2.1\mingw48_32\doc Qt Creator will try to look up example-manifest.xml , demos-manifest.xml files in every subdirectory of 'doc'.

The relative paths in the manifest.xml files are resolved relative to the Qt version's examples path (qmake -query QT_INSTALL_EXAMPLES) and demos path (qmake -query QT_INSTALL_DEMOS).

Validity checks

After retrieving example & demo entries from the .xml files, it validates whether an entry should be shown or not:

Check whether projectPath is valid

If the path in the projectPath attribute is relative it is resolved:

1. relative to the directory the XML file is in
2. inside the examples/demos directory

If the project cannot be found there, the example/demo is skipped.

Check whether imageUrl is valid

Checks whether the imageUrl attribute contains a valid URL.

Check whether docUrl is valid

Checks whether the docUrl attribute contains a valid URL

examples-manifest.xml:

These files are generated by qdoc. For example, in Qt each module has a .qdocconf which pulls in .qdoc files for the examples, which contain the documentation for the example and the meta-information for the examples-manifest file for that module.

• the .qdocconf contains a examplesinstallpath variable, which is used as a prefix for all example paths
• the example's .qdoc contains a tag with the path to the example

These two are concatenated to the relative path that ends up in the projectPath tag in the manifest file.

For example, in Qt src/widgets/doc/qtwidgets.qdocconf there is "examplesinstallpath = widgets", and in examples/widgets/doc/src/wiggly.qdoc there is "widgets/wiggly", which results in "widgets/widgets/wiggly/wiggly.pro" as the projectPath (which is later resolved relative to QT_INSTALL_EXAMPLES).

See also QDocExamples for more details.

XML file format

<examples> section

The <examples> section can contain any number of <example> elements. Here is a typical example of an element:

<example name="Mandelbrot Example" docUrl="qthelp://org.qt-project.qtcore.521/qtcore/qtcore-mandelbrot-example.html" projectPath="core/mandelbrot/mandelbrot.pro" imageUrl="qthelp://org.qt-project.qtcore.521/qtcore/images/mandelbrot-example.png">
 <description><![CDATA[The Mandelbrot example demonstrates multi-thread programming using Qt. It shows how to use a worker thread to perform heavy computations without blocking the main thread's event loop.]]></description>
 <tags>mandelbrot,ios,core</tags>
 <fileToOpen>core/mandelbrot/main.cpp</fileToOpen>
</example>

• name=: The name of the example. Mandatory.
• docUrl=: absolute URL to documentation of the example. Mandatory.
• imageUrl=: image to display for example. Mandatory.
• projectPath=: relative path to project file for example. Mandatory.
• isHighlighted=: boolean argument whether example should be highlighted.
• <description>: Free text describing the example. Mandatory.
• <dependency>: No idea
• <platforms>: No idea
• <tags>: List of tags that allows filtering for examples
• <fileToOpen>: relative path to main file to open.

Example categories and highlights

Examples can be split into different categories. This is enabled for Qt versions 6.5.1 and later. Each example can list categories to appear in via its meta data. The order of categories in the examples view must be defined in one of the manifest files belonging to the same Qt version or set. If none is found, a default list of known categories is used. All unknown categories are ordered alphabetically after all known categories. Within each category, all examples with the isHighlighted tag set to true are shown first, otherwise examples are ordered alphabetically.

<instructionals ...>
    <example isHighlighted="true" ...>
        ...
        <meta>
            <entry name="category">Mobile</entry>
            <entry name="category">Application Examples</entry>
        </meta>
    </example>
    ...
    <categories>
        <category>Application Examples</category>
        <category>Desktop</category>
        <category>Mobile</category>
        ...
    </categories>
</instructionals>