/**************************************************************************** ** ** Copyright (c) 2013 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 index.html \previouspage creator-project-qmake-libraries.html \page creator-project-wizards.html \nextpage creator-version-control.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\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 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" \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/QtProject/qtcreator/templates/wizards} \o \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: \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 \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. This attribute is optional. Use the value \c qt4project to add Qt 4 specific pages. \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 console.png Creates a hello-world-project with custom message. Erzeugt ein Hello-Welt-Projekt mit einer Nachricht. Hello World; Hallo Welt; Custom Projects Benutzerdefinierte Projekte \endcode \list \o \c displayCategory appears in the \gui New dialog, under \gui Projects. \o \c icon appears next to the \c displayName in the middle panel when \c displayCategory is selected. \o \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 \o Files to be added to the project: \list \o Template-based: The following code specifies the files to add to the project: \code \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 \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 Hello World Parameters Hallo Welt Parameter Hello world message: Hallo-Welt-Nachricht: \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 Creates a QAbstractListModel implementation. Erzeugt eine Implementierung von QAbstractListModel. QAbstractListModel implementation Implementierung von QAbstractListModel Custom Classes Benutzerdefinierte Klassen \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 \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 ListModel parameters Parameter des ListModel Class name: Klassenname: Data type: Datentyp: \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}. \o \c {%CurrentDate%} is replaced by the current date in the format \c {yyyy-MM-dd}. \o \c {%CurrentTime%} is replaced by the current time in the short format of the locale. \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 %ClassName% cannot be used as class name. %ClassName% kann nicht als Klassenname verwendet werden. \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{} 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 overridden 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%. */