forked from qt-creator/qt-creator
Add information about project wizards and creating new ones.
Task-number: QTCREATORBUG-863 Reviewed-by: Friedemann Kleint
This commit is contained in:
Leena Miettinen
committed by
Oswald Buddenhagen
Oswald Buddenhagen
parent
2e77722656
commit
875cfd2a52
BIN
doc/images/qtcreator-custom-project-wizards.png
Normal file
BIN
doc/images/qtcreator-custom-project-wizards.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 25 KiB |
@@ -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
|
||||
|
||||
*/
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user