The JSON-based wizards are displayed in the New dialog. To customize them, copy a directory that contains a wizard.json file in share/qtcreator/templates/wizards/ and modify it to fit your needs. After you run qmake and restart Qt Creator, the wizard name appears in the selected or added category. For each wizard, an icon, a display name, and a description are displayed.

JSON-based wizard template directories contain a JSON configuration file called wizard.json and the template files. The configuration file contains sections that specify information about the wizard, variables that you can use, wizard pages, and generators for creating files.

Using Variables in Wizards

You can use variables (%{<variableName>}) in the configuration and template source files. A set of variables is predefined by the wizards and their pages. You can introduce new variables as shortcuts to be used later. Define the variable key names and values in the options section in the .json file.

The variables always return strings. In places where a boolean value is expected and a string is given, an empty string is treated as false and anything else as true. A common pitfall is that a string containing "false" is not empty and is therefore treated as the value true when converted to a boolean value. To avoid this pitfall, use the following type of construction:

{"condition": "%{JS: ('%{VersionControl}' === 'G.Git') ? 'yes' : ''}"

Localizing Wizards

If a setting name starts with the tr prefix, the value is visible to users and should be translated. If the new wizard is included in the Qt Creator sources, the translatable strings appear in the Qt Creator translation files and can be translated as a part of Qt Creator. Alternatively, you can place the translations in the .json file using the following syntax:

"trDisplayName": { "C": "default", "en_US": "english", "de_DE": "deutsch" }

For example:

"trDisplayName": { "C": "Project Location", "en_US": "Project Location", "de_DE": "Projekt Verzeichnis" }

Creating Wizards

Qt Creator contains wizards for adding classes, files, and projects. You can use them as basis for adding your own wizards. We use the C++ wizard to explain the process and the sections and settings in the .json file.

For more information about the pages and widgets that you can add, see Available Pages and Available Widgets.

To create a JSON-based C++ class wizard:

1. Make a copy of share/qtcreator/templates/wizards/classes/cpp and rename it.
2. Right-click the project name in Projects and select Run qmake to register the new wizard. Basically, qmake generates a fixed list of files to copy. Therefore, you need to run qmake each time the names or locations of the files change.
3. Open the wizard configuration file, wizard.json for editing:
   • The following settings determine the type of the wizard and its place in the New dialog:

                     "version": 1,
                     "kind": "class",
                     "id": "A.Class",
                     "category": "O.C++",

     • version is the version of the file contents. Do not modify this value.
     • kind specifies the type of the wizard: class, file, or project.
     • id is the unique identifier for your wizard. You can use a leading letter to specify the position of the wizard within the category.
     • category is the category in which to place the wizard in the list. You can use a leading letter to specify the position of the category in the list in the New dialog.
     • disabled is set to to true to hide the wizard. By default, it is set to false.
   • The following settings specify the icon and text that appear in the New dialog:

                 "trDescription": "Creates a C++ header and a source file for a new class that you can add to a C++ project.",
                 "trDisplayName": "C++ Class",
                 "trDisplayCategory": "C++",
                 "icon": "../../global/genericfilewizard.png",
                 "featuresRequired": [ "Plugin.CppEditor" ],

     • trDescription appears in the right-most panel when trDisplayCategory is selected.
     • trDisplayName appears in the middle panel when trDisplayCategory is selected.
     • trDisplayCategory appears in the New dialog, under Projects.
     • icon appears next to the trDisplayName in the middle panel when trDisplayCategory is selected. We recommend that you specify the path relative to the wizard.json file, but you can also use an absolute path.
     • featuresRequired specifies the Qt Creator features that the wizard depends on. If a required feature is missing, the wizard is hidden. For example, if the CppEditor plugin is disabled, the C++ Class wizard is hidden.
     • featuresPreferred specifies the build and run kits to preselect.
     • platformIndependent is set to true if the wizard is supported by all target platforms. By default, it is set to false.
   • The options section contains an array of objects with key and value attributes. You can define your own variables to use in the configuration and template source files, in addition to the predefined variables. For example, the following variables are used in the C++ class creation wizard:

                 "options":
                 [
                     { "key": "TargetPath", "value": "%{Path}" },
                     { "key": "HdrPath", "value": "%{Path}/%{HdrFileName}" },
                     { "key": "SrcPath", "value": "%{Path}/%{SrcFileName}" },
                     { "key": "CN", "value": "%{JS: Cpp.className('%{Class}')}" },
                     { "key": "Base", "value": "%{JS: ( '%{BaseCB}' === '' ) ? '%{BaseEdit}' : '%{BaseCB}'}" },
                     { "key": "isQObject", "value": "%{JS: ('%{Base}' === 'QObject' || '%{Base}' === 'QWidget' || '%{Base}' === 'QMainWindow' || '%{Base}' === 'QDeclarativeItem' || '%{Base}' === 'QQuickItem' ) ? 'yes' : ''}" },
                     { "key": "GUARD", "value": "%{JS: Cpp.classToHeaderGuard('%{Class}', '%{JS: Util.preferredSuffix('text/x-c++hdr')}')}" },
                     { "key": "SharedDataInit", "value": "%{JS: ('%{IncludeQSharedData}') ? 'data(new %{CN}Data)' : '' }" }
                 ],

     This section is optional. For more examples of variables, see the wizard.json files for other wizards.

   • The pages section specifies the wizard pages. The pages used depend on the wizard type. You can add standard pages to wizards or create new pages using the available widgets. The following settings specify the display name, title, and type of the page:

                 "pages":
                 [
                     {
                         "trDisplayName": "Define Class",
                         "trShortTitle": "Details",
                         "typeId": "Fields",
                 "data" :
                 [
                     {
                         "name": "Class",
                         "trDisplayName": "Class name:",
                         "mandatory": true,
                         "type": "LineEdit",
                         "data": { "validator": "(?:(?:[a-zA-Z_][a-zA-Z_0-9]*::)+[a-zA-Z_][a-zA-Z_0-9]*|)" }
                     },
                     ...
                 ]

     • typeId specifies the page to use: Fields, File, Form, Kits, Project, or Summary. Full page ID, as used in the code, consists of the typeId prefixed with "PE.Wizard.Page.". For more information, about the pages, see Available Pages.
     • trDisplayName specifies the title of the page. By default, the page title is used.
     • trShortTitle specifies the title used in the sidebar of the Wizard. By default, the page title is used.
     • trSubTitle specifies the subtitle of the page. By default, the page title is used.
     • index is an integer value that specifies the page ID. It is automatically assigned if you do not set it.
     • enabled is set to true to show the page and to false to hide it.
     • data specifies the wizard pages. In the C++ wizard, it specifies a Fields page and a Summary page. The Fields page contains the CheckBox, ComboBox, LineEdit, PathChooser, and Spacer widgets. For more information about the widgets, see Available Widgets.
   • The generators section specifies the files to be added to the project:

                 "generators":
                 [
                     {
                         "typeId": "File",
                         "data":
                         [
                             {
                                 "source": "file.h",
                                 "target": "%{HdrPath}",
                                 "openInEditor": true
                             },
                             {
                                 "source": "file.cpp",
                                 "target": "%{SrcPath}",
                                 "openInEditor": true
                             }
                 ]

     • typeId specifies the type of the generator. Currently, only File is supported.
     • data spefices the files to generate. For a each file to be generated, specify the following values:
       • source specifies the path and filename of the template file relative to the wizard.json file.
       • target specifies the location of the generated file, either absolute or relative to %{TargetPath}, which is usually set by one of the wizard pages.
       • openInEditor opens the file in the appropriate editor if it is set to true.
       • openAsProject opens the project file in Qt Creator if it is set to true.
       • condition generates the file if the condition returns true. For more information, see Using Variables in Wizards.

Available Pages

You can add predefined pages to wizards by specifying them in the pages section of a wizard.json file.

Field Page

A Field page has the typeId value Field and contains widgets. For more information about widget definitions, see Available Widgets.

"pages":
[
    {
        "trDisplayName": "Define Class",
        "trShortTitle": "Details",
        "typeId": "Fields",
        "data" :
        [
            {
                "name": "Class",
                "trDisplayName": "Class name:",
                "mandatory": true,
                "type": "LineEdit",
                "data": { "validator": "(?:(?:[a-zA-Z_][a-zA-Z_0-9]*::)+[a-zA-Z_][a-zA-Z_0-9]*|)" }
            },
            ...
],

File Page

A File page has the typeId value File. You can leave out the data key or assign an empty object to it.

{
    "trDisplayName": "Location",
    "trShortTitle": "Location",
    "typeId": "File"
},

The page evaluates InitialFileName and InitialPath from the wizard to set the initial path and filename. The page sets TargetPath to the full path of the file to be created.

Form Page

A Form page has the typeId value Form. You can leave out the data key or assign an empty object to it.

{
    "trDisplayName": "Choose a Form Template",
    "trShortTitle": "Form Template",
    "typeId": "Form"
},

The page sets FormContents to an array of strings with the form contents.

Kits

A Kits page has the typeId value Kits. The data section of a Kits page contains an object with the field projectFilePath set.

{
    "trDisplayName": "Kit Selection",
    "trShortTitle": "Kits",
    "typeId": "Kits",
    "enabled": "%{IsTopLevelProject}",
    "data": { "projectFilePath": "%{ProFileName}" }
},

The page evaluates Platform to set the platform selected in File > New, PreferredFeatures to set the preferred features for the project, and RequiredFeatures to set the required features for the project. The feature set is used to determine which kits to display and pre-select for the project.

Project

A Project page has the typeId value Project. It contains no data or an empty object.

{
    "trDisplayName": "Project Location",
    "trShortTitle": "Location",
    "typeId": "Project"
},

The page evaluates InitialPath to set the initial project path. The page sets ProjectDirectory and TargetPath to the project directory.

Summary

A Summary page has the typeId value Summary. It contains no data or an empty object.

{
    "trDisplayName": "Project Management",
    "trShortTitle": "Summary",
    "typeId": "Summary"
}

The page sets IsSubproject to an empty string if this is a toplevel project and to yes otherwise. It sets VersionControl to the ID of the version control system in use.

Available Widgets

You can add the following widgets on a Field page:

• Check Box
• Combo Box
• Label
• Line Edit
• Path Chooser
• Spacer
• Text Edit

Specify the following settings for each widget:

• name specifies the widget name. This name is used as the variable name to access the value again.
• trDisplayName specifies the label text visible in the UI (if span is not true).
• type specifies the type of the widget: CheckBox, ComboBox, Label, LineEdit, PathChooser, Spacer, and TextEdit.
• data specifies settings for the widget:
  • visible is set to true if the widget is visible, otherwise it is set to false. By default, it is set to true.
  • enabled is set to true if the widget is enabled, otherwise it is set to false. By default, it is set to true.
  • mandatory is set to true if this widget must have a value for the Next button to become enabled. By default, it is set to true.
  • span is set to hide the label and to span the form. By default, it is set to false. For more information, see Using Variables in Wizards.

  The additional settings available for a particular widget are described in the following sections.

Check Box

{
    "name": "IncludeQObject",
    "trDisplayName": "Include QObject",
    "type": "CheckBox",
    "data":
    {
        "checkedValue": "QObject",
        "uncheckedValue": "",
        "checked": "%{JS: ('%{BaseCB}' === 'QObject' ) ? 'yes' : ''}"
    }
},

• checkedValue specifies the value to set when the check box is enabled. By default, set to 0.
• uncheckedValue specifies the value to set when the check box is disabled. By default, set to 1.
• checked is set to true if the check box is enabled, otherwise false.

Combo Box

{
    "name": "BaseCB",
    "trDisplayName": "Base class:",
    "type": "ComboBox",
    "data":
    {
        "items": [ { "trKey": "<Custom>", "value": "" },
                   "QObject", "QWidget", "QMainWindow", "QDeclarativeItem", "QQuickItem" ]
    }
},

• items specifies a list of items to put into the combo box. The list can contain both JSON objects and plain strings. For JSON objects, define trKey and value pairs, where the trKey is the list item visible to users and value contains the data associated with the item.
• index specifies the index to select when the combo box is enabled. By default, it is set to 0.
• disabledIndex specifies the index to show if the combo box is disabled.

Label

{
"name": "LabelQQC_1_0",
    "type": "Label",
    "span": true,
    "visible": "%{( '%{CS}' === 'QQC_1_0' ) ? 'yes' : ''}",
    "data":
    {
        "wordWrap": true,
        "trText": "Creates a deployable Qt Quick 2 application using Qt Quick Controls. Requires Qt 5.1 or newer."
    }
},

• wordWrap is set to true to enable word wrap. By default, it is set to false.
• trText contains the label text to display.

Line Edit

{
    "name": "Class",
    "trDisplayName": "Class name:",
    "mandatory": true,
    "type": "LineEdit",
    "data": { "validator": "(?:(?:[a-zA-Z_][a-zA-Z_0-9]*::)+[a-zA-Z_][a-zA-Z_0-9]*|)" }
},
{
    "name": "BaseEdit",
    "type": "LineEdit",
    "enabled": "%{JS: ( '%{BaseCB}' === '' ) ? 'yes' : ''}",
    "mandatory": false,
    "data":
    {
        "trText": "%{BaseCB}",
        "trDisabledText": "%{BaseCB}"
    }
},

• trText specifies the default text to display.
• trDisabledText specifies the text to display in a disabled field.
• trPlaceholder specifies the placeholder text.
• validator specifies a QRegularExpression to validate the line edit against.
• fixup specifies a variable that is used to fix up the string. For example, to turn the first character in the line edit to upper case.

Path Chooser

{
    "name": "Path",
    "type": "PathChooser",
    "trDisplayName": "Path:",
    "mandatory": true,
    "data":
    {
        "kind": "existingDirectory",
        "basePath": "%{InitialPath}",
        "path": "%{InitialPath}"
    }
},

• path specifies the selected path.
• basePath specifies a base path that lookups are relative to.
• kind defines what to look for: existingDirectory, directory, file, saveFile, existingCommand, command, or any.

Spacer

{
    "name": "Sp1",
    "type": "Spacer",
    "data":
    {
        "factor": 2
    }
},

The factor setting specifies the factor (an integer) to multiply the layout spacing for this spacer.

Text Edit

{
    "name": "TextField",
    "type": "TextEdit",
    "data" :
    {
        "trText": "This is some text",
        "richText": true
    }
}

• trText specifies the text to display.
• trDisabledText specifies the text to display when the text edit is disabled.
• richText is set to true for rich text, otherwise false.