forked from qt-creator/qt-creator
Doc: prepare for describing JSON-based wizards
Move XML-wizard specific information into a separate file. Change-Id: I7fe80c28747fa20d274eae7d3bf0b65f3624fd20 Reviewed-by: Alessandro Portale <alessandro.portale@digia.com>
This commit is contained in:
Leena Miettinen
committed by
Leena Miettinen
Leena Miettinen
parent
e1fbeedcd4
commit
36f8765596
@@ -24,7 +24,7 @@
|
||||
|
||||
/*!
|
||||
\contentspage {Qt Creator Manual}
|
||||
\previouspage creator-project-wizards.html
|
||||
\previouspage creator-project-wizards-xml.html
|
||||
\page creator-version-control.html
|
||||
\nextpage creator-configuring-projects.html
|
||||
|
||||
|
||||
663
doc/src/projects/creator-projects-custom-wizards-xml.qdoc
Normal file
663
doc/src/projects/creator-projects-custom-wizards-xml.qdoc
Normal file
@@ -0,0 +1,663 @@
|
||||
/****************************************************************************
|
||||
**
|
||||
** Copyright (c) 2014 Digia Plc and/or its subsidiary(-ies).
|
||||
** Contact: http://www.qt-project.org/legal
|
||||
**
|
||||
** This file is part of Qt Creator
|
||||
**
|
||||
**
|
||||
** GNU Free Documentation License
|
||||
**
|
||||
** Alternatively, this file may be used under the terms of the GNU Free
|
||||
** Documentation License version 1.3 as published by the Free Software
|
||||
** Foundation and appearing in the file included in the packaging of this
|
||||
** file.
|
||||
**
|
||||
**
|
||||
****************************************************************************/
|
||||
|
||||
// **********************************************************************
|
||||
// NOTE: the sections are not ordered by their logical order to avoid
|
||||
// reshuffling the file each time the index order changes (i.e., often).
|
||||
// Run the fixnavi.pl script to adjust the links to the index order.
|
||||
// **********************************************************************
|
||||
|
||||
/*!
|
||||
\contentspage {Qt Creator Manual}
|
||||
\previouspage creator-project-wizards.html
|
||||
\page creator-project-wizards-xml.html
|
||||
\nextpage creator-version-control.html
|
||||
|
||||
\title Adding XML-Based Wizards
|
||||
|
||||
To display the XML-based example wizards in \QC, rename wizard_sample.xml as wizard.xml in the
|
||||
\c {\share\qtcreator\templates\wizards\helloworld} and
|
||||
\c {\share\qtcreator\templates\wizards\listmodel} folders. After
|
||||
you restart \QC, the \gui {Custom Classes}
|
||||
and \gui {Custom Projects} categories (1) appear in the \gui 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"
|
||||
|
||||
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:
|
||||
|
||||
\list 1
|
||||
|
||||
\li Template-based, where source files that contain placeholders for
|
||||
the field names are provided. During processing, the placeholders
|
||||
are replaced by the values from the wizard page. Optionally,
|
||||
modifier characters are applied. For more information, see
|
||||
\l{Processing Template Files}.
|
||||
|
||||
\li Generator script, where a script is called to create the files.
|
||||
|
||||
\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 \l{Using Generator Scripts}.
|
||||
|
||||
\endlist
|
||||
|
||||
Custom wizards are located in subdirectories of the following directories:
|
||||
|
||||
\list
|
||||
|
||||
\li \c{share/qtcreator/templates/wizards}
|
||||
|
||||
\li the local user's configuration folder,
|
||||
\c{$HOME/.config/QtProject/qtcreator/templates/wizards}
|
||||
|
||||
\li \c{%APPDATA%\QtProject\qtcreator\templates\wizards}
|
||||
|
||||
\endlist
|
||||
|
||||
They contain an XML configuration file called wizard.xml, the template
|
||||
source files, and optionally, the generator script.
|
||||
|
||||
\section1 Creating Project Wizards
|
||||
|
||||
To create a project wizard:
|
||||
|
||||
\list 1
|
||||
|
||||
\li Make a copy of the \c {share/qtcreator/templates/wizards/helloworld}
|
||||
or \c {share/qtcreator/templates/wizards/listmodel} folder.
|
||||
|
||||
\li Modify the wizard_example.xml file.
|
||||
|
||||
\li The following code determines the type of the wizard and its place
|
||||
in the \gui New dialog:
|
||||
|
||||
\code
|
||||
|
||||
<wizard version="1" kind="project"
|
||||
class="qmakeproject" firstpage="10"
|
||||
id="A.HelloWorld" category="B.CustomProjects">
|
||||
|
||||
\endcode
|
||||
|
||||
\list
|
||||
|
||||
\li \c version is the version of the file contents. Do not modify
|
||||
this value.
|
||||
|
||||
\li \c kind specifies the type of the wizard: \c project or
|
||||
\c class.
|
||||
|
||||
\li \c class specifies the type of the project. This attribute is
|
||||
optional. Use the value \c qmakeproject to add Qt specific pages.
|
||||
|
||||
\li \c 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.
|
||||
|
||||
\li \c id is the unique identifier for your wizard. The letter
|
||||
specifies the position of the wizard within the \c category. The
|
||||
HelloWorld wizard appears as the first wizard in the second
|
||||
category in the \gui New dialog.
|
||||
|
||||
\li \c 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 \gui New dialog.
|
||||
|
||||
\endlist
|
||||
|
||||
\li The following code specifies the icon and text that appear in the
|
||||
\gui New dialog:
|
||||
|
||||
\code
|
||||
|
||||
<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>
|
||||
|
||||
\endcode
|
||||
|
||||
\list
|
||||
|
||||
\li \c displayCategory appears in the \gui New dialog, under
|
||||
\gui Projects.
|
||||
|
||||
\li \c icon appears next to the \c displayName in the middle panel
|
||||
when \c displayCategory is selected.
|
||||
|
||||
\li \c description appears in the right-most panel when
|
||||
\c 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, \c {xml:lang="de"}.
|
||||
|
||||
\endlist
|
||||
|
||||
\li Files to be added to the project:
|
||||
|
||||
\list
|
||||
|
||||
\li Template-based: The following code specifies the files to add to
|
||||
the project:
|
||||
\code
|
||||
<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" />
|
||||
\endcode
|
||||
|
||||
\list
|
||||
|
||||
\li \c source specifies the file to copy to the project. The
|
||||
files must be located in the wizard folder.
|
||||
|
||||
\li \c openeditor indicates that the file is to be opened in an
|
||||
editor after the wizard has finished.
|
||||
|
||||
\li \c 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.
|
||||
|
||||
\li \c target specifies the new filename for the file. The
|
||||
\c {%ProjectName%} variable is replaced with the string that
|
||||
users specify in the \gui Name field on the first page of
|
||||
the wizard.
|
||||
|
||||
\li \c openproject indicates that the file is a project file
|
||||
which is to be opened after the wizard has finished.
|
||||
|
||||
\endlist
|
||||
|
||||
See also \l{Processing Template Files}.
|
||||
|
||||
\li Generator-script: The following code specifies that the script
|
||||
\c generate.pl is to be used to create the files:
|
||||
|
||||
\code
|
||||
<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>
|
||||
\endcode
|
||||
|
||||
In each argument, the field placeholders are replaced by the
|
||||
field values. There are additional boolean attributes which give
|
||||
fine-grained control:
|
||||
|
||||
\list
|
||||
|
||||
\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.
|
||||
|
||||
\endlist
|
||||
|
||||
See also \l{Using Generator Scripts}.
|
||||
|
||||
\endlist
|
||||
|
||||
\li The following code creates a page that specifies settings for the project:
|
||||
|
||||
\code
|
||||
<!-- 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>
|
||||
\endcode
|
||||
|
||||
\list
|
||||
|
||||
\li \c fieldpagetitle specifies the title of the page.
|
||||
|
||||
\li \c fields specifies the user interface objects on the page.
|
||||
|
||||
\li \c 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 \l {Supported Widgets}.
|
||||
|
||||
\li \c mandatory specifies whether the field is mandatory (\c true or
|
||||
\c false). For more information, see QWizardPage::registerField().
|
||||
|
||||
\li \c name specifies a name that you can use as a placeholder variable in the
|
||||
template file (for example, \c {%MESSAGE%}).
|
||||
|
||||
\li \c class specifies the type of the \c fieldcontrol. The XML attributes that you
|
||||
can specify for the field depend on the field type.
|
||||
|
||||
\li For a QLineEdit, \c validator specifies a regular expression to check the
|
||||
characters allowed in the field.
|
||||
|
||||
\li \c defaulttext specifies text that appears in the field by
|
||||
default.
|
||||
|
||||
\li For a QLineEdit, \c placeholdertext specifies placeholder text that appears in the
|
||||
field.
|
||||
|
||||
\li \c fielddescription specifies the field name that appears on the
|
||||
wizard page.
|
||||
|
||||
\endlist
|
||||
|
||||
\endlist
|
||||
|
||||
\section1 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:
|
||||
|
||||
\list 1
|
||||
|
||||
\li The following code specifies settings for the wizard:
|
||||
|
||||
\code
|
||||
|
||||
<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>
|
||||
|
||||
\endcode
|
||||
|
||||
For more information about the elements and their values, see
|
||||
\l {Creating Project Wizards}.
|
||||
|
||||
\li The following code specifies the files to add to the project:
|
||||
|
||||
\code
|
||||
|
||||
<files>
|
||||
<file source="listmodel.cpp" target="%ClassName:l%.%CppSourceSuffix%" openeditor="true" />
|
||||
<file source="listmodel.h" target="%ClassName:l%.%CppHeaderSuffix%" openeditor="true" />
|
||||
</files>
|
||||
|
||||
\endcode
|
||||
|
||||
Here, \c target contains the following variables that are used to
|
||||
construct the filename:
|
||||
|
||||
\list
|
||||
|
||||
\li \c {%ClassName:l%} is replaced with the value of the
|
||||
\c ClassName field. The modifier \c l converts the string to
|
||||
lower case, to observe Qt conventions.
|
||||
|
||||
\li \c {%CppSourceSuffix%} and \c {%CppHeaderSuffix%} are
|
||||
pre-defined. For more information, see
|
||||
\l{Pre-defined Standard Variables}.
|
||||
|
||||
\endlist
|
||||
|
||||
\code
|
||||
|
||||
<!-- 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>
|
||||
|
||||
\endcode
|
||||
|
||||
In addition to QLineEdit, QComboBox is used in the class wizard to
|
||||
create a field. Specify the following XML attributes:
|
||||
|
||||
\list
|
||||
|
||||
\li \c defaultindex specifies which comboentry is displayed by default. In the above
|
||||
example, "0" means that the first comboentry is the default value.
|
||||
|
||||
\li \c comboentries specifies the options in the combobox.
|
||||
|
||||
\li \c value specifies the type of each \c comboentry, QString or integer.
|
||||
|
||||
\li \c comboentrytext specifies the text of the entry.
|
||||
|
||||
\endlist
|
||||
|
||||
\endlist
|
||||
|
||||
\section1 Supported Widgets
|
||||
|
||||
You can use the following interface objects to create fields in the wizards:
|
||||
|
||||
\list
|
||||
|
||||
\li PathChooser utility to set paths
|
||||
|
||||
\li Check boxes with text labels (QCheckBox)
|
||||
|
||||
\li Combined button and popup lists (QComboBox)
|
||||
|
||||
\li One-line text editors (QLineEdit)
|
||||
|
||||
\li Multi-line rich text editors (QTextEdit)
|
||||
|
||||
\endlist
|
||||
|
||||
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 \c fieldcontrol element of a field in a particular
|
||||
\c class.
|
||||
|
||||
\section2 Path Choosers
|
||||
|
||||
\code
|
||||
<field mandatory="true" name="QtCreatorSources">
|
||||
<fieldcontrol class="Utils::PathChooser" defaulttext="" expectedkind="existingdirectory"/>
|
||||
<fielddescription>Qt Creator sources:</fielddescription>
|
||||
</field>
|
||||
\endcode
|
||||
|
||||
The \c defaulttext attribute specifies text that appears in the field by default.
|
||||
|
||||
The text attribute \c expectedkind specifies which type of path is expected:
|
||||
|
||||
\list
|
||||
|
||||
\li \c any accepts any kind of path.
|
||||
|
||||
\li \c file expects a file.
|
||||
|
||||
\li \c directory expects a directory.
|
||||
|
||||
\li \c existingdirectory expects an existing directory.
|
||||
|
||||
\li \c command expects an executable file.
|
||||
|
||||
\li \c existingcommand expects an existing, executable file.
|
||||
|
||||
\endlist
|
||||
|
||||
\section2 Check Boxes
|
||||
|
||||
To make check boxes appear selected by default, set the \c fieldcontrol attribute
|
||||
\c defaultvalue to \c true. Any other value or omitting the attribute makes the check box
|
||||
appear not selected.
|
||||
|
||||
For example:
|
||||
|
||||
\code
|
||||
<field name="CONSOLE">
|
||||
<fieldcontrol class="QCheckBox" defaultvalue="true"/>
|
||||
<fielddescription>Console application</fielddescription>
|
||||
</field>
|
||||
\endcode
|
||||
|
||||
For more examples about using check boxes, see \l{Processing Template Files}.
|
||||
|
||||
\section2 Text Editors
|
||||
|
||||
\code
|
||||
<field name="License">
|
||||
<fieldcontrol class="QTextEdit" defaulttext="Put your license text here" />
|
||||
<fielddescription>License:</fielddescription>
|
||||
</field>
|
||||
\endcode
|
||||
|
||||
The \c defaulttext attribute specifies text that appears in the field by default.
|
||||
|
||||
The boolean attribute \c 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.
|
||||
|
||||
\section1 Processing Template Files
|
||||
|
||||
When processing a template source file, placeholders specifying the field
|
||||
names in the format \c{%FIELDNAME%} are replaced by the values entered by
|
||||
the user. In addition, modifier characters are supported. For example,
|
||||
\c{%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:
|
||||
|
||||
\list
|
||||
|
||||
\li \c{l} for lower case.
|
||||
|
||||
\li \c{u} for upper case.
|
||||
|
||||
\li \c{c} for upper case initial letter ("project" > "Project").
|
||||
|
||||
\endlist
|
||||
|
||||
In the \c{helloworld} example, the placeholder \c %NETWORK% is used together with the
|
||||
QCheckBox class. The following line is added to the project file:
|
||||
|
||||
\code
|
||||
%NETWORK%QT += network
|
||||
\endcode
|
||||
|
||||
And the following field is specified in the wizard.xml:
|
||||
|
||||
\code
|
||||
<field name="NETWORK">
|
||||
<fieldcontrol class="QCheckBox" truevalue="" falsevalue="# "/>
|
||||
<fielddescription>Include network module</fielddescription>
|
||||
<fielddescription xml:lang="de">Netzwerk-Modul verwenden</fielddescription>
|
||||
</field>
|
||||
\endcode
|
||||
|
||||
If the checkbox is checked, the placeholder is replaced by \c truevalue. If it is not
|
||||
checked, the placeholder is replaced by \c 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 \c{helloworld} example:
|
||||
|
||||
\code
|
||||
|
||||
@if "%SCRIPT%" == "true"
|
||||
QT += script
|
||||
@endif
|
||||
|
||||
\endcode
|
||||
|
||||
The value of the Boolean (QCheckBox) field labeled \c{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:
|
||||
|
||||
\code
|
||||
<field name="SCRIPT">
|
||||
<fieldcontrol class="QCheckBox"/>
|
||||
<fielddescription>Include script module</fielddescription>
|
||||
<fielddescription xml:lang="de">Script-Modul verwenden</fielddescription>
|
||||
</field>
|
||||
\endcode
|
||||
|
||||
\section1 Pre-defined Standard Variables
|
||||
|
||||
In addition to the field values entered by the user, you can use
|
||||
the following pre-defined standard values:
|
||||
|
||||
\list
|
||||
|
||||
\li \c {%ProjectName%} is replaced by the name of the project in the
|
||||
case of project wizards.
|
||||
|
||||
\li \c {%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.
|
||||
|
||||
\li \c {%TargetPath%} is replaced by the path to the directory where the
|
||||
actual files are created. For non-project wizards, it is identical
|
||||
to \c %Path%. For project wizards, it is \c %Path%/%ProjectName%.
|
||||
|
||||
\li \c {%CppSourceSuffix%} is replaced by the default source suffix,
|
||||
which is defined in \QC in \gui {Tools > Options > C++ >
|
||||
File Naming}. For example, if users enter \b MyClass, the
|
||||
filename becomes myclass.cpp when the project is created.
|
||||
|
||||
\li \c {%CppHeaderSuffix%} is replaced by the default header suffix,
|
||||
which is also defined in \gui {File Naming}.
|
||||
|
||||
\li \c {%CurrentDate%} is replaced by the current date in the format
|
||||
\c {YYYY-MM-DD} as specified by ISO 8601.
|
||||
|
||||
\li \c {%CurrentTime%} is replaced by the current time in the format
|
||||
\c {HH:MM:SS} as specified by ISO 8601.
|
||||
|
||||
\li \c {%CurrentDate:Locale%} is replaced by the current date in the short format
|
||||
specified by the application's locale.
|
||||
|
||||
\li \c {%CurrentTime:Locale%} is replaced by the current time in the short format
|
||||
specified by the application's locale.
|
||||
|
||||
\li \c {%CurrentDate:ISO%} is replaced by the current date in the format
|
||||
\c {YYYY-MM-DD} as specified by ISO 8601.
|
||||
|
||||
\li \c {%CurrentTime:ISO%} is replaced by the current time in the format
|
||||
\c {HH:MM:SS} as specified by ISO 8601.
|
||||
|
||||
\li \c {%CurrentDate:RFC%} is replaced by the current date in the format
|
||||
\c {DD Mon YYYY}, where \c {Mon} is the three letter month name, as specified by RFC 2822.
|
||||
|
||||
\li \c {%CurrentTime:RFC%} is replaced by the current time in the format
|
||||
\c {HH:MM:SS} as specified by RFC 2822.
|
||||
|
||||
\endlist
|
||||
|
||||
\section1 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 \l{Creating Class Wizards} example:
|
||||
|
||||
\code
|
||||
<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>
|
||||
\endcode
|
||||
|
||||
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.
|
||||
|
||||
\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
|
||||
example:
|
||||
|
||||
\code
|
||||
myclass.cpp,openeditor
|
||||
myclass.h,openeditor
|
||||
myproject.pro,openproject
|
||||
\endcode
|
||||
|
||||
\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.
|
||||
|
||||
\endlist
|
||||
|
||||
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
|
||||
generate.pl --class-name=TestClass --project-name=TestProject --header-suffix=h --source-suffix=cpp --description=/tmp/qtcreatorj26629.txt
|
||||
\endcode
|
||||
|
||||
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%.
|
||||
|
||||
*/
|
||||
@@ -26,7 +26,7 @@
|
||||
\contentspage {Qt Creator Manual}
|
||||
\previouspage creator-project-qmake-libraries.html
|
||||
\page creator-project-wizards.html
|
||||
\nextpage creator-version-control.html
|
||||
\nextpage creator-project-wizards-xml.html
|
||||
|
||||
\title Adding New Custom Wizards
|
||||
|
||||
@@ -45,636 +45,10 @@
|
||||
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
|
||||
\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"
|
||||
|
||||
\section1 Overview of Custom Wizards
|
||||
|
||||
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:
|
||||
|
||||
\list 1
|
||||
|
||||
\li Template-based, where source files that contain placeholders for
|
||||
the field names are provided. During processing, the placeholders
|
||||
are replaced by the values from the wizard page. Optionally,
|
||||
modifier characters are applied. For more information, see
|
||||
\l{Processing Template Files}.
|
||||
|
||||
\li Generator script, where a script is called to create the files.
|
||||
|
||||
\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 \l{Using Generator Scripts}.
|
||||
|
||||
\endlist
|
||||
|
||||
Custom wizards are located in subdirectories of the following directories:
|
||||
You can create either JSON-based or XML-based wizards. We recommend creating
|
||||
JSON-based wizards for new projects.
|
||||
|
||||
\list
|
||||
|
||||
\li \c{share/qtcreator/templates/wizards}
|
||||
|
||||
\li the local user's configuration folder,
|
||||
\c{$HOME/.config/QtProject/qtcreator/templates/wizards}
|
||||
|
||||
\li \c{%APPDATA%\QtProject\qtcreator\templates\wizards}
|
||||
|
||||
\li \l{Adding XML-Based Wizards}
|
||||
\endlist
|
||||
|
||||
They contain an XML configuration file called wizard.xml, the template
|
||||
source files, and optionally, the generator script.
|
||||
|
||||
\section1 Creating Project Wizards
|
||||
|
||||
To create a project wizard:
|
||||
|
||||
\list 1
|
||||
|
||||
\li Make a copy of the \c {share/qtcreator/templates/wizards/helloworld}
|
||||
or \c {share/qtcreator/templates/wizards/listmodel} folder.
|
||||
|
||||
\li Modify the wizard_example.xml file.
|
||||
|
||||
\li The following code determines the type of the wizard and its place
|
||||
in the \uicontrol New dialog:
|
||||
|
||||
\code
|
||||
|
||||
<wizard version="1" kind="project"
|
||||
class="qmakeproject" firstpage="10"
|
||||
id="A.HelloWorld" category="B.CustomProjects">
|
||||
|
||||
\endcode
|
||||
|
||||
\list
|
||||
|
||||
\li \c version is the version of the file contents. Do not modify
|
||||
this value.
|
||||
|
||||
\li \c kind specifies the type of the wizard: \c project or
|
||||
\c class.
|
||||
|
||||
\li \c class specifies the type of the project. This attribute is
|
||||
optional. Use the value \c qmakeproject to add Qt specific pages.
|
||||
|
||||
\li \c 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.
|
||||
|
||||
\li \c id is the unique identifier for your wizard. The letter
|
||||
specifies the position of the wizard within the \c category. The
|
||||
HelloWorld wizard appears as the first wizard in the second
|
||||
category in the \uicontrol New dialog.
|
||||
|
||||
\li \c 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 \uicontrol New dialog.
|
||||
|
||||
\endlist
|
||||
|
||||
\li The following code specifies the icon and text that appear in the
|
||||
\uicontrol New dialog:
|
||||
|
||||
\code
|
||||
|
||||
<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>
|
||||
|
||||
\endcode
|
||||
|
||||
\list
|
||||
|
||||
\li \c displayCategory appears in the \uicontrol New dialog, under
|
||||
\uicontrol Projects.
|
||||
|
||||
\li \c icon appears next to the \c displayName in the middle panel
|
||||
when \c displayCategory is selected.
|
||||
|
||||
\li \c description appears in the right-most panel when
|
||||
\c 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, \c {xml:lang="de"}.
|
||||
|
||||
\endlist
|
||||
|
||||
\li Files to be added to the project:
|
||||
|
||||
\list
|
||||
|
||||
\li Template-based: The following code specifies the files to add to
|
||||
the project:
|
||||
\code
|
||||
<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" />
|
||||
\endcode
|
||||
|
||||
\list
|
||||
|
||||
\li \c source specifies the file to copy to the project. The
|
||||
files must be located in the wizard folder.
|
||||
|
||||
\li \c openeditor indicates that the file is to be opened in an
|
||||
editor after the wizard has finished.
|
||||
|
||||
\li \c 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.
|
||||
|
||||
\li \c target specifies the new filename for the file. The
|
||||
\c {%ProjectName%} variable is replaced with the string that
|
||||
users specify in the \uicontrol Name field on the first page of
|
||||
the wizard.
|
||||
|
||||
\li \c openproject indicates that the file is a project file
|
||||
which is to be opened after the wizard has finished.
|
||||
|
||||
\endlist
|
||||
|
||||
See also \l{Processing Template Files}.
|
||||
|
||||
\li Generator-script: The following code specifies that the script
|
||||
\c generate.pl is to be used to create the files:
|
||||
|
||||
\code
|
||||
<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>
|
||||
\endcode
|
||||
|
||||
In each argument, the field placeholders are replaced by the
|
||||
field values. There are additional boolean attributes which give
|
||||
fine-grained control:
|
||||
|
||||
\list
|
||||
|
||||
\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.
|
||||
|
||||
\endlist
|
||||
|
||||
See also \l{Using Generator Scripts}.
|
||||
|
||||
\endlist
|
||||
|
||||
\li The following code creates a page that specifies settings for the project:
|
||||
|
||||
\code
|
||||
<!-- 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>
|
||||
\endcode
|
||||
|
||||
\list
|
||||
|
||||
\li \c fieldpagetitle specifies the title of the page.
|
||||
|
||||
\li \c fields specifies the user interface objects on the page.
|
||||
|
||||
\li \c 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 \l {Supported Widgets}.
|
||||
|
||||
\li \c mandatory specifies whether the field is mandatory (\c true or
|
||||
\c false). For more information, see QWizardPage::registerField().
|
||||
|
||||
\li \c name specifies a name that you can use as a placeholder variable in the
|
||||
template file (for example, \c {%MESSAGE%}).
|
||||
|
||||
\li \c class specifies the type of the \c fieldcontrol. The XML attributes that you
|
||||
can specify for the field depend on the field type.
|
||||
|
||||
\li For a QLineEdit, \c validator specifies a regular expression to check the
|
||||
characters allowed in the field.
|
||||
|
||||
\li \c defaulttext specifies text that appears in the field by
|
||||
default.
|
||||
|
||||
\li For a QLineEdit, \c placeholdertext specifies placeholder text that appears in the
|
||||
field.
|
||||
|
||||
\li \c fielddescription specifies the field name that appears on the
|
||||
wizard page.
|
||||
|
||||
\endlist
|
||||
|
||||
\endlist
|
||||
|
||||
\section1 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:
|
||||
|
||||
\list 1
|
||||
|
||||
\li The following code specifies settings for the wizard:
|
||||
|
||||
\code
|
||||
|
||||
<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>
|
||||
|
||||
\endcode
|
||||
|
||||
For more information about the elements and their values, see
|
||||
\l {Creating Project Wizards}.
|
||||
|
||||
\li The following code specifies the files to add to the project:
|
||||
|
||||
\code
|
||||
|
||||
<files>
|
||||
<file source="listmodel.cpp" target="%ClassName:l%.%CppSourceSuffix%" openeditor="true" />
|
||||
<file source="listmodel.h" target="%ClassName:l%.%CppHeaderSuffix%" openeditor="true" />
|
||||
</files>
|
||||
|
||||
\endcode
|
||||
|
||||
Here, \c target contains the following variables that are used to
|
||||
construct the filename:
|
||||
|
||||
\list
|
||||
|
||||
\li \c {%ClassName:l%} is replaced with the value of the
|
||||
\c ClassName field. The modifier \c l converts the string to
|
||||
lower case, to observe Qt conventions.
|
||||
|
||||
\li \c {%CppSourceSuffix%} and \c {%CppHeaderSuffix%} are
|
||||
pre-defined. For more information, see
|
||||
\l{Pre-defined Standard Variables}.
|
||||
|
||||
\endlist
|
||||
|
||||
\code
|
||||
|
||||
<!-- 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>
|
||||
|
||||
\endcode
|
||||
|
||||
In addition to QLineEdit, QComboBox is used in the class wizard to
|
||||
create a field. Specify the following XML attributes:
|
||||
|
||||
\list
|
||||
|
||||
\li \c defaultindex specifies which comboentry is displayed by default. In the above
|
||||
example, "0" means that the first comboentry is the default value.
|
||||
|
||||
\li \c comboentries specifies the options in the combobox.
|
||||
|
||||
\li \c value specifies the type of each \c comboentry, QString or integer.
|
||||
|
||||
\li \c comboentrytext specifies the text of the entry.
|
||||
|
||||
\endlist
|
||||
|
||||
\endlist
|
||||
|
||||
\section1 Supported Widgets
|
||||
|
||||
You can use the following interface objects to create fields in the wizards:
|
||||
|
||||
\list
|
||||
|
||||
\li PathChooser utility to set paths
|
||||
|
||||
\li Check boxes with text labels (QCheckBox)
|
||||
|
||||
\li Combined button and popup lists (QComboBox)
|
||||
|
||||
\li One-line text editors (QLineEdit)
|
||||
|
||||
\li Multi-line rich text editors (QTextEdit)
|
||||
|
||||
\endlist
|
||||
|
||||
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 \c fieldcontrol element of a field in a particular
|
||||
\c class.
|
||||
|
||||
\section2 Path Choosers
|
||||
|
||||
\code
|
||||
<field mandatory="true" name="QtCreatorSources">
|
||||
<fieldcontrol class="Utils::PathChooser" defaulttext="" expectedkind="existingdirectory"/>
|
||||
<fielddescription>Qt Creator sources:</fielddescription>
|
||||
</field>
|
||||
\endcode
|
||||
|
||||
The \c defaulttext attribute specifies text that appears in the field by default.
|
||||
|
||||
The text attribute \c expectedkind specifies which type of path is expected:
|
||||
|
||||
\list
|
||||
|
||||
\li \c any accepts any kind of path.
|
||||
|
||||
\li \c file expects a file.
|
||||
|
||||
\li \c directory expects a directory.
|
||||
|
||||
\li \c existingdirectory expects an existing directory.
|
||||
|
||||
\li \c command expects an executable file.
|
||||
|
||||
\li \c existingcommand expects an existing, executable file.
|
||||
|
||||
\endlist
|
||||
|
||||
\section2 Check Boxes
|
||||
|
||||
To make check boxes appear selected by default, set the \c fieldcontrol attribute
|
||||
\c defaultvalue to \c true. Any other value or omitting the attribute makes the check box
|
||||
appear not selected.
|
||||
|
||||
For example:
|
||||
|
||||
\code
|
||||
<field name="CONSOLE">
|
||||
<fieldcontrol class="QCheckBox" defaultvalue="true"/>
|
||||
<fielddescription>Console application</fielddescription>
|
||||
</field>
|
||||
\endcode
|
||||
|
||||
For more examples about using check boxes, see \l{Processing Template Files}.
|
||||
|
||||
\section2 Text Editors
|
||||
|
||||
\code
|
||||
<field name="License">
|
||||
<fieldcontrol class="QTextEdit" defaulttext="Put your license text here" />
|
||||
<fielddescription>License:</fielddescription>
|
||||
</field>
|
||||
\endcode
|
||||
|
||||
The \c defaulttext attribute specifies text that appears in the field by default.
|
||||
|
||||
The boolean attribute \c 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.
|
||||
|
||||
\section1 Processing Template Files
|
||||
|
||||
When processing a template source file, placeholders specifying the field
|
||||
names in the format \c{%FIELDNAME%} are replaced by the values entered by
|
||||
the user. In addition, modifier characters are supported. For example,
|
||||
\c{%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:
|
||||
|
||||
\list
|
||||
|
||||
\li \c{l} for lower case.
|
||||
|
||||
\li \c{u} for upper case.
|
||||
|
||||
\li \c{c} for upper case initial letter ("project" > "Project").
|
||||
|
||||
\endlist
|
||||
|
||||
In the \c{helloworld} example, the placeholder \c %NETWORK% is used together with the
|
||||
QCheckBox class. The following line is added to the project file:
|
||||
|
||||
\code
|
||||
%NETWORK%QT += network
|
||||
\endcode
|
||||
|
||||
And the following field is specified in the wizard.xml:
|
||||
|
||||
\code
|
||||
<field name="NETWORK">
|
||||
<fieldcontrol class="QCheckBox" truevalue="" falsevalue="# "/>
|
||||
<fielddescription>Include network module</fielddescription>
|
||||
<fielddescription xml:lang="de">Netzwerk-Modul verwenden</fielddescription>
|
||||
</field>
|
||||
\endcode
|
||||
|
||||
If the checkbox is checked, the placeholder is replaced by \c truevalue. If it is not
|
||||
checked, the placeholder is replaced by \c 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 \c{helloworld} example:
|
||||
|
||||
\code
|
||||
|
||||
@if "%SCRIPT%" == "true"
|
||||
QT += script
|
||||
@endif
|
||||
|
||||
\endcode
|
||||
|
||||
The value of the Boolean (QCheckBox) field labeled \c{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:
|
||||
|
||||
\code
|
||||
<field name="SCRIPT">
|
||||
<fieldcontrol class="QCheckBox"/>
|
||||
<fielddescription>Include script module</fielddescription>
|
||||
<fielddescription xml:lang="de">Script-Modul verwenden</fielddescription>
|
||||
</field>
|
||||
\endcode
|
||||
|
||||
\section1 Pre-defined Standard Variables
|
||||
|
||||
In addition to the field values entered by the user, you can use
|
||||
the following pre-defined standard values:
|
||||
|
||||
\list
|
||||
|
||||
\li \c {%ProjectName%} is replaced by the name of the project in the
|
||||
case of project wizards.
|
||||
|
||||
\li \c {%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.
|
||||
|
||||
\li \c {%TargetPath%} is replaced by the path to the directory where the
|
||||
actual files are created. For non-project wizards, it is identical
|
||||
to \c %Path%. For project wizards, it is \c %Path%/%ProjectName%.
|
||||
|
||||
\li \c {%CppSourceSuffix%} is replaced by the default source suffix,
|
||||
which is defined in \QC in \uicontrol {Tools > Options > C++ >
|
||||
File Naming}. For example, if users enter \b MyClass, the
|
||||
filename becomes myclass.cpp when the project is created.
|
||||
|
||||
\li \c {%CppHeaderSuffix%} is replaced by the default header suffix,
|
||||
which is also defined in \uicontrol {File Naming}.
|
||||
|
||||
\li \c {%CurrentDate%} is replaced by the current date in the format
|
||||
\c {YYYY-MM-DD} as specified by ISO 8601.
|
||||
|
||||
\li \c {%CurrentTime%} is replaced by the current time in the format
|
||||
\c {HH:MM:SS} as specified by ISO 8601.
|
||||
|
||||
\li \c {%CurrentDate:Locale%} is replaced by the current date in the short format
|
||||
specified by the application's locale.
|
||||
|
||||
\li \c {%CurrentTime:Locale%} is replaced by the current time in the short format
|
||||
specified by the application's locale.
|
||||
|
||||
\li \c {%CurrentDate:ISO%} is replaced by the current date in the format
|
||||
\c {YYYY-MM-DD} as specified by ISO 8601.
|
||||
|
||||
\li \c {%CurrentTime:ISO%} is replaced by the current time in the format
|
||||
\c {HH:MM:SS} as specified by ISO 8601.
|
||||
|
||||
\li \c {%CurrentDate:RFC%} is replaced by the current date in the format
|
||||
\c {DD Mon YYYY}, where \c {Mon} is the three letter month name, as specified by RFC 2822.
|
||||
|
||||
\li \c {%CurrentTime:RFC%} is replaced by the current time in the format
|
||||
\c {HH:MM:SS} as specified by RFC 2822.
|
||||
|
||||
\endlist
|
||||
|
||||
\section1 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 \l{Creating Class Wizards} example:
|
||||
|
||||
\code
|
||||
<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>
|
||||
\endcode
|
||||
|
||||
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.
|
||||
|
||||
\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
|
||||
example:
|
||||
|
||||
\code
|
||||
myclass.cpp,openeditor
|
||||
myclass.h,openeditor
|
||||
myproject.pro,openproject
|
||||
\endcode
|
||||
|
||||
\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.
|
||||
|
||||
\endlist
|
||||
|
||||
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
|
||||
generate.pl --class-name=TestClass --project-name=TestProject --header-suffix=h --source-suffix=cpp --description=/tmp/qtcreatorj26629.txt
|
||||
\endcode
|
||||
|
||||
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%.
|
||||
|
||||
*/
|
||||
|
||||
@@ -143,6 +143,9 @@
|
||||
\li \l{Opening Projects}
|
||||
\li \l{Adding Libraries to Projects}
|
||||
\li \l{Adding New Custom Wizards}
|
||||
\list
|
||||
\li \l{Adding XML-Based Wizards}
|
||||
\endlist
|
||||
\endlist
|
||||
\li \l{Using Version Control Systems}
|
||||
\li \l{Configuring Projects}
|
||||
|
||||
Reference in New Issue
Block a user