Add information about project wizards and creating new ones.

Task-number: QTCREATORBUG-863
Reviewed-by: Friedemann Kleint

doc/qtcreator.qdoc

@@ -1073,15 +1073,39 @@
 
     \title Creating a Project
 
+    You use wizards to create and import several types of projects and files, such
+    as Qt GUI or console applications and Qt Quick applications. You can also use
+    wizards to add individual files to your projects. For example, you can create
+    the following types of files:
+
+    \list
+
+        \o Qt resource files, which allow you to store binary files in the
+        application executable
+
+        \o \QD forms and Qt QML files, which specify parts of application user
+        interfaces
+
+        \o C++ class, source, or header files
+
+    \endlist
+
+    The wizards prompt you to enter the settings needed
+    for that particular type of project and create the necessary files for you.
+
+    \image qtcreator-new-project.png
+
+    \section1 Using Project Wizards
+
     To create a new project:
     \list 1
         \o Select \gui File > \gui{New File or Project} and select the type of your
            project.
 
            The contents of the following dialogs depend on the project type.
+           Follow the instructions of the wizard.
            This example uses \gui {Qt Gui Application}.
 
-           \image qtcreator-new-project.png
         \o Name the project and set its path. To select the path from a
            directory tree, click \gui Browse.
 
@@ -1104,6 +1128,262 @@
            \image qtcreator-new-project-summary.png
     \endlist
 
+    \section1 Adding New Project 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 use the wizard templates in the \c {share/qtcreator/templates/wizards}
+    folder to create your own project and class wizards. Qt Creator looks in the
+    folder and adds all wizards defined in wizard.xml files to the \gui New dialog
+    that opens when you select \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
+    projcet.
+
+    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_example.xml as wizard.xml in the helloworld
+    and listmodels folders. After you restart Qt Creator, 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"
+
+    \section2 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 The following code specifies the files to add to the project:
+
+        \code
+
+        <files>
+            <file source="main.cpp"/>
+            <file source="project.pro" target="%ProjectName%.pro"/>
+
+        \endcode
+
+        \list
+
+            \o \c source specifies the file to copy to the project. The files must be
+            located in the wizard folder.
+
+            \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.
+
+        \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
+
+    \section2 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%"/>
+            <file source="listmodel.h" target="%ClassName:l%.%CppHeaderSuffix%"/>
+        </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%} is replaced by the default source suffix, which
+        is defined in Qt Creator 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}. Here, the filename would
+        become myclass.h.
+
+        \endlist
+
+        \o The following code creates a page that allows users to select the class
+        name, base class, and header and source files for the class:
+
+        \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
+
 */