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 classes.
You can copy the wizard templates in the template folders to create your own project and class wizards. They are displayed in the New dialog that opens when you choose File > New File or Project.
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.
In a class wizard, you can allow developers to specify the class name, base class, and header and source files for the class.
To see how this works, rename wizard_sample.xml as wizard.xml in the \share\qtcreator\templates\wizards\helloworld and \share\qtcreator\templates\wizards\listmodel folders. After you restart Qt Creator, the Custom Classes and Custom Projects categories (1) appear in the New dialog. For each category, an icon (2), a display name (3), and a description (4) are displayed.
A custom wizard defines the user interface of a wizard page. 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. File creation can happen in the following ways:
Note: This option mainly exists to accommodate existing generator scripts or cases where complicated algorithmic logic is required when generating files. Writing cross-platform scripts is inherently difficult, and therefore, it is not recommended for new wizards. For more information, see Using Generator Scripts.
Custom wizards are located in subdirectories of the following directories:
They contain an XML configuration file called wizard.xml, the template source files, and optionally, the generator script.
To create a project wizard:
<wizard version="1" kind="project" class="qt4project" firstpage="10" id="A.HelloWorld" category="B.CustomProjects">
<icon>console.png</icon> <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>
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".
<files> <file source="main.cpp" openeditor="true" /> <file source="project.pro" target="%ProjectName%.pro" openproject="true" /> <file source="icon.png" target="%ProjectName%.png" binary="true" />
See also Processing Template Files.
<generatorscript binary="generate.pl"> <argument value="--class-name=%ClassName%"/> <argument value="--project-name=%ProjectName%"/> <argument value="--header-suffix=%CppHeaderSuffix%" omit-empty="true"/> <argument value="--source-suffix=%CppSourceSuffix%" omit-empty="true"/> <argument value="--description=%Description%" omit-empty="true" write-file="true"/> </generatorscript>
In each argument, the field placeholders are replaced by the field values. There are additional boolean attributes which give fine-grained control:
See also Using Generator Scripts.
<!-- Create a 2nd wizard page with parameters --> <fieldpagetitle>Hello World Parameters</fieldpagetitle> <fieldpagetitle xml:lang="de">Hallo Welt Parameter</fieldpagetitle> <fields> <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> </field> </fields>
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:
<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 Project Wizards.
<files> <file source="listmodel.cpp" target="%ClassName:l%.%CppSourceSuffix%" openeditor="true" /> <file source="listmodel.h" target="%ClassName:l%.%CppHeaderSuffix%" openeditor="true" /> </files>
Here, target contains the following variables that are used to construct the filename:
<!-- Create parameter wizard page --> <fieldpagetitle>ListModel parameters</fieldpagetitle> <fieldpagetitle xml:lang="de">Parameter des ListModel</fieldpagetitle> <fields> <field name="ClassName"> <fieldcontrol class="QLineEdit" validator="^[a-zA-Z0-9_]+$" defaulttext="MyListModel" /> <fielddescription>Class name:</fielddescription> <fielddescription xml:lang="de">Klassenname:</fielddescription> </field> <field name="Datatype"> <fieldcontrol class="QComboBox" defaultindex="0"> <comboentries> <comboentry value="QString"> <comboentrytext>class QString</comboentrytext> <comboentrytext xml:lang="de">Klasse QString</comboentrytext> </comboentry> <comboentry value="int"> <comboentrytext>Integer</comboentrytext> <comboentrytext xml:lang="de">Ganzzahlwert</comboentrytext> </comboentry> </comboentries> </fieldcontrol> <fielddescription>Data type:</fielddescription> <fielddescription xml:lang="de">Datentyp:</fielddescription> </field> </fields>
In addition to QLineEdit, QComboBox is used in the class wizard to create a field. Specify the following XML attributes:
You can use the following interface objects to create fields in the wizards:
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.
<field mandatory="true" name="QtCreatorSources"> <fieldcontrol class="Utils::PathChooser" defaulttext="" expectedkind="existingdirectory"/> <fielddescription>Qt Creator sources:</fielddescription> </field>
The defaulttext attribute specifies text that appears in the field by default.
The text attribute expectedkind specifies which type of path is expected:
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> </field>
For more examples about using check boxes, see Processing Template Files.
<field name="License"> <fieldcontrol class="QTextEdit" defaulttext="Put your license text here" /> <fielddescription>License:</fielddescription> </field>
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.
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:
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> </field>
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 @endif
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> </field>
In addition to the field values entered by the user, you can use the following pre-defined standard values:
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:
<validationrules> <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> </validationrule> </validationrules>
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.
The values entered in the wizard page are passed to the script as command line arguments as defined by the wizard configuration file.
In addition, the script must implement a --dry-run command line option.
Qt Creator needs to know the file names before the files are created to check whether files with identical names already exist, for example. Therefore, script file generation is a two-step process:
myclass.cpp,openeditor myclass.h,openeditor myproject.pro,openproject
The scriptgeneratedproject sample wizard illustrates the usage. A typical script invocation for this example (obtained by running Qt Creator with --customwizard-verbose) looks as follows:
generate.pl --class-name=TestClass --project-name=TestProject --header-suffix=h --source-suffix=cpp --description=/tmp/qtcreatorj26629.txt
By default, the scripts are run in the directory corresponding to %TargetPath%. This can be overridden by specifying the attribute workingdirectory on the element generatorscript. For example, if the script creates the project directory by itself, %Path% can be specified. In that case, --dry-run should output the correct relative paths or absolute paths constructed using the value of %Path%.