Adding XML-Based Wizards

Note: We recommend that you create JSON-Based wizards instead. XML wizards are deprecated and support for them will be removed in future versions of Qt Creator.

To see examples of XML-based wizards, select File > New File or Project > Library. For each wizard, an icon (1), a display name (2), and a description (3) are displayed.

"The New dialog"

Files can be generated by using templates.

XML-based wizard template directories contain an XML configuration file called wizard.xml and the template source files.

Creating XML-Based Project Wizards

To create an XML-based project wizard:

  1. Make a copy of a folder in the share/qtcreator/templates/wizards/ folder that contains an XML-based wizard (codesnippet, qtcreatorplugin, or qtquick2-extension).
  2. Modify the wizard.xml file.
  3. The following code determines the type of the wizard and its place in the New dialog:
    <wizard version="1" kind="project"
    class="qmakeproject" firstpage="10"
    id="A.HelloWorld" category="B.CustomProjects">
    • version is the version of the file contents.
    • kind specifies the type of the wizard: project or class.
    • class specifies the type of the project. This attribute is optional. Use the value qmakeproject to add Qt specific pages.
    • firstpage specifies the place of the new page in the standard project wizard. The value 10 ensures that the custom page appears after the standard pages, as the last page of the wizard.
    • id is the unique identifier for your wizard. The letter specifies the position of the wizard within the category. The HelloWorld wizard appears as the first wizard in the second category in the New dialog.
    • category is the category in which to place the wizard in the list. The letter specifies the position of the category in the list in the New dialog.
  4. The following code specifies the icon and text that appear in the New dialog:
    <description>Creates a hello-world-project with custom message.</description>
    <description xml:lang="de">Erzeugt ein Hello-Welt-Projekt mit einer Nachricht.</description>
    <displayname>Hello World</displayname>;
    <displayname xml:lang="de">Hallo Welt</displayname>;
    <displaycategory>Custom Projects</displaycategory>
    <displaycategory xml:lang="de">Benutzerdefinierte Projekte</displaycategory>
    • displayCategory appears in the New dialog, under Projects.
    • icon appears next to the displayName in the middle panel when displayCategory is selected.
    • description appears in the right-most panel when displayCategory is selected.

      You can add translations as values for the text elements. Specify the target language as an attribute for the element. Use locale names (QLocale). For example, xml:lang="de".

  5. The following code specifies the files to add to the project:
        <file source="main.cpp" openeditor="true" />
        <file source="" target="" openproject="true" />
        <file source="icon.png" target="%ProjectName%.png" binary="true" />
    • source specifies the file to copy to the project. The files must be located in the wizard folder.
    • openeditor indicates that the file is to be opened in an editor after the wizard has finished.
    • binary indicates that the file is a binary file (for example, an image file). It is to be copied to the target folder as is. Placeholders are not replaced with values.
    • target specifies the new filename for the file. The %ProjectName% variable is replaced with the string that users specify in the Name field on the first page of the wizard.
    • openproject indicates that the file is a project file which is to be opened after the wizard has finished.

    See also Processing Template Files.

  6. The following code creates a page that specifies settings for the project:
    <!-- Create a 2nd wizard page with parameters -->
    <fieldpagetitle>Hello World Parameters</fieldpagetitle>
    <fieldpagetitle xml:lang="de">Hallo Welt Parameter</fieldpagetitle>
        <field mandatory="true" name="MESSAGE">
            <fieldcontrol class="QLineEdit" validator='^[^"]+$'  defaulttext="Hello world!" placeholdertext="Enter a message"/>
            <fielddescription>Hello world message:</fielddescription>
            <fielddescription xml:lang="de">Hallo-Welt-Nachricht:</fielddescription>
    • fieldpagetitle specifies the title of the page.
    • fields specifies the user interface objects on the page.
    • field specifies one object. You can use a set of interface objects from QtWidgets classes, derived from QWidget, to create fields. This example uses QLineEdit to create an input field. For more information about the objects that you can add, see Supported Widgets.
    • mandatory specifies whether the field is mandatory (true or false). For more information, see QWizardPage::registerField().
    • name specifies a name that you can use as a placeholder variable in the template file (for example, %MESSAGE%).
    • class specifies the type of the fieldcontrol. The XML attributes that you can specify for the field depend on the field type.
    • For a QLineEdit, validator specifies a regular expression to check the characters allowed in the field.
    • defaulttext specifies text that appears in the field by default.
    • For a QLineEdit, placeholdertext specifies placeholder text that appears in the field.
    • fielddescription specifies the field name that appears on the wizard page.

Creating Class Wizards

The wizard.xml file for a class wizard is very similar to that for a project wizard. The differences are discussed below.

To create a class wizard:

  1. The following code specifies settings for the wizard:
    <wizard version="1" kind="class" id="A.ListModel" category="B.CustomClasses">
       <description>Creates a QAbstractListModel implementation.</description>
       <description xml:lang="de">Erzeugt eine Implementierung von QAbstractListModel.</description>
       <displayname>QAbstractListModel implementation</displayname>
       <displayname xml:lang="de">Implementierung von QAbstractListModel</displayname>
       <displaycategory>Custom Classes</displaycategory>
       <displaycategory xml:lang="de">Benutzerdefinierte Klassen</displaycategory>

    For more information about the elements and their values, see Creating XML-Based Project Wizards.

  2. The following code specifies the files to add to the project:
        <file source="listmodel.cpp" target="%ClassName:l%.%CppSourceSuffix%"  openeditor="true" />
        <file source="listmodel.h" target="%ClassName:l%.%CppHeaderSuffix%"  openeditor="true" />

    Here, target contains the following variables that are used to construct the filename:

    • %ClassName:l% is replaced with the value of the ClassName field. The modifier l converts the string to lower case, to observe Qt conventions.
    • %CppSourceSuffix% and %CppHeaderSuffix% are pre-defined. For more information, see Pre-defined Standard Variables.
    <!-- Create parameter wizard page -->
    <fieldpagetitle>ListModel parameters</fieldpagetitle>
    <fieldpagetitle xml:lang="de">Parameter des ListModel</fieldpagetitle>
        <field name="ClassName">
            <fieldcontrol class="QLineEdit" validator="^[a-zA-Z0-9_]+$" defaulttext="MyListModel" />
            <fielddescription>Class name:</fielddescription>
            <fielddescription xml:lang="de">Klassenname:</fielddescription>
        <field name="Datatype">
            <fieldcontrol class="QComboBox" defaultindex="0">
                    <comboentry value="QString">
                        <comboentrytext>class QString</comboentrytext>
                        <comboentrytext xml:lang="de">Klasse QString</comboentrytext>
                <comboentry value="int">
                    <comboentrytext xml:lang="de">Ganzzahlwert</comboentrytext>
            <fielddescription>Data type:</fielddescription>
            <fielddescription xml:lang="de">Datentyp:</fielddescription>

    In addition to QLineEdit, QComboBox is used in the class wizard to create a field. Specify the following XML attributes:

    • defaultindex specifies which comboentry is displayed by default. In the above example, "0" means that the first comboentry is the default value.
    • comboentries specifies the options in the combobox.
    • value specifies the type of each comboentry, QString or integer.
    • comboentrytext specifies the text of the entry.

Supported Widgets

You can use the following interface objects to create fields in the wizards:

  • PathChooser utility to set paths
  • Check boxes with text labels (QCheckBox)
  • Combined button and popup lists (QComboBox)
  • One-line text editors (QLineEdit)
  • Multi-line rich text editors (QTextEdit)

Using QLineEdit and QComboBox is described in the previous sections. The following sections show examples of using the other classes and describe the XML attributes that you can specify for the fieldcontrol element of a field in a particular class.

Path Choosers

<field mandatory="true" name="QtCreatorSources">
    <fieldcontrol class="Utils::PathChooser" defaulttext="" expectedkind="existingdirectory"/>
        <fielddescription>Qt Creator sources:</fielddescription>

The defaulttext attribute specifies text that appears in the field by default.

The text attribute expectedkind specifies which type of path is expected:

  • any accepts any kind of path.
  • file expects a file.
  • directory expects a directory.
  • existingdirectory expects an existing directory.
  • command expects an executable file.
  • existingcommand expects an existing, executable file.

Check Boxes

To make check boxes appear selected by default, set the fieldcontrol attribute defaultvalue to true. Any other value or omitting the attribute makes the check box appear not selected.

For example:

<field name="CONSOLE">
    <fieldcontrol class="QCheckBox" defaultvalue="true"/>
    <fielddescription>Console application</fielddescription>

For more examples about using check boxes, see Processing Template Files.

Text Editors

<field name="License">
    <fieldcontrol class="QTextEdit" defaulttext="Put your license text here" />

The defaulttext attribute specifies text that appears in the field by default.

The boolean attribute acceptRichText sets the property QTextEdit::acceptRichText. It is disabled by default (as opposed to the default value of QTextEdit::acceptRichText) to prevent pasting of rich text with formatting, which is not desirable for code templates.

Processing Template Files

When processing a template source file, placeholders specifying the field names in the format %FIELDNAME% are replaced by the values entered by the user. In addition, modifier characters are supported. For example, %FIELDNAME:u% specifies that the value is converted to upper case. This enables generating header guards for C++ header files.

The following modifier characters are supported:

  • l for lower case.
  • u for upper case.
  • c for upper case initial letter ("project" > "Project").

In the helloworld example, the placeholder %NETWORK% is used together with the QCheckBox class. The following line is added to the project file:

%NETWORK%QT += network

And the following field is specified in the wizard.xml:

<field name="NETWORK">
    <fieldcontrol class="QCheckBox" truevalue="" falsevalue="# "/>
    <fielddescription>Include network module</fielddescription>
    <fielddescription xml:lang="de">Netzwerk-Modul verwenden</fielddescription>

If the checkbox is checked, the placeholder is replaced by truevalue. If it is not checked, the placeholder is replaced by falsevalue.

You can use conditions to add sections of the file depending on field values. Use a syntax that is similar to C++ preprocessing, as demonstrated in the project file of the helloworld example:

@if "%SCRIPT%" == "true"
QT += script

The value of the Boolean (QCheckBox) field labeled SCRIPT determines whether the script module is added. The expressions must expand to valid Javascript expressions after field replacement.

For example, the following field is specified in the wizard.xml:

<field name="SCRIPT">
    <fieldcontrol class="QCheckBox"/>
    <fielddescription>Include script module</fielddescription>
    <fielddescription xml:lang="de">Script-Modul verwenden</fielddescription>

Pre-defined Standard Variables

In addition to the field values entered by the user, you can use the following pre-defined standard values:

  • %ProjectName% is replaced by the name of the project in the case of project wizards.
  • %Path% is replaced by the path to the target directory. For classes, this is the directory, where the files are created. For project wizards, an additional subdirectory named after the project is created.
  • %TargetPath% is replaced by the path to the directory where the actual files are created. For non-project wizards, it is identical to %Path%. For project wizards, it is %Path%/%ProjectName%.
  • %CppSourceSuffix% is replaced by the default source suffix, which is defined in Qt Creator in Tools > Options > C++ > File Naming. For example, if users enter MyClass, the filename becomes myclass.cpp when the project is created.
  • %CppHeaderSuffix% is replaced by the default header suffix, which is also defined in File Naming.
  • %CurrentDate% is replaced by the current date in the format YYYY-MM-DD as specified by ISO 8601.
  • %CurrentTime% is replaced by the current time in the format HH:MM:SS as specified by ISO 8601.
  • %CurrentDate:Locale% is replaced by the current date in the short format specified by the application's locale.
  • %CurrentTime:Locale% is replaced by the current time in the short format specified by the application's locale.
  • %CurrentDate:ISO% is replaced by the current date in the format YYYY-MM-DD as specified by ISO 8601.
  • %CurrentTime:ISO% is replaced by the current time in the format HH:MM:SS as specified by ISO 8601.
  • %CurrentDate:RFC% is replaced by the current date in the format DD Mon YYYY, where Mon is the three letter month name, as specified by RFC 2822.
  • %CurrentTime:RFC% is replaced by the current time in the format HH:MM:SS as specified by RFC 2822.

Validating User Input

You can specify validation rules for user input. The rules consist of a Boolean JavaScript expression and an error message. The placeholders in them are replaced with values before they are evaluated or displayed.

Consider the following rule used in the Creating Class Wizards example:

    <validationrule condition='"%ClassName%" != "QAbstractListModel"'>
        <message>%ClassName% cannot be used as class name.</message>
        <message xml:lang="de">%ClassName% kann nicht als Klassenname verwendet werden.</message>

It ensures that the class name entered by the user does not match the name of the base class. If the validation fails, a red label displaying the message appears at the bottom of the wizard page.

© 2019 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.