diff --git a/doc/images/qtcreator-custom-project-wizards.png b/doc/images/qtcreator-custom-project-wizards.png new file mode 100644 index 00000000000..fa96ec606f4 Binary files /dev/null and b/doc/images/qtcreator-custom-project-wizards.png differ diff --git a/doc/qtcreator.qdoc b/doc/qtcreator.qdoc index 4183fb911f7..5e4a41b4ace 100644 --- a/doc/qtcreator.qdoc +++ b/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 + + + + \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 + + 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 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 + + + + + + \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 + + + 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 + + \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 + + + + 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%} 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 + + + + 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 + */