diff options
author | Leena Miettinen <riitta-leena.miettinen@nokia.com> | 2011-09-27 11:55:44 +0200 |
---|---|---|
committer | Leena Miettinen <riitta-leena.miettinen@nokia.com> | 2011-09-27 15:56:06 +0200 |
commit | c78528dce8d687af8dfffeb459c3f53990cf177e (patch) | |
tree | e78c5ae580c99d093196d17500002a3ac79a26a7 /doc/src/projects/creator-projects-custom-wizards.qdoc | |
parent | 44c107c26797a7a114419b7392b520c8a69c33d7 (diff) | |
download | qt-creator-c78528dce8d687af8dfffeb459c3f53990cf177e.tar.gz |
Doc: move projects mode topics to a separate folder
Change-Id: I031e1f488c4923baea0bddbd24da804f3bb01c95
Reviewed-on: http://codereview.qt-project.org/5611
Reviewed-by: Qt Sanity Bot <qt_sanity_bot@ovi.com>
Reviewed-by: Eike Ziller <eike.ziller@nokia.com>
Diffstat (limited to 'doc/src/projects/creator-projects-custom-wizards.qdoc')
-rw-r--r-- | doc/src/projects/creator-projects-custom-wizards.qdoc | 513 |
1 files changed, 513 insertions, 0 deletions
diff --git a/doc/src/projects/creator-projects-custom-wizards.qdoc b/doc/src/projects/creator-projects-custom-wizards.qdoc new file mode 100644 index 0000000000..a60ae3bef3 --- /dev/null +++ b/doc/src/projects/creator-projects-custom-wizards.qdoc @@ -0,0 +1,513 @@ +/**************************************************************************** +** +** This file is part of Qt Creator +** +** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies). +** +** Contact: Nokia Corporation (info@qt.nokia.com) +** +** +** 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. +** +** If you have questions regarding the use of this file, please contact +** Nokia at info@qt.nokia.com. +** +****************************************************************************/ + +// ********************************************************************** +// 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-os-supported-platforms.html + \page creator-project-wizards.html + \nextpage creator-project-cmake.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 can copy the wizard templates in the template folders to create your own + project and class wizards. They are displayed in the \gui New dialog that + opens when you choose \gui {File > New File or Project}. + + 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 + project. + + In a class wizard, you can allow developers to specify the class name, base + class, and header and source files for the class. + + To see how this works, rename wizard_sample.xml as wizard.xml in the + \c {\share\qtcreator\templates\wizards\listmodel\helloworld} and + \c {\share\qtcreator\templates\wizards\listmodel\listmodels} folders. After + you restart \QC, the \gui {Custom Classes} + and \gui {Custom Projects} categories appear in the \gui New dialog. + + \image qtcreator-custom-project-wizards.png "The New dialog with custom projects and classes" + + \section1 Overview of Custom Wizards + + A custom wizard defines the user interface of a wizard page. The values the + user enters in the wizard are assigned field names. Field name and value + pairs are then passed to the file creation process. File creation can happen + in the following ways: + + \list 1 + + \o 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}. + + \o 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 + + \o \c{share/qtcreator/templates/wizards} + + \o the local user's configuration folder, + \c{$HOME/.config/Nokia/qtcreator/templates/wizards} + + \o \c{%APPDATA%\Nokia\qtcreator\templates\wizards} + + \endlist + + They contain an XML configuration file called wizard.xml, the template + source files, and optionally, the generator script. + + \section1 Creating Project Wizards + + To create a project wizard: + + \list 1 + + \o Make a copy of the \c {share/qtcreator/templates/wizards/helloworld} + or \c {share/qtcreator/templates/wizards/listmodel} folder. + + \o Modify the wizard_example.xml file. + + \o The following code determines the type of the wizard and its place + in the \gui New dialog: + + \code + + <wizard version="1" kind="project" + class="qt4project" firstpage="10" + id="A.HelloWorld" category="B.CustomProjects"> + + \endcode + + \list + + \o \c version is the version of the file contents. Do not modify + this value. + + \o \c kind specifies the type of the wizard: \c project or + \c class. + + \o \c class specifies the type of the project. Currently the only + available type is \c qt4project, which specifies a Qt console + project. + + \o \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. + + \o \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. + + \o \c category is the category in which to place the wizard in the + list. The letter specifies the position of the category in the + list in the \gui New dialog. + + \endlist + + \o The following code specifies the icon and text that appear in the + \gui New dialog: + + \code + + <icon>console.png</icon> + <description>Creates a hello-world-project with custom message.</description> + <description xml:lang="de">Erzeugt ein Hello-Welt-Projekt mit einer Nachricht.</description> + <displayname>Hello World</displayname>; + <displayname xml:lang="de">Hallo Welt</displayname>; + <displaycategory>Custom Projects</displaycategory> + <displaycategory xml:lang="de">Benutzerdefinierte Projekte</displaycategory> + + \endcode + + \list + + + \o \c icon appears next to the \c displayName. + + \o \c description appears at the bottom of the \gui New dialog when + you select the display name. + + \o \c displayName appears in the \gui New dialog, under the + \c displayCategory. + + 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 + + \o Files to be added to the project: + + \list + + \o Template-based: The following code specifies the files to add to + the project: + \code + <files> + <file source="main.cpp" openeditor="true" /> + <file source="project.pro" target="%ProjectName%.pro" openproject="true" /> + <file source="icon.png" target="%ProjectName%.png" binary="true" /> + \endcode + + \list + + \o \c source specifies the file to copy to the project. The + files must be located in the wizard folder. + + \o \c openeditor indicates that the file is to be opened in an + editor after the wizard has finished. + + \o \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. + + \o \c target specifies the new filename for the file. The + \c {%ProjectName%} variable is replaced with the string that + users specify in the \gui Name field on the first page of + the wizard. + + \o \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}. + + \o Generator-script: The following code specifies that the script + \c generate.pl is to be used to create the files: + + \code + <generatorscript binary="generate.pl"> + <argument value="--class-name=%ClassName%"/> + <argument value="--project-name=%ProjectName%"/> + <argument value="--header-suffix=%CppHeaderSuffix%" omit-empty="true"/> + <argument value="--source-suffix=%CppSourceSuffix%" omit-empty="true"/> + <argument value="--description=%Description%" omit-empty="true" write-file="true"/> + </generatorscript> + \endcode + + In each argument, the field placeholders are replaced by the + field values. There are additional boolean attributes which give + fine-grained control: + + \list + + \o \c omit-empty specifies that complete argument is to be + omitted when all placeholders expand to empty values. In + the above example, the option \c --source-suffix will + not be passed to the script if the value is empty. + + \o \c write-file indicates that instead of the expanded + value, the value will be written to a temporary file and + its file name will be passed to the script instead. This + is useful for multi-line text fields. + + \endlist + + See also \l{Using Generator Scripts}. + + \endlist + + \o 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!" /> + <fielddescription>Hello world message:</fielddescription> + <fielddescription xml:lang="de">Hallo-Welt-Nachricht:</fielddescription> + </field> + </fields> + \endcode + + \list + + \o \c fieldpagetitle specifies the title of the page. + + \o \c field specifies whether the field is mandatory (\c true or + \c false). You can use the value of the \c name field as a + variable in other files (for example, \c {%MESSAGE%}. + + \o \c fieldcontrol specifies the field. \c class specifies the + field type. You can use interface objects from the QWidget class + to create fields. This example uses QLineEdit to create an input + field. + + \o \c validator specifies a regular expression to check the + characters allowed in the field. + + \o \c defaulttext specifies text that appears in the field by + default. + + \o \c fielddescription specifies the field name that appears on the + wizard page. + + \endlist + + \endlist + + \section1 Creating Class Wizards + + The widget.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 + + \o The following code specifies settings for the wizard: + + \code + + <wizard version="1" kind="class" id="A.ListModel" category="B.CustomClasses"> + + <description>Creates a QAbstractListModel implementation.</description> + <description xml:lang="de">Erzeugt eine Implementierung von QAbstractListModel.</description> + + <displayname>QAbstractListModel implementation</displayname> + <displayname xml:lang="de">Implementierung von QAbstractListModel</displayname> + + <displaycategory>Custom Classes</displaycategory> + <displaycategory xml:lang="de">Benutzerdefinierte Klassen</displaycategory> + + \endcode + + For more information about the elements and their values, see + \l {Creating Project Wizards}. + + \o 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 + + \o \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. + + \o \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" combochoices="QString,int" defaultindex="0" /> + + <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. \c combochoices specifies the options in the combobox + and \c defaultindex specifies that QString is the default value. + + \endlist + + \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 + + \o \c{l} for lower case. + + \o \c{u} for upper case. + + \o \c{c} for upper case initial letter ("project" > "Project"). + + \endlist + + 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 profile 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. + + \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 + + \o \c {%ProjectName%} is replaced by the name of the project in the + case of project wizards. + + \o \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. + + \o \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%. + + \o \c {%CppSourceSuffix%} is replaced by the default source suffix, + which is defined in \QC in \gui {Tools > Options > C++ > + File Naming}. For example, if users enter \bold MyClass, the + filename becomes myclass.cpp when the project is created. + + \o \c {%CppHeaderSuffix%} is replaced by the default header suffix, + which is also defined in \gui {File Naming}. + + \endlist + + \section1 Validating User Input + + You can specify validation rules for user input. The rules consist of a + Boolean JavaScript expression and an error message. The placeholders in them + are replaced with values before they are evaluated or displayed. + + Consider the following rule used in the \l{Creating Class Wizards} example: + + \code + <validationrules> + <validationrule condition='"%ClassName%" != "QAbstractListModel"'> + <message>%ClassName% cannot be used as class name.</message> + <message xml:lang="de">%ClassName% kann nicht als Klassenname verwendet werden.</message> + </validationrule> + </validationrules> + \endcode + + It ensures that the class name entered by the user does not match the name + of the base class. If the validation fails, a red label displaying the + message appears at the bottom of the wizard page. + + \section1 Using Generator Scripts + + The values entered in the wizard page are passed to the script + as command line arguments as defined by the wizard configuration file. + + In addition, the script must implement a \c{--dry-run} command line option. + + \QC needs to know the file names before the files are created to check + whether files with identical names already exist, for example. Therefore, + script file generation is a two-step process: + + \list 1 + + \o Determine file names and attributes: The script is called with the + command line \c{--dry-run} option and the field values. It then prints + the relative path names of the files it intends to create, followed by + comma-separated attributes matching those of the \c{<file>} element, for + example: + + \code + myclass.cpp,openeditor + myclass.h,openeditor + myproject.pro,openproject + \endcode + + \o Create files: The script is called with the parameters only in the + working directory. It then actually creates the files. If directories + are needed, the script should create them, too. + + \endlist + + The \c{scriptgeneratedproject} sample wizard illustrates the usage. + A typical script invocation for this example (obtained by running \QC with + \c{--customwizard-verbose}) looks as follows: + + \code + generate.pl --class-name=TestClass --project-name=TestProject --header-suffix=h --source-suffix=cpp --description=/tmp/qtcreatorj26629.txt + \endcode + + By default, the scripts are run in the directory corresponding to + \c %TargetPath%. This can be overriden by specifying the attribute + \c workingdirectory on the element \c generatorscript. For example, if the + script creates the project directory by itself, %Path% can be specified. In + that case, \c --dry-run should output the correct relative paths or absolute + paths constructed using the value of \c %Path%. + +*/ |