Doc: Remove information about XML-based project wizards

Combine the overview topic and JSON-wizard topic, because there
is now only one wizard type.

Change-Id: I80c4412aa0973ef4ac339ed3c757dcc24779cb42
Reviewed-by: Eike Ziller <eike.ziller@qt.io>
This commit is contained in:
Leena Miettinen
2020-01-10 15:44:43 +01:00
parent aaabc2f472
commit 311779e53e
6 changed files with 59 additions and 643 deletions

Binary file not shown.

Before

Width:  |  Height:  |  Size: 36 KiB

View File

@@ -1,6 +1,6 @@
/****************************************************************************
**
** Copyright (C) 2019 The Qt Company Ltd.
** Copyright (C) 2020 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Creator documentation.
@@ -23,59 +23,8 @@
**
****************************************************************************/
// **********************************************************************
// 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 index.html
\previouspage creator-project-wizards.html
\page creator-project-wizards-json.html
\nextpage creator-project-wizards-xml.html
\title Adding JSON-Based Wizards
\QC searches for wizards in the shared directory and in the local user's
settings directory, as described in \l{Locating Wizards}.
JSON-based wizard template directories contain a JSON configuration file
called \c {wizard.json} and any template files needed. The configuration
file contains sections that specify information about the wizard, variables
that you can use, wizard pages, and generators for creating files.
To create a customized wizard, copy a template directory to the shared
directory or the settings directory under a new name. If you want to use
qmake to build the wizard and integrate it into \QC, use the shared
directory. Otherwise, you can create a subdirectory in the settings
directory. The standard wizards are organized into subdirectories by type,
but you can add your wizard directory to any directory you like. The folder
hierarchy does not affect the order in which the wizards are displayed.
To share the wizard with other users, you can create an archive of the
wizard directory and instruct the recipients to extract it into one of the
directories \QC searches wizards from.
For wizard development, we recommend that you start \QC with the
\c {-customwizard-verbose} argument to receive confirmation that \QC was
able to find and parse the \c {wizard.json} file. The verbose mode displays
information about syntax errors, which are the most typical errors you might
run into while editing wizards. For more information, see
\l {Verbose Output}.
In addition, set keyboard shortcuts for the \uicontrol Inspect and
\uicontrol {Factory.Reset} functions to be able to inspect the fields and
variables in the wizard and to have the wizard listed in \uicontrol File >
\uicontrol {New File or Project} without restarting \QC. For more
information, see \l {Tips for Wizard Development}.
\QC displays the wizards that it finds in the
\uicontrol {New File or Project} dialog. For each wizard, an icon (1), a
display name (2), and a description (3) are displayed.
\image qtcreator-custom-wizard.png
//! [json wizards]
\section1 Integrating Wizards into Builds
To integrate the wizard into \QC and to deliver it as part of the \QC build,
@@ -994,5 +943,5 @@
and no subdirectories will be scanned.
\endlist
//! [json wizards]
*/

View File

@@ -1,550 +0,0 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Creator documentation.
**
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** 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. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
**
****************************************************************************/
// **********************************************************************
// 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 index.html
\previouspage creator-project-wizards-json.html
\page creator-project-wizards-xml.html
\nextpage creator-version-control.html
\title Adding XML-Based Wizards
\note We recommend that you create \l{Adding JSON-Based Wizards}
{JSON-Based wizards} instead. XML wizards are deprecated and support for
them will be removed in future versions of \QC.
To see examples of XML-based wizards, select \uicontrol File >
\uicontrol {New File or Project} > \uicontrol Library. For each wizard, an
icon (1), a display name (2), and a description (3) are displayed.
\image qtcreator-custom-project-wizards.png "The New dialog"
Files can be generated by using \l{Processing Template Files}{templates}.
XML-based wizard template directories contain an XML configuration file
called wizard.xml and the template source files.
\section1 Creating XML-Based Project Wizards
To create an XML-based project wizard:
\list 1
\li Make a copy of a folder in the \c share/qtcreator/templates/wizards/
folder that contains an XML-based wizard (\c codesnippet,
\c qtcreatorplugin, or \c qtquick2-extension).
\li Modify the wizard.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.
\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 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 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 XML-Based 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.
*/

View File

@@ -1,6 +1,6 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Copyright (C) 2020 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Creator documentation.
@@ -33,7 +33,7 @@
\contentspage index.html
\previouspage creator-project-qmake-libraries.html
\page creator-project-wizards.html
\nextpage creator-project-wizards-json.html
\nextpage creator-version-control.html
\title Adding New Custom Wizards
@@ -41,14 +41,30 @@
you might want to standardize the way the team members create projects and
files.
You can copy the wizard templates in the template folders to create your own
project and file wizards. They are displayed in the \uicontrol New
dialog that opens when you choose \uicontrol File >
\uicontrol {New File or Project}.
You can create custom wizards in JSON format. They are stored in wizard
template directories that contain a JSON configuration file called
\c {wizard.json} and any template files needed. The configuration file
contains sections that specify information about the wizard, variables
that you can use, wizard pages, and generators for creating files.
A custom wizard defines the user interface of a set of wizard pages. 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.
To create a customized wizard, copy a template directory to the shared
directory or the local user's settings directory under a new name. Then
change the wizard id in the \c {wizard.json} file.
You can create a subdirectory for the templates in the settings directory.
The standard wizards are organized into subdirectories by type, but you can
add your wizard directory to any directory you like. The folder hierarchy
does not affect the order in which the wizards are displayed.
To share the wizard with other users, you can create an archive of the
wizard directory and instruct the recipients to extract it into one of the
directories \QC searches wizards from.
\QC displays the wizards that it finds in the
\uicontrol {New File or Project} dialog. For each wizard, an icon (1), a
display name (2), and a description (3) are displayed.
\image qtcreator-custom-wizard.png
\section1 Wizard Types
@@ -58,35 +74,34 @@
A file wizard is similar, but does not contain any project file.
You are encouraged to create JSON-based wizards. They provide a super-set
of the functionality available in the XML based wizards used before. For
more information, see:
\list
\li \l{Adding JSON-Based Wizards}
\li \l{Adding XML-Based Wizards} (deprecated)
\endlist
\section1 Locating Wizards
Wizards are located in subdirectories of the following directories:
\QC searches the following locations for wizards:
\list
\li \c {share/qtcreator/templates/wizards}
\li the local user's configuration folder,
\c {$HOME/.config/QtProject/qtcreator/templates/wizards} on Linux
and \macos or \c {%APPDATA%\QtProject\qtcreator\templates\wizards} on
Windows
\li Shared directory:
\list
\li On Windows: \c {share\qtcreator\templates\wizards}
\li On Linux: \c {share/qtcreator/templates/wizards}
\li On \macos:
\c{Qt Creator.app/Contents/Resources/templates/wizards}
\endlist
\li Local user's settings directory:
\list
\li On Windows:
\c {%APPDATA%\QtProject\qtcreator\templates\wizards}
\li On Linux and \macos:
\c {$HOME/.config/QtProject/qtcreator/templates/wizards}
\endlist
\endlist
\note If you installed \QC on \macos, you can find the wizards in
\c {Qt Creator.app/Contents/Resources/templates/wizards}.
\section1 Tips for Wizard Development
Assign keyboard shortcuts to some helper actions and turn on verbose output.
\section2 Mapping Actions to Keyboard Shortcuts
\QC has some actions that can improve the wizard development process. These
are by default not bound to any keyboard shortcuts and can thus not be
triggered. To enable them, assign keyboard shortcuts in \uicontrol Tools >
@@ -119,10 +134,14 @@
\section2 Verbose Output
When developing custom wizards (both JSON as well as XML based), it is
recommended to start \QC with the \c {-customwizard-verbose} argument. It
causes each correctly set up wizard to produce output along the following
lines:
For wizard development, we recommend that you start \QC with the
\c {-customwizard-verbose} argument to receive confirmation that \QC was
able to find and parse the \c {wizard.json} file. The verbose mode displays
information about syntax errors, which are the most typical errors you might
run into while editing wizards.
In verbose mode, each correctly set up wizard produces output along the
following lines:
\code
Checking "/home/jsmith/.config/QtProject/qtcreator/templates/wizards/mywizard"
@@ -147,4 +166,6 @@
See \l{Using Command Line Options} for more information about command line
arguments.
\include creator-projects-custom-wizards-json.qdocinc json wizards
*/

View File

@@ -56,10 +56,6 @@
\li \l{Opening Projects}
\li \l{Adding Libraries to Projects}
\li \l{Adding New Custom Wizards}
\list
\li \l{Adding JSON-Based Wizards}
\li \l{Adding XML-Based Wizards}
\endlist
\endlist
\li \l{Using Version Control Systems}
\list

View File

@@ -1,6 +1,6 @@
/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Copyright (C) 2020 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Creator documentation.
@@ -31,7 +31,7 @@
/*!
\contentspage index.html
\previouspage creator-project-wizards-xml.html
\previouspage creator-project-wizards.html
\page creator-version-control.html
\nextpage creator-vcs-bazaar.html