Commit 875cfd2a authored by Leena Miettinen's avatar Leena Miettinen Committed by Oswald Buddenhagen
Browse files

Add information about project wizards and creating new ones.

Task-number: QTCREATORBUG-863
Reviewed-by: Friedemann Kleint
parent 2e777226
......@@ -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
*/
......
Supports Markdown
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