Doc: Update information about XML-based wizard templates

The example wizard templates have been removed. None of the
remaining XML-based wizards use generator scripts (and those
are not recommended for new projects), so information about
genereator scripts was removed.

Change-Id: Ie84fad6a5acb39e9718358bd0b14a5caca454201
Reviewed-by: Tobias Hunger's avatarTobias Hunger <>
parent 6cb2d8d3
......@@ -41,29 +41,16 @@
{JSON-Based wizards} instead. XML wizards are deprecated and support for
them will be removed in future versions of \QC.
To display the XML-based example wizards in \QC, rename
\c {wizard_sample.xml} as \c {wizard.xml} in the
\c {\share\qtcreator\templates\wizards\helloworld} and
\c {\share\qtcreator\templates\wizards\listmodel} folders. After
you restart \QC, the \uicontrol {Custom Classes}
and \uicontrol {Custom Projects} categories (1) appear in the \uicontrol New
dialog. For each category, an icon (2), a display name (3), and a
description (4) are displayed.
\image qtcreator-custom-project-wizards.png "The New dialog with custom projects and classes"
Files can be generated by using either \l{Processing Template Files}
{templates} or \l{Using Generator Scripts}{generator scripts}, where a
script is called to create the files.
\note The generator 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.
To see examples of XML-based wizards, select \uicontrol File >
\uicontrol {New File or Project} > \uicontrol Library. For each wizard, an
icon (1), a display name (2), and a description (3) are displayed.
\image qtcreator-custom-project-wizards.png "The New dialog"
Files can be generated by using \l{Processing Template Files}{templates}.
XML-based wizard template directories contain an XML configuration file
called wizard.xml, the template source files, and optionally, the generator
called wizard.xml and the template source files.
\section1 Creating XML-Based Project Wizards
......@@ -71,10 +58,11 @@
\list 1
\li Make a copy of the \c {share/qtcreator/templates/wizards/helloworld}
or \c {share/qtcreator/templates/wizards/listmodel} folder.
\li Make a copy of a folder in the \c share/qtcreator/templates/wizards/
folder that contains an XML-based wizard (\c codesnippet,
\c qtcreatorplugin, or \c qtquick2-extension).
\li Modify the wizard_example.xml file.
\li Modify the wizard.xml file.
\li The following code determines the type of the wizard and its place
in the \uicontrol New dialog:
......@@ -89,8 +77,7 @@
\li \c version is the version of the file contents. Do not modify
this value.
\li \c version is the version of the file contents.
\li \c kind specifies the type of the wizard: \c project or
\c class.
......@@ -146,12 +133,7 @@
\li Files to be added to the project:
\li Template-based: The following code specifies the files to add to
the project:
\li The following code specifies the files to add to the project:
<file source="main.cpp" openeditor="true" />
......@@ -183,41 +165,6 @@
See also \l{Processing Template Files}.
\li Generator-script: The following code specifies that the script
\c is to be used to create the files:
<generatorscript binary="">
<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"/>
In each argument, the field placeholders are replaced by the
field values. There are additional boolean attributes which give
fine-grained control:
\li \c omit-empty specifies that complete argument is to be
omitted when all placeholders expand to empty values. In
the above example, the option \c --source-suffix will
not be passed to the script if the value is empty.
\li \c write-file indicates that instead of the expanded
value, the value will be written to a temporary file and
its file name will be passed to the script instead. This
is useful for multi-line text fields.
See also \l{Using Generator Scripts}.
\li The following code creates a page that specifies settings for the project:
......@@ -600,50 +547,4 @@
of the base class. If the validation fails, a red label displaying the
message appears at the bottom of the wizard page.
\section1 Using Generator Scripts
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 \c{--dry-run} command line option.
\QC 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:
\list 1
\li Determine file names and attributes: The script is called with the
command line \c{--dry-run} option and the field values. It then prints
the relative path names of the files it intends to create, followed by
comma-separated attributes matching those of the \c{<file>} element, for
\li Create files: The script is called with the parameters only in the
working directory. It then actually creates the files. If directories
are needed, the script should create them, too.
The \c{scriptgeneratedproject} sample wizard illustrates the usage.
A typical script invocation for this example (obtained by running \QC with
\c{--customwizard-verbose}) looks as follows:
\code --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
\c %TargetPath%. This can be overridden by specifying the attribute
\c workingdirectory on the element \c generatorscript. For example, if the
script creates the project directory by itself, %Path% can be specified. In
that case, \c --dry-run should output the correct relative paths or absolute
paths constructed using the value of \c %Path%.
Markdown is supported
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment