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>

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%.
+
+*/