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}
|
\contentspage {Qt Creator Manual}
|
||||||
\previouspage creator-project-wizards.html
|
\previouspage creator-project-wizards-xml.html
|
||||||
\page creator-version-control.html
|
\page creator-version-control.html
|
||||||
\nextpage creator-configuring-projects.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}
|
\contentspage {Qt Creator Manual}
|
||||||
\previouspage creator-project-qmake-libraries.html
|
\previouspage creator-project-qmake-libraries.html
|
||||||
\page creator-project-wizards.html
|
\page creator-project-wizards.html
|
||||||
\nextpage creator-version-control.html
|
\nextpage creator-project-wizards-xml.html
|
||||||
|
|
||||||
\title Adding New Custom Wizards
|
\title Adding New Custom Wizards
|
||||||
|
|
||||||
@@ -45,636 +45,10 @@
|
|||||||
In a class wizard, you can allow developers to specify the class name, base
|
In a class wizard, you can allow developers to specify the class name, base
|
||||||
class, and header and source files for the class.
|
class, and header and source files for the class.
|
||||||
|
|
||||||
To see how this works, rename wizard_sample.xml as wizard.xml in the
|
You can create either JSON-based or XML-based wizards. We recommend creating
|
||||||
\c {\share\qtcreator\templates\wizards\helloworld} and
|
JSON-based wizards for new projects.
|
||||||
\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:
|
|
||||||
|
|
||||||
\list
|
\list
|
||||||
|
\li \l{Adding XML-Based Wizards}
|
||||||
\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
|
\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{Opening Projects}
|
||||||
\li \l{Adding Libraries to Projects}
|
\li \l{Adding Libraries to Projects}
|
||||||
\li \l{Adding New Custom Wizards}
|
\li \l{Adding New Custom Wizards}
|
||||||
|
\list
|
||||||
|
\li \l{Adding XML-Based Wizards}
|
||||||
|
\endlist
|
||||||
\endlist
|
\endlist
|
||||||
\li \l{Using Version Control Systems}
|
\li \l{Using Version Control Systems}
|
||||||
\li \l{Configuring Projects}
|
\li \l{Configuring Projects}
|
||||||
|
|||||||
Reference in New Issue
Block a user