source: trunk/doc/src/examples/classwizard.qdoc@ 560

Last change on this file since 560 was 2, checked in by Dmitry A. Kuminov, 16 years ago

Initially imported qt-all-opensource-src-4.5.1 from Trolltech.

File size: 8.3 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4** Contact: Qt Software Information ([email protected])
5**
6** This file is part of the documentation of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial Usage
10** Licensees holding valid Qt Commercial licenses may use this file in
11** accordance with the Qt Commercial License Agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and Nokia.
14**
15** GNU Lesser General Public License Usage
16** Alternatively, this file may be used under the terms of the GNU Lesser
17** General Public License version 2.1 as published by the Free Software
18** Foundation and appearing in the file LICENSE.LGPL included in the
19** packaging of this file. Please review the following information to
20** ensure the GNU Lesser General Public License version 2.1 requirements
21** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
22**
23** In addition, as a special exception, Nokia gives you certain
24** additional rights. These rights are described in the Nokia Qt LGPL
25** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
26** package.
27**
28** GNU General Public License Usage
29** Alternatively, this file may be used under the terms of the GNU
30** General Public License version 3.0 as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL included in the
32** packaging of this file. Please review the following information to
33** ensure the GNU General Public License version 3.0 requirements will be
34** met: http://www.gnu.org/copyleft/gpl.html.
35**
36** If you are unsure which license is appropriate for your use, please
37** contact the sales department at [email protected].
38** $QT_END_LICENSE$
39**
40****************************************************************************/
41
42/*!
43 \example dialogs/classwizard
44 \title Class Wizard Example
45
46 The License Wizard example shows how to implement linear
47 wizards using QWizard.
48
49 \image classwizard.png Screenshot of the Class Wizard example
50
51 Most wizards have a linear structure, with page 1 followed by
52 page 2 and so on until the last page. Some wizards are more
53 complex in that they allow different traversal paths based on the
54 information provided by the user. The
55 \l{dialogs/licensewizard}{License Wizard} example shows how to
56 create such wizards.
57
58 The Class Wizard example consists of the following classes:
59
60 \list
61 \o \c ClassWizard inherits QWizard and provides a
62 three-step wizard that generates the skeleton of a C++ class
63 based on the user's input.
64 \o \c IntroPage, \c ClassInfoPage, \c CodeStylePage, \c
65 OutputFilesPage, and \c ConclusionPage are QWizardPage
66 subclasses that implement the wizard pages.
67 \endlist
68
69 \section1 ClassWizard Class Definition
70
71 \image classwizard-flow.png The Class Wizard pages
72
73 We will see how to subclass QWizard to implement our own wizard.
74 The concrete wizard class is called \c ClassWizard and provides
75 five pages:
76
77 \list
78 \o The first page is an introduction page, telling the user what
79 the wizard is going to do.
80 \o The second page asks for a class name and a base class, and
81 allows the user to specify whether the class should have a \c
82 Q_OBJECT macro and what constructors it should provide.
83 \o The third page allows the user to set some options related to the code
84 style, such as the macro used to protect the header file from
85 multiple inclusion (e.g., \c MYDIALOG_H).
86 \o The fourth page allows the user to specify the names of the
87 output files.
88 \o The fifth page is a conclusion page.
89 \endlist
90
91 Although the program is just an example, if you press \gui Finish
92 (\gui Done on Mac OS X), actual C++ source files will actually be
93 generated.
94
95 \section1 The ClassWizard Class
96
97 Here's the \c ClassWizard definition:
98
99 \snippet examples/dialogs/classwizard/classwizard.h 0
100
101 The class reimplements QDialog's \l{QDialog::}{accept()} slot.
102 This slot is called when the user clicks \gui{Finish}.
103
104 Here's the constructor:
105
106 \snippet examples/dialogs/classwizard/classwizard.cpp 1
107
108 We instantiate the five pages and insert them into the wizard
109 using QWizard::addPage(). The order in which they are inserted
110 is also the order in which they will be shown later on.
111
112 We call QWizard::setPixmap() to set the banner and the
113 background pixmaps for all pages. The banner is used as a
114 background for the page header when the wizard's style is
115 \l{QWizard::}{ModernStyle}; the background is used as the
116 dialog's background in \l{QWizard::}{MacStyle}. (See \l{Elements
117 of a Wizard Page} for more information.)
118
119 \snippet examples/dialogs/classwizard/classwizard.cpp 3
120 \snippet examples/dialogs/classwizard/classwizard.cpp 4
121 \dots
122 \snippet examples/dialogs/classwizard/classwizard.cpp 5
123 \snippet examples/dialogs/classwizard/classwizard.cpp 6
124
125 If the user clicks \gui Finish, we extract the information from
126 the various pages using QWizard::field() and generate the files.
127 The code is long and tedious (and has barely anything to do with
128 noble art of designing wizards), so most of it is skipped here.
129 See the actual example in the Qt distribution for the details if
130 you're curious.
131
132 \section1 The IntroPage Class
133
134 The pages are defined in \c classwizard.h and implemented in \c
135 classwizard.cpp, together with \c ClassWizard. We will start with
136 the easiest page:
137
138 \snippet examples/dialogs/classwizard/classwizard.h 1
139 \codeline
140 \snippet examples/dialogs/classwizard/classwizard.cpp 7
141
142 A page inherits from QWizardPage. We set a
143 \l{QWizardPage::}{title} and a
144 \l{QWizard::WatermarkPixmap}{watermark pixmap}. By not setting
145 any \l{QWizardPage::}{subTitle}, we ensure that no header is
146 displayed for this page. (On Windows, it is customary for wizards
147 to display a watermark pixmap on the first and last pages, and to
148 have a header on the other pages.)
149
150 Then we create a QLabel and add it to a layout.
151
152 \section1 The ClassInfoPage Class
153
154 The second page is defined and implemented as follows:
155
156 \snippet examples/dialogs/classwizard/classwizard.h 2
157 \codeline
158 \snippet examples/dialogs/classwizard/classwizard.cpp 9
159 \dots
160 \snippet examples/dialogs/classwizard/classwizard.cpp 12
161 \dots
162 \snippet examples/dialogs/classwizard/classwizard.cpp 13
163
164 First, we set the page's \l{QWizardPage::}{title},
165 \l{QWizardPage::}{subTitle}, and \l{QWizard::LogoPixmap}{logo
166 pixmap}. The logo pixmap is displayed in the page's header in
167 \l{QWizard::}{ClassicStyle} and \l{QWizard::}{ModernStyle}.
168
169 Then we create the child widgets, create \l{Registering and Using
170 Fields}{wizard fields} associated with them, and put them into
171 layouts. The \c className field is created with an asterisk (\c
172 *) next to its name. This makes it a \l{mandatory field}, that
173 is, a field that must be filled before the user can press the
174 \gui Next button (\gui Continue on Mac OS X). The fields' values
175 can be accessed from any other page using QWizardPage::field(),
176 or from the wizard code using QWizard::field().
177
178 \section1 The CodeStylePage Class
179
180 The third page is defined and implemented as follows:
181
182 \snippet examples/dialogs/classwizard/classwizard.h 3
183 \codeline
184 \snippet examples/dialogs/classwizard/classwizard.cpp 14
185 \dots
186 \snippet examples/dialogs/classwizard/classwizard.cpp 15
187 \codeline
188 \snippet examples/dialogs/classwizard/classwizard.cpp 16
189
190 The code in the constructor is very similar to what we did for \c
191 ClassInfoPage, so we skipped most of it.
192
193 The \c initializePage() function is what makes this class
194 interesting. It is reimplemented from QWizardPage and is used to
195 initialize some of the page's fields with values from the
196 previous page (namely, \c className and \c baseClass). For
197 example, if the class name on page 2 is \c SuperDuperWidget, the
198 default macro name on page 3 is \c SUPERDUPERWIDGET_H.
199
200 The \c OutputFilesPage and \c ConclusionPage classes are very
201 similar to \c CodeStylePage, so we won't review them here.
202
203 \sa QWizard, {License Wizard Example}, {Trivial Wizard Example}
204*/
Note: See TracBrowser for help on using the repository browser.