forked from qt-creator/qt-creator
Doc: adding JSON-based custom wizards
Task-number: QTCREATORBUG-13642 Change-Id: Ie3af0d4bdef33364cc442449ccfb5e770c0c3a99 Reviewed-by: Tobias Hunger <tobias.hunger@theqtcompany.com>
This commit is contained in:
committed by
Leena Miettinen
parent
77fa568870
commit
3b86184d12
686
doc/src/projects/creator-projects-custom-wizards-json.qdoc
Normal file
686
doc/src/projects/creator-projects-custom-wizards-json.qdoc
Normal file
@@ -0,0 +1,686 @@
|
||||
/****************************************************************************
|
||||
**
|
||||
** 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-json.html
|
||||
\nextpage creator-project-wizards-xml.html
|
||||
|
||||
\title Adding JSON-Based Wizards
|
||||
|
||||
\image qtcreator-new-qt-gui-application.png
|
||||
|
||||
The JSON-based wizards are displayed in the \uicontrol New dialog. To
|
||||
customize them, copy a directory that contains a wizard.json file in
|
||||
\c {share/qtcreator/templates/wizards/} and modify it to fit your needs.
|
||||
After you run qmake and restart \QC, the wizard name appears in the
|
||||
selected or added category. For each wizard, an icon, a display name, and
|
||||
a description are displayed.
|
||||
|
||||
JSON-based wizard template directories contain a JSON configuration file
|
||||
called wizard.json and the template files. The configuration file contains
|
||||
sections that specify information about the wizard, variables that you can
|
||||
use, wizard pages, and generators for creating files.
|
||||
|
||||
\section1 Using Variables in Wizards
|
||||
|
||||
You can use variables (\c %{<variableName>}) in the configuration and
|
||||
template source files. A set of variables is predefined by the wizards and
|
||||
their pages. You can introduce new variables as shortcuts to be used later.
|
||||
Define the variable key names and values in the \c options section in the
|
||||
.json file.
|
||||
|
||||
The variables always return strings. In places where a boolean value is
|
||||
expected and a string is given, an empty string is treated as \c false and
|
||||
anything else as \c true. A common pitfall is that a string containing
|
||||
\c "false" is not empty and is therefore treated as the value \c true when
|
||||
converted to a boolean value. To avoid this pitfall, use the following type
|
||||
of construction:
|
||||
|
||||
\code
|
||||
{"condition": "%{JS: ('%{VersionControl}' === 'G.Git') ? 'yes' : ''}"
|
||||
\endcode
|
||||
|
||||
\section1 Localizing Wizards
|
||||
|
||||
If a setting name starts with the \c tr prefix, the value is visible to
|
||||
users and should be translated. If the new wizard is included in the \QC
|
||||
sources, the translatable strings appear in the \QC translation files and
|
||||
can be translated as a part of \QC. Alternatively, you can place the
|
||||
translations in the .json file using the following syntax:
|
||||
|
||||
\code
|
||||
"trDisplayName": { "C": "default", "en_US": "english", "de_DE": "deutsch" }
|
||||
\endcode
|
||||
|
||||
For example:
|
||||
|
||||
\code
|
||||
"trDisplayName": { "C": "Project Location", "en_US": "Project Location", "de_DE": "Projekt Verzeichnis" }
|
||||
\endcode
|
||||
|
||||
\section1 Creating Wizards
|
||||
|
||||
\QC contains wizards for adding classes, files, and projects. You can
|
||||
use them as basis for adding your own wizards. We use the C++ wizard
|
||||
to explain the process and the sections and settings in the .json file.
|
||||
|
||||
\image qtcreator-cpp-class-wizard.png
|
||||
|
||||
For more information about the pages and widgets that you can add, see
|
||||
\l {Available Pages} and \l{Available Widgets}.
|
||||
|
||||
To create a JSON-based C++ class wizard:
|
||||
|
||||
\list 1
|
||||
|
||||
\li Make a copy of \c {share/qtcreator/templates/wizards/classes/cpp}
|
||||
and rename it.
|
||||
|
||||
\li Right-click the project name in \uicontrol Projects and select
|
||||
\uicontrol {Run qmake} to register the new wizard. Basically, qmake
|
||||
generates a fixed list of files to copy. Therefore, you need to run
|
||||
qmake each time the names or locations of the files change.
|
||||
|
||||
\li Open the wizard configuration file, \c wizard.json for editing:
|
||||
|
||||
\list
|
||||
|
||||
\li The following settings determine the type of the wizard and
|
||||
its place in the \uicontrol New dialog:
|
||||
|
||||
\code
|
||||
"version": 1,
|
||||
"kind": "class",
|
||||
"id": "A.Class",
|
||||
"category": "O.C++",
|
||||
\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 class,
|
||||
\c file, or \c project.
|
||||
|
||||
\li \c id is the unique identifier for your wizard. You can
|
||||
use a leading letter to specify the position of the
|
||||
wizard within the \c category.
|
||||
|
||||
\li \c category is the category in which to place the wizard
|
||||
in the list. You can use a leading letter to specify the
|
||||
position of the category in the list in the
|
||||
\uicontrol New dialog.
|
||||
|
||||
\li \c disabled is set to to \c true to hide the wizard. By
|
||||
default, it is set to \c{false}.
|
||||
\endlist
|
||||
|
||||
\li The following settings specify the icon and text that appear in
|
||||
the \uicontrol New dialog:
|
||||
|
||||
\code
|
||||
"trDescription": "Creates a C++ header and a source file for a new class that you can add to a C++ project.",
|
||||
"trDisplayName": "C++ Class",
|
||||
"trDisplayCategory": "C++",
|
||||
"icon": "../../global/genericfilewizard.png",
|
||||
"featuresRequired": [ "Plugin.CppEditor" ],
|
||||
\endcode
|
||||
|
||||
\list
|
||||
|
||||
\li \c trDescription appears in the right-most panel when
|
||||
\c trDisplayCategory is selected.
|
||||
|
||||
\li \c trDisplayName appears in the middle panel when
|
||||
\c trDisplayCategory is selected.
|
||||
|
||||
\li \c trDisplayCategory appears in the \uicontrol New dialog,
|
||||
under \uicontrol Projects.
|
||||
|
||||
\li \c icon appears next to the \c trDisplayName in the middle
|
||||
panel when \c trDisplayCategory is selected. We recommend
|
||||
that you specify the path relative to the wizard.json file,
|
||||
but you can also use an absolute path.
|
||||
|
||||
\li \c featuresRequired specifies the \QC features that the
|
||||
wizard depends on. If a required feature is missing, the
|
||||
wizard is hidden. For example, if the CppEditor plugin is
|
||||
disabled, the C++ Class wizard is hidden.
|
||||
|
||||
\li \c featuresPreferred specifies the build and run kits to
|
||||
preselect.
|
||||
|
||||
\li \c platformIndependent is set to \c true if the wizard is
|
||||
supported by all target platforms. By default, it is set to
|
||||
\c{false}.
|
||||
|
||||
\endlist
|
||||
|
||||
\li The \c options section contains an array of objects with \e key
|
||||
and \e value attributes. You can define your own variables to
|
||||
use in the configuration and template source files, in addition
|
||||
to the predefined variables. For example, the following
|
||||
variables are used in the C++ class creation wizard:
|
||||
|
||||
\code
|
||||
"options":
|
||||
[
|
||||
{ "key": "TargetPath", "value": "%{Path}" },
|
||||
{ "key": "HdrPath", "value": "%{Path}/%{HdrFileName}" },
|
||||
{ "key": "SrcPath", "value": "%{Path}/%{SrcFileName}" },
|
||||
{ "key": "CN", "value": "%{JS: Cpp.className('%{Class}')}" },
|
||||
{ "key": "Base", "value": "%{JS: ( '%{BaseCB}' === '' ) ? '%{BaseEdit}' : '%{BaseCB}'}" },
|
||||
{ "key": "isQObject", "value": "%{JS: ('%{Base}' === 'QObject' || '%{Base}' === 'QWidget' || '%{Base}' === 'QMainWindow' || '%{Base}' === 'QDeclarativeItem' || '%{Base}' === 'QQuickItem' ) ? 'yes' : ''}" },
|
||||
{ "key": "GUARD", "value": "%{JS: Cpp.classToHeaderGuard('%{Class}', '%{JS: Util.preferredSuffix('text/x-c++hdr')}')}" },
|
||||
{ "key": "SharedDataInit", "value": "%{JS: ('%{IncludeQSharedData}') ? 'data(new %{CN}Data)' : '' }" }
|
||||
],
|
||||
\endcode
|
||||
|
||||
This section is optional. For more examples of variables, see
|
||||
the wizard.json files for other wizards.
|
||||
|
||||
\li The \c pages section specifies the wizard pages. The pages
|
||||
used depend on the wizard type. You can add standard pages to
|
||||
wizards or create new pages using the available widgets. The
|
||||
following settings specify the display name, title, and type of
|
||||
the page:
|
||||
|
||||
\code
|
||||
"pages":
|
||||
[
|
||||
{
|
||||
"trDisplayName": "Define Class",
|
||||
"trShortTitle": "Details",
|
||||
"typeId": "Fields",
|
||||
"data" :
|
||||
[
|
||||
{
|
||||
"name": "Class",
|
||||
"trDisplayName": "Class name:",
|
||||
"mandatory": true,
|
||||
"type": "LineEdit",
|
||||
"data": { "validator": "(?:(?:[a-zA-Z_][a-zA-Z_0-9]*::)+[a-zA-Z_][a-zA-Z_0-9]*|)" }
|
||||
},
|
||||
...
|
||||
]
|
||||
\endcode
|
||||
|
||||
\list
|
||||
|
||||
\li \c typeId specifies the page to use: \c Fields, \c File,
|
||||
\c Form, \c Kits, \c Project, or \c Summary. Full page
|
||||
ID, as used in the code, consists of the \c typeId
|
||||
prefixed with \c {"PE.Wizard.Page."}. For more
|
||||
information, about the pages, see \l{Available Pages}.
|
||||
|
||||
\li \c trDisplayName specifies the title of the page. By
|
||||
default, the page title is used.
|
||||
|
||||
\li \c trShortTitle specifies the title used in the sidebar
|
||||
of the Wizard. By default, the page title is used.
|
||||
|
||||
\li \c trSubTitle specifies the subtitle of the page. By
|
||||
default, the page title is used.
|
||||
|
||||
\li \c index is an integer value that specifies the page ID.
|
||||
It is automatically assigned if you do not set it.
|
||||
|
||||
\li \c enabled is set to \c true to show the page and to
|
||||
\c false to hide it.
|
||||
|
||||
\li \c data specifies the wizard pages. In the C++ wizard,
|
||||
it specifies a \c Fields page and a \c Summary page. The
|
||||
\c Fields page contains the \c CheckBox, \c ComboBox,
|
||||
\c LineEdit, \c PathChooser, and \c Spacer widgets. For
|
||||
more information about the widgets, see
|
||||
\l{Available Widgets}.
|
||||
|
||||
\endlist
|
||||
|
||||
\li The \c generators section specifies the files to be added to the
|
||||
project:
|
||||
|
||||
\code
|
||||
"generators":
|
||||
[
|
||||
{
|
||||
"typeId": "File",
|
||||
"data":
|
||||
[
|
||||
{
|
||||
"source": "file.h",
|
||||
"target": "%{HdrPath}",
|
||||
"openInEditor": true
|
||||
},
|
||||
{
|
||||
"source": "file.cpp",
|
||||
"target": "%{SrcPath}",
|
||||
"openInEditor": true
|
||||
}
|
||||
]
|
||||
\endcode
|
||||
|
||||
\list
|
||||
|
||||
\li \c typeId specifies the type of the generator. Currently,
|
||||
only \c File is supported.
|
||||
|
||||
\li \c data spefices the files to generate. For a each file
|
||||
to be generated, specify the following values:
|
||||
|
||||
\list
|
||||
|
||||
\li \c source specifies the path and filename of the
|
||||
template file relative to the wizard.json file.
|
||||
|
||||
\li \c target specifies the location of the generated
|
||||
file, either absolute or relative to
|
||||
\c %{TargetPath}, which is usually set by one of the
|
||||
wizard pages.
|
||||
|
||||
\li \c openInEditor opens the file in the appropriate
|
||||
editor if it is set to \c{true}.
|
||||
|
||||
\li \c openAsProject opens the project file in \QC if it
|
||||
is set to \c{true}.
|
||||
|
||||
\li \c condition generates the file if the condition
|
||||
returns \c{true}. For more information, see
|
||||
\l{Using Variables in Wizards}.
|
||||
|
||||
\endlist
|
||||
|
||||
\endlist
|
||||
|
||||
\endlist
|
||||
|
||||
\endlist
|
||||
|
||||
\section1 Available Pages
|
||||
|
||||
You can add predefined pages to wizards by specifying them in the \c pages
|
||||
section of a wizard.json file.
|
||||
|
||||
\section2 Field Page
|
||||
|
||||
A Field page has the \c typeId value \c Field and contains widgets. For more
|
||||
information about widget definitions, see \l{Available Widgets}.
|
||||
|
||||
\code
|
||||
"pages":
|
||||
[
|
||||
{
|
||||
"trDisplayName": "Define Class",
|
||||
"trShortTitle": "Details",
|
||||
"typeId": "Fields",
|
||||
"data" :
|
||||
[
|
||||
{
|
||||
"name": "Class",
|
||||
"trDisplayName": "Class name:",
|
||||
"mandatory": true,
|
||||
"type": "LineEdit",
|
||||
"data": { "validator": "(?:(?:[a-zA-Z_][a-zA-Z_0-9]*::)+[a-zA-Z_][a-zA-Z_0-9]*|)" }
|
||||
},
|
||||
...
|
||||
],
|
||||
\endcode
|
||||
|
||||
\section2 File Page
|
||||
|
||||
A File page has the \c typeId value \c File. You can leave out the \c data
|
||||
key or assign an empty object to it.
|
||||
|
||||
\code
|
||||
{
|
||||
"trDisplayName": "Location",
|
||||
"trShortTitle": "Location",
|
||||
"typeId": "File"
|
||||
},
|
||||
\endcode
|
||||
|
||||
The page evaluates \c InitialFileName and \c InitialPath from the wizard to
|
||||
set the initial path and filename. The page sets \c TargetPath to the full
|
||||
path of the file to be created.
|
||||
|
||||
\section2 Form Page
|
||||
|
||||
A Form page has the \c typeId value \c Form. You can leave out the \c data
|
||||
key or assign an empty object to it.
|
||||
|
||||
\code
|
||||
{
|
||||
"trDisplayName": "Choose a Form Template",
|
||||
"trShortTitle": "Form Template",
|
||||
"typeId": "Form"
|
||||
},
|
||||
\endcode
|
||||
|
||||
The page sets \c FormContents to an array of strings with the form contents.
|
||||
|
||||
\section2 Kits
|
||||
|
||||
A Kits page has the \c typeId value \c Kits. The \c data section of a Kits
|
||||
page contains an object with the field \c projectFilePath set.
|
||||
|
||||
\code
|
||||
{
|
||||
"trDisplayName": "Kit Selection",
|
||||
"trShortTitle": "Kits",
|
||||
"typeId": "Kits",
|
||||
"enabled": "%{IsTopLevelProject}",
|
||||
"data": { "projectFilePath": "%{ProFileName}" }
|
||||
},
|
||||
\endcode
|
||||
|
||||
The page evaluates \c Platform to set the platform selected in
|
||||
\uicontrol File > \uicontrol New, \c PreferredFeatures to set the preferred
|
||||
features for the project, and \c RequiredFeatures to set the required
|
||||
features for the project. The feature set is used to determine which kits to
|
||||
display and pre-select for the project.
|
||||
|
||||
\section2 Project
|
||||
|
||||
A Project page has the \c typeId value \c Project. It contains no data or an
|
||||
empty object.
|
||||
|
||||
\code
|
||||
{
|
||||
"trDisplayName": "Project Location",
|
||||
"trShortTitle": "Location",
|
||||
"typeId": "Project"
|
||||
},
|
||||
\endcode
|
||||
|
||||
The page evaluates \c InitialPath to set the initial project path. The page
|
||||
sets \c ProjectDirectory and \c TargetPath to the project directory.
|
||||
|
||||
\section2 Summary
|
||||
|
||||
A Summary page has the \c typeId value \c Summary. It contains no data or
|
||||
an empty object.
|
||||
|
||||
\code
|
||||
{
|
||||
"trDisplayName": "Project Management",
|
||||
"trShortTitle": "Summary",
|
||||
"typeId": "Summary"
|
||||
}
|
||||
\endcode
|
||||
|
||||
The page sets \c IsSubproject to an empty string if this is a toplevel
|
||||
project and to \c yes otherwise. It sets \c VersionControl to the ID of the
|
||||
version control system in use.
|
||||
|
||||
\section1 Available Widgets
|
||||
|
||||
You can add the following widgets on a Field page:
|
||||
|
||||
\list
|
||||
\li Check Box
|
||||
\li Combo Box
|
||||
\li Label
|
||||
\li Line Edit
|
||||
\li Path Chooser
|
||||
\li Spacer
|
||||
\li Text Edit
|
||||
\endlist
|
||||
|
||||
Specify the following settings for each widget:
|
||||
|
||||
\list
|
||||
|
||||
\li \c name specifies the widget name. This name is used as the variable
|
||||
name to access the value again.
|
||||
|
||||
\li \c trDisplayName specifies the label text visible in the UI (if
|
||||
\c span is not \c true).
|
||||
|
||||
\li \c type specifies the type of the widget: \c CheckBox, \c ComboBox,
|
||||
\c Label, \c LineEdit, \c PathChooser, \c Spacer, and \c TextEdit.
|
||||
|
||||
\li \c data specifies settings for the widget:
|
||||
|
||||
\list
|
||||
|
||||
\li \c visible is set to \c true if the widget is visible, otherwise
|
||||
it is set to \c false. By default, it is set to \c true.
|
||||
|
||||
\li \c enabled is set to \c true if the widget is enabled, otherwise
|
||||
it is set to \c false. By default, it is set to \c true.
|
||||
|
||||
\li \c mandatory is set to \c true if this widget must have a value
|
||||
for the \uicontrol Next button to become enabled. By default, it
|
||||
is set to \c true.
|
||||
|
||||
\li \c span is set to hide the label and to span the form. By
|
||||
default, it is set to \c false. For more information, see
|
||||
\l{Using Variables in Wizards}.
|
||||
|
||||
\endlist
|
||||
|
||||
The additional settings available for a particular widget are described
|
||||
in the following sections.
|
||||
|
||||
\endlist
|
||||
|
||||
\section2 Check Box
|
||||
|
||||
\code
|
||||
{
|
||||
"name": "IncludeQObject",
|
||||
"trDisplayName": "Include QObject",
|
||||
"type": "CheckBox",
|
||||
"data":
|
||||
{
|
||||
"checkedValue": "QObject",
|
||||
"uncheckedValue": "",
|
||||
"checked": "%{JS: ('%{BaseCB}' === 'QObject' ) ? 'yes' : ''}"
|
||||
}
|
||||
},
|
||||
\endcode
|
||||
|
||||
\list
|
||||
|
||||
\li \c checkedValue specifies the value to set when the check box is
|
||||
enabled. By default, set to \c 0.
|
||||
|
||||
\li \c uncheckedValue specifies the value to set when the check box is
|
||||
disabled. By default, set to \c 1.
|
||||
|
||||
\li \c checked is set to \c true if the check box is enabled, otherwise
|
||||
\c{false}.
|
||||
|
||||
\endlist
|
||||
|
||||
\section2 Combo Box
|
||||
|
||||
\code
|
||||
{
|
||||
"name": "BaseCB",
|
||||
"trDisplayName": "Base class:",
|
||||
"type": "ComboBox",
|
||||
"data":
|
||||
{
|
||||
"items": [ { "trKey": "<Custom>", "value": "" },
|
||||
"QObject", "QWidget", "QMainWindow", "QDeclarativeItem", "QQuickItem" ]
|
||||
}
|
||||
},
|
||||
\endcode
|
||||
|
||||
\list
|
||||
|
||||
\li \c items specifies a list of items to put into the combo box. The
|
||||
list can contain both JSON objects and plain strings. For JSON
|
||||
objects, define \c trKey and \c value pairs, where the \c trKey is
|
||||
the list item visible to users and \c value contains the data
|
||||
associated with the item.
|
||||
|
||||
\li \c index specifies the index to select when the combo box is
|
||||
enabled. By default, it is set to \c 0.
|
||||
|
||||
\li \c disabledIndex specifies the index to show if the combo box is
|
||||
disabled.
|
||||
|
||||
\endlist
|
||||
|
||||
\section2 Label
|
||||
|
||||
\code
|
||||
{
|
||||
"name": "LabelQQC_1_0",
|
||||
"type": "Label",
|
||||
"span": true,
|
||||
"visible": "%{( '%{CS}' === 'QQC_1_0' ) ? 'yes' : ''}",
|
||||
"data":
|
||||
{
|
||||
"wordWrap": true,
|
||||
"trText": "Creates a deployable Qt Quick 2 application using Qt Quick Controls. Requires Qt 5.1 or newer."
|
||||
}
|
||||
},
|
||||
\endcode
|
||||
|
||||
\list
|
||||
|
||||
\li \c wordWrap is set to \c true to enable word wrap. By default, it is
|
||||
set to \c{false}.
|
||||
|
||||
\li \c trText contains the label text to display.
|
||||
|
||||
\endlist
|
||||
|
||||
\section2 Line Edit
|
||||
|
||||
\code
|
||||
{
|
||||
"name": "Class",
|
||||
"trDisplayName": "Class name:",
|
||||
"mandatory": true,
|
||||
"type": "LineEdit",
|
||||
"data": { "validator": "(?:(?:[a-zA-Z_][a-zA-Z_0-9]*::)+[a-zA-Z_][a-zA-Z_0-9]*|)" }
|
||||
},
|
||||
{
|
||||
"name": "BaseEdit",
|
||||
"type": "LineEdit",
|
||||
"enabled": "%{JS: ( '%{BaseCB}' === '' ) ? 'yes' : ''}",
|
||||
"mandatory": false,
|
||||
"data":
|
||||
{
|
||||
"trText": "%{BaseCB}",
|
||||
"trDisabledText": "%{BaseCB}"
|
||||
}
|
||||
},
|
||||
\endcode
|
||||
|
||||
\list
|
||||
|
||||
\li \c trText specifies the default text to display.
|
||||
|
||||
\li \c trDisabledText specifies the text to display in a disabled field.
|
||||
|
||||
\li \c trPlaceholder specifies the placeholder text.
|
||||
|
||||
\li \c validator specifies a QRegularExpression to validate the line
|
||||
edit against.
|
||||
|
||||
\li \c fixup specifies a variable that is used to fix up the string.
|
||||
For example, to turn the first character in the line edit to upper
|
||||
case.
|
||||
|
||||
\endlist
|
||||
|
||||
\section2 Path Chooser
|
||||
|
||||
\code
|
||||
{
|
||||
"name": "Path",
|
||||
"type": "PathChooser",
|
||||
"trDisplayName": "Path:",
|
||||
"mandatory": true,
|
||||
"data":
|
||||
{
|
||||
"kind": "existingDirectory",
|
||||
"basePath": "%{InitialPath}",
|
||||
"path": "%{InitialPath}"
|
||||
}
|
||||
},
|
||||
\endcode
|
||||
|
||||
\list
|
||||
|
||||
\li \c path specifies the selected path.
|
||||
|
||||
\li \c basePath specifies a base path that lookups are relative to.
|
||||
|
||||
\li \c kind defines what to look for: \c existingDirectory,
|
||||
\c directory, \c file, \c saveFile, \c existingCommand, \c command,
|
||||
or \c any.
|
||||
|
||||
\endlist
|
||||
|
||||
\section2 Spacer
|
||||
|
||||
\code
|
||||
{
|
||||
"name": "Sp1",
|
||||
"type": "Spacer",
|
||||
"data":
|
||||
{
|
||||
"factor": 2
|
||||
}
|
||||
},
|
||||
\endcode
|
||||
|
||||
The \c factor setting specifies the factor (an integer) to multiply the
|
||||
layout spacing for this spacer.
|
||||
|
||||
\section2 Text Edit
|
||||
|
||||
\code
|
||||
{
|
||||
"name": "TextField",
|
||||
"type": "TextEdit",
|
||||
"data" :
|
||||
{
|
||||
"trText": "This is some text",
|
||||
"richText": true
|
||||
}
|
||||
}
|
||||
\endcode
|
||||
|
||||
\list
|
||||
|
||||
\li \c trText specifies the text to display.
|
||||
|
||||
\li \c trDisabledText specifies the text to display when the text edit
|
||||
is disabled.
|
||||
|
||||
\li \c richText is set to \c true for rich text, otherwise \c{false}.
|
||||
|
||||
\endlist
|
||||
|
||||
*/
|
@@ -24,7 +24,7 @@
|
||||
|
||||
/*!
|
||||
\contentspage {Qt Creator Manual}
|
||||
\previouspage creator-project-wizards.html
|
||||
\previouspage creator-project-wizards-json.html
|
||||
\page creator-project-wizards-xml.html
|
||||
\nextpage creator-version-control.html
|
||||
|
||||
@@ -33,55 +33,29 @@
|
||||
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
|
||||
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"
|
||||
|
||||
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:
|
||||
Files can be generated by using either \l{Processing Template Files}
|
||||
{templates} or \l{Using Generator Scripts}{generator scripts}, where a
|
||||
script is called to create the files.
|
||||
|
||||
\list 1
|
||||
\note The generator option mainly exists to accommodate existing generator
|
||||
scripts or cases where complicated algorithmic logic is required when
|
||||
generating files. Writing cross-platform scripts is inherently difficult,
|
||||
and therefore, it is not recommended for new wizards.
|
||||
|
||||
\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}.
|
||||
XML-based wizard template directories contain an XML configuration file
|
||||
called wizard.xml, the template source files, and optionally, the generator
|
||||
script.
|
||||
|
||||
\li Generator script, where a script is called to create the files.
|
||||
\section1 Creating XML-Based Project Wizards
|
||||
|
||||
\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:
|
||||
To create an XML-based project wizard:
|
||||
|
||||
\list 1
|
||||
|
||||
@@ -91,7 +65,7 @@
|
||||
\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:
|
||||
in the \uicontrol New dialog:
|
||||
|
||||
\code
|
||||
|
||||
@@ -120,16 +94,16 @@
|
||||
\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.
|
||||
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 \gui New dialog.
|
||||
list in the \uicontrol New dialog.
|
||||
|
||||
\endlist
|
||||
|
||||
\li The following code specifies the icon and text that appear in the
|
||||
\gui New dialog:
|
||||
\uicontrol New dialog:
|
||||
|
||||
\code
|
||||
|
||||
@@ -145,8 +119,8 @@
|
||||
|
||||
\list
|
||||
|
||||
\li \c displayCategory appears in the \gui New dialog, under
|
||||
\gui Projects.
|
||||
\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.
|
||||
@@ -187,7 +161,7 @@
|
||||
|
||||
\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
|
||||
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
|
||||
@@ -560,12 +534,12 @@
|
||||
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++ >
|
||||
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 \gui {File Naming}.
|
||||
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.
|
||||
|
@@ -26,17 +26,23 @@
|
||||
\contentspage {Qt Creator Manual}
|
||||
\previouspage creator-project-qmake-libraries.html
|
||||
\page creator-project-wizards.html
|
||||
\nextpage creator-project-wizards-xml.html
|
||||
\nextpage creator-project-wizards-json.html
|
||||
|
||||
\title Adding New Custom Wizards
|
||||
|
||||
If you have a team working on a large application or several applications,
|
||||
you might want to standardize the way the team members create projects
|
||||
and classes.
|
||||
you might want to standardize the way the team members create projects,
|
||||
classes, and files.
|
||||
|
||||
You can copy the wizard templates in the template folders to create your own
|
||||
project and class wizards. They are displayed in the \uicontrol New dialog that
|
||||
opens when you choose \uicontrol {File > New File or Project}.
|
||||
project, class, and file wizards. They are displayed in the \uicontrol New
|
||||
dialog that opens when you choose \uicontrol {File > New File or Project}.
|
||||
|
||||
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.
|
||||
|
||||
\section1 Wizard Types
|
||||
|
||||
In a project wizard, you can specify the files needed in a project.
|
||||
You can add wizard pages to allow developers to specify settings for the
|
||||
@@ -45,10 +51,51 @@
|
||||
In a class wizard, you can allow developers to specify the class name, base
|
||||
class, and header and source files for the class.
|
||||
|
||||
In a file wizard, you can allow developers to specify the type and location
|
||||
of the file.
|
||||
|
||||
You can create either JSON-based or XML-based wizards. We recommend creating
|
||||
JSON-based wizards for new projects.
|
||||
JSON-based wizards for new projects. For more information, see:
|
||||
|
||||
\list
|
||||
\li \l{Adding JSON-Based Wizards}
|
||||
\li \l{Adding XML-Based Wizards}
|
||||
\endlist
|
||||
|
||||
The following table summarizes the wizards you can create:
|
||||
|
||||
\table
|
||||
\header
|
||||
\li Wizard Type
|
||||
\li JSON-Based
|
||||
\li XML-Based
|
||||
\row
|
||||
\li Class
|
||||
\li \image ok
|
||||
\li \image ok
|
||||
\row
|
||||
\li File
|
||||
\li \image ok
|
||||
\li \image ok
|
||||
\row
|
||||
\li Project
|
||||
\li \image ok
|
||||
\li \image ok
|
||||
\endtable
|
||||
|
||||
\section1 Locating Wizards
|
||||
|
||||
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
|
||||
|
||||
*/
|
||||
|
@@ -144,6 +144,7 @@
|
||||
\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
|
||||
|
Reference in New Issue
Block a user