Qt Documentation

Qt Creator Manual
Adding New Custom Wizards
Qt Creator Manual 4.2.0

Adding Libraries to Projects Adding JSON-Based Wizards

Adding New Custom Wizards

If you have a team working on a large application or several applications, you might want to standardize the way the team members create projects and files.

You can copy the wizard templates in the template folders to create your own project and file wizards. They are displayed in the New dialog that opens when you choose File > New File or Project.

A custom wizard defines the user interface of a set of wizard pages. The values the user enters in the wizard are assigned field names. Field name and value pairs are then passed to the file creation process.

Wizard Types

In a project wizard, you can specify the files needed in a project. You can add wizard pages to allow developers to specify settings for the project.

A file wizard is similar, but does not contain any project file.

You are encouraged to create JSON-based wizards. They provide a super-set of the functionality available in the XML based wizards used before. For more information, see:

Adding JSON-Based Wizards
Adding XML-Based Wizards (deprecated)

Locating Wizards

Wizards are located in subdirectories of the following directories:

share/qtcreator/templates/wizards
the local user's configuration folder, $HOME/.config/QtProject/qtcreator/templates/wizards on Linux and macOS or %APPDATA%\QtProject\qtcreator\templates\wizards on Windows

Tips for Wizard Development

Qt Creator has some actions that can improve the wizard development process. These are by default not bound to any keyboard shortcuts and can thus not be triggered. To enable them, assign keyboard shortcuts in Tools > Options > Environment > Keyboard > Wizard.

The following actions can help with wizard development:

Action Id	Description
Inspect	Triggering this action opens a window that lists all the defined fields and variables in the wizard at the time the action was triggered. Each activation of this action opens a new non-modal window, so you can compare state at different pages of the wizard for example.
Factory.Reset	Triggering this action makes Qt Creator forget all wizard factories, causing it to reload all wizard definitions when for example opening File > New File or Project. This way you can avoid having to restart Qt Creator for your changes to a wizard definition to become visible.

Verbose Output

When developing custom wizards (both JSON as well as XML based), it is recommended to start Qt Creator with the -customwizard-verbose argument. It causes each correctly set up wizard to produce output along the following lines:

Checking "/home/jsmith/.config/QtProject/qtcreator/templates/wizards/mywizard"
for wizard.json.
* Configuration found and parsed.

The output includes the name of the directory that was checked for a wizard.json file. If the file is not found, the message is not displayed.

If the file contains errors, such as an invalid icon path, the following types of messages are displayed:

Checking "/home/jsmith/.config/QtProject/qtcreator/templates/wizards/mywizard"
for wizard.json.
* Configuration found and parsed.
* Failed to create: Icon file
"/home/jsmith/.config/QtProject/qtcreator/templates/wizards/mywizard/../..
/global/genericfilewizard.png" not found.

See Using Command Line Options for more information about command line arguments.