creator-projects-custom-wizards.qdoc 19.8 KB
Newer Older
1
2
3
4
/****************************************************************************
**
** This file is part of Qt Creator
**
5
** Copyright (c) 2012 Nokia Corporation and/or its subsidiary(-ies).
6
**
Eike Ziller's avatar
Eike Ziller committed
7
** Contact: http://www.qt-project.org/
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
**
**
** 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.
**
**
****************************************************************************/

// **********************************************************************
// 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
28
    \previouspage creator-project-qmake-libraries.html
29
    \page creator-project-wizards.html
30
    \nextpage creator-version-control.html
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

    \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
50
51
    \c {\share\qtcreator\templates\wizards\helloworld} and
    \c {\share\qtcreator\templates\wizards\listmodel} folders. After
52
    you restart \QC, the \gui {Custom Classes}
53
54
55
    and \gui {Custom Projects} categories (1) appear in the \gui New dialog. For
    each category, an icon (2), a display name (3), and a description (4) are
    displayed.
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

    \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.

130
131
            \o  \c class specifies the type of the project. This attribute is
                optional. Use the value \c qt4project to add Qt 4 specific pages.
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165

            \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

166
167
            \o  \c displayCategory appears in the \gui New dialog, under
                \gui Projects.
168

169
170
            \o  \c icon appears next to the \c displayName in the middle panel
                when \c displayCategory is selected.
171

172
173
            \o  \c description appears in the right-most panel when
                \c displayCategory is selected.
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442

                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}.

443
444
445
446
447
448
        \o  \c {%CurrentDate%} is replaced by the current date in the format
            \c {yyyy-MM-dd}.

        \o  \c {%CurrentTime%} is replaced by the current time in the short
            format of the locale.

449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
    \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%.

*/