Commit 3b86184d authored by Leena Miettinen's avatar Leena Miettinen Committed by Leena Miettinen

Doc: adding JSON-based custom wizards

Task-number: QTCREATORBUG-13642
Change-Id: Ie3af0d4bdef33364cc442449ccfb5e770c0c3a99
Reviewed-by: default avatarTobias Hunger <tobias.hunger@theqtcompany.com>
parent 77fa5688
This diff is collapsed.
......@@ -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
\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
\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.
They contain an XML configuration file called wizard.xml, the template
source files, and optionally, the generator script.
XML-based wizard template directories contain an XML configuration file
called wizard.xml, the template source files, and optionally, the generator
script.
\section1 Creating Project Wizards
\section1 Creating XML-Based 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
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment