forked from qt-creator/qt-creator
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:
Binary file not shown.
|
Before Width: | Height: | Size: 36 KiB |
@@ -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]
|
||||
*/
|
||||
@@ -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.
|
||||
|
||||
*/
|
||||
@@ -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
|
||||
*/
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user