Skip to content
GitLab
Menu
Projects
Groups
Snippets
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in
Toggle navigation
Menu
Open sidebar
Tobias Hunger
qt-creator
Commits
b9c56431
Commit
b9c56431
authored
Sep 03, 2010
by
Leena Miettinen
Browse files
Doc - Add information about creating custom wizards.
Reviewed-by: Friedemann Kleint
parent
c4e287f0
Changes
1
Hide whitespace changes
Inline
Side-by-side
doc/qtcreator.qdoc
View file @
b9c56431
...
...
@@ -52,6 +52,7 @@
\
o
\
l
{
Setting
Up
Development
Environment
for
Maemo
}
\
o
\
l
{
Setting
Up
Development
Environment
for
Symbian
}
\
o
\
l
{
Managing
Sessions
}
\
o
\
l
{
Adding
New
Custom
Wizards
}
\
endlist
\
o
\
l
{
Using
the
Editor
}
\
list
...
...
@@ -1709,7 +1710,7 @@
\
contentspage
index
.
html
\
previouspage
creator
-
project
-
managing
.
html
\
page
creator
-
project
-
creating
.
html
\
nextpage
creator
-
project
-
qmake
.
html
\
nextpage
creator
-
project
-
wizards
.
html
\
title
Creating
a
Project
...
...
@@ -1771,6 +1772,9 @@
\
image
qtcreator
-
new
-
project
-
summary
.
png
\
endlist
You
can
create
your
own
project
and
class
wizards
.
For
more
information
,
see
\
l
{
Adding
New
Custom
Wizards
}.
\
section1
Displaying
Additional
File
Types
in
Projects
Pane
Qt
Creator
determines
whether
to
display
files
from
the
project
folder
...
...
@@ -1790,20 +1794,28 @@
This
also
makes
the
files
available
in
the
\
gui
Locator
.
\
section1
Adding
New
Project
Wizards
*/
/*
!
\
contentspage
index
.
html
\
previouspage
creator
-
project
-
creating
.
html
\
page
creator
-
project
-
wizards
.
html
\
nextpage
creator
-
project
-
qmake
.
html
\
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
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
}.
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
proj
c
et
.
proje
c
t
.
In
a
class
wizard
,
you
can
allow
developers
to
specify
the
class
name
,
base
class
,
and
header
and
source
files
for
the
class
.
...
...
@@ -1814,7 +1826,45 @@
\
image
qtcreator
-
custom
-
project
-
wizards
.
png
"The New dialog with custom projects and classes"
\
section2
Creating
Project
Wizards
\
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:
...
...
@@ -1891,31 +1941,59 @@
\endlist
\
o
The
following
code
specifies
the
files
to
add
to
the
project
:
\
code
\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" />
\endcode
\list
\
list
\o \c source specifies the file to copy to the project. The files must be
located in the wizard folder.
\
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
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 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
.
\o \c openproject indicates that the file is a project file which is to be opened
after the wizard has finished.
\
o
\
c
openeditor
indicates
that
the
file
is
to
be
opened
in
an
editor
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:
...
...
@@ -1958,7 +2036,7 @@
\
endlist
\
section
2
Creating
Class
Wizards
\
section
1
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
.
...
...
@@ -2012,6 +2090,7 @@
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
.
...
...
@@ -2052,12 +2131,81 @@
\
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
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
.
Qt
Creator
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
Qt
Creator
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
*/
/*
!
\
contentspage
index
.
html
\
previouspage
creator
-
project
-
creating
.
html
\
previouspage
creator
-
project
-
wizards
.
html
\
page
creator
-
project
-
qmake
.
html
\
nextpage
creator
-
project
-
cmake
.
html
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
.
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment