|
1 /**************************************************************************** |
|
2 ** |
|
3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). |
|
4 ** All rights reserved. |
|
5 ** Contact: Nokia Corporation (qt-info@nokia.com) |
|
6 ** |
|
7 ** This file is part of the documentation of the Qt Toolkit. |
|
8 ** |
|
9 ** $QT_BEGIN_LICENSE:LGPL$ |
|
10 ** No Commercial Usage |
|
11 ** This file contains pre-release code and may not be distributed. |
|
12 ** You may use this file in accordance with the terms and conditions |
|
13 ** contained in the Technology Preview License Agreement accompanying |
|
14 ** this package. |
|
15 ** |
|
16 ** GNU Lesser General Public License Usage |
|
17 ** Alternatively, this file may be used under the terms of the GNU Lesser |
|
18 ** General Public License version 2.1 as published by the Free Software |
|
19 ** Foundation and appearing in the file LICENSE.LGPL included in the |
|
20 ** packaging of this file. Please review the following information to |
|
21 ** ensure the GNU Lesser General Public License version 2.1 requirements |
|
22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. |
|
23 ** |
|
24 ** In addition, as a special exception, Nokia gives you certain additional |
|
25 ** rights. These rights are described in the Nokia Qt LGPL Exception |
|
26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. |
|
27 ** |
|
28 ** If you have questions regarding the use of this file, please contact |
|
29 ** Nokia at qt-info@nokia.com. |
|
30 ** |
|
31 ** |
|
32 ** |
|
33 ** |
|
34 ** |
|
35 ** |
|
36 ** |
|
37 ** |
|
38 ** $QT_END_LICENSE$ |
|
39 ** |
|
40 ****************************************************************************/ |
|
41 |
|
42 /*! |
|
43 \example dialogs/licensewizard |
|
44 \title License Wizard Example |
|
45 |
|
46 The License Wizard example shows how to implement complex wizards in |
|
47 Qt. |
|
48 |
|
49 \image licensewizard-example.png Screenshot of the License 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. The |
|
53 \l{dialogs/classwizard}{Class Wizard} example shows how to create |
|
54 such wizards. |
|
55 |
|
56 Some wizards are more complex in that they allow different |
|
57 traversal paths based on the information provided by the user. |
|
58 The License Wizard example illustrates this. It provides five |
|
59 wizard pages; depending on which options are selected, the user |
|
60 can reach different pages. |
|
61 |
|
62 \image licensewizard-flow.png The License Wizard pages |
|
63 |
|
64 The example consists of the following classes: |
|
65 |
|
66 \list |
|
67 \o \c LicenseWizard inherits QWizard and implements a non-linear |
|
68 five-page wizard that leads the user through the process of |
|
69 choosing a license agreement. |
|
70 \o \c IntroPage, \c EvaluatePage, \c RegisterPage, \c |
|
71 DetailsPage, and \c ConclusionPage are QWizardPage subclasses |
|
72 that implement the wizard pages. |
|
73 \endlist |
|
74 |
|
75 \section1 The LicenseWizard Class |
|
76 |
|
77 The \c LicenseWizard class derives from QWizard and provides a |
|
78 five-page wizard that guides the user through the process of |
|
79 registering their copy of a fictitious software product. Here's |
|
80 the class definition: |
|
81 |
|
82 \snippet examples/dialogs/licensewizard/licensewizard.h 1 |
|
83 |
|
84 The class's public API is limited to a constructor and an enum. |
|
85 The enum defines the IDs associated with the various pages: |
|
86 |
|
87 \table |
|
88 \header \o Class name \o Enum value \o Page ID |
|
89 \row \o \c IntroPage \o \c Page_Intro \o 0 |
|
90 \row \o \c EvaluatePage \o \c Page_Evaluate \o 1 |
|
91 \row \o \c RegisterPage \o \c Page_Register \o 2 |
|
92 \row \o \c DetailsPage \o \c Page_Details \o 3 |
|
93 \row \o \c ConclusionPage \o \c Page_Conclusion \o 4 |
|
94 \endtable |
|
95 |
|
96 For this example, the IDs are arbitrary. The only constraints are |
|
97 that they must be unique and different from -1. IDs allow us to |
|
98 refer to pages. |
|
99 |
|
100 \snippet examples/dialogs/licensewizard/licensewizard.cpp 2 |
|
101 |
|
102 In the constructor, we create the five pages, insert them into |
|
103 the wizard using QWizard::setPage(), and set \c Page_Intro to be |
|
104 the first page. |
|
105 |
|
106 \snippet examples/dialogs/licensewizard/licensewizard.cpp 3 |
|
107 \snippet examples/dialogs/licensewizard/licensewizard.cpp 4 |
|
108 |
|
109 We set the style to \l{QWizard::}{ModernStyle} on all platforms |
|
110 except Mac OS X, |
|
111 |
|
112 \snippet examples/dialogs/licensewizard/licensewizard.cpp 5 |
|
113 \snippet examples/dialogs/licensewizard/licensewizard.cpp 6 |
|
114 |
|
115 We configure the QWizard to show a \gui Help button, which is |
|
116 connected to our \c showHelp() slot. We also set the |
|
117 \l{QWizard::}{LogoPixmap} for all pages that have a header (i.e., |
|
118 \c EvaluatePage, \c RegisterPage, and \c DetailsPage). |
|
119 |
|
120 \snippet examples/dialogs/licensewizard/licensewizard.cpp 9 |
|
121 \snippet examples/dialogs/licensewizard/licensewizard.cpp 11 |
|
122 \dots |
|
123 \snippet examples/dialogs/licensewizard/licensewizard.cpp 13 |
|
124 |
|
125 In \c showHelp(), we display help texts that are appropiate for |
|
126 the current page. If the user clicks \gui Help twice for the same |
|
127 page, we say, "Sorry, I already gave what help I could. Maybe you |
|
128 should try asking a human?" |
|
129 |
|
130 \section1 The IntroPage Class |
|
131 |
|
132 The pages are defined in \c licensewizard.h and implemented in \c |
|
133 licensewizard.cpp, together with \c LicenseWizard. |
|
134 |
|
135 Here's the definition and implementation of \c{IntroPage}: |
|
136 |
|
137 \snippet examples/dialogs/licensewizard/licensewizard.h 4 |
|
138 \codeline |
|
139 \snippet examples/dialogs/licensewizard/licensewizard.cpp 16 |
|
140 |
|
141 A page inherits from QWizardPage. We set a |
|
142 \l{QWizardPage::}{title} and a |
|
143 \l{QWizard::WatermarkPixmap}{watermark pixmap}. By not setting |
|
144 any \l{QWizardPage::}{subTitle}, we ensure that no header is |
|
145 displayed for this page. (On Windows, it is customary for wizards |
|
146 to display a watermark pixmap on the first and last pages, and to |
|
147 have a header on the other pages.) |
|
148 |
|
149 \snippet examples/dialogs/licensewizard/licensewizard.cpp 17 |
|
150 \snippet examples/dialogs/licensewizard/licensewizard.cpp 19 |
|
151 |
|
152 The \c nextId() function returns the ID for \c EvaluatePage if |
|
153 the \gui{Evaluate the product for 30 days} option is checked; |
|
154 otherwise it returns the ID for \c RegisterPage. |
|
155 |
|
156 \section1 The EvaluatePage Class |
|
157 |
|
158 The \c EvaluatePage is slightly more involved: |
|
159 |
|
160 \snippet examples/dialogs/licensewizard/licensewizard.h 5 |
|
161 \codeline |
|
162 \snippet examples/dialogs/licensewizard/licensewizard.cpp 20 |
|
163 \dots |
|
164 \snippet examples/dialogs/licensewizard/licensewizard.cpp 21 |
|
165 \dots |
|
166 \snippet examples/dialogs/licensewizard/licensewizard.cpp 22 |
|
167 |
|
168 First, we set the page's \l{QWizardPage::}{title} |
|
169 and \l{QWizardPage::}{subTitle}. |
|
170 |
|
171 Then we create the child widgets, create \l{Registering and Using |
|
172 Fields}{wizard fields} associated with them, and put them into |
|
173 layouts. The fields are created with an asterisk (\c |
|
174 *) next to their name. This makes them \l{mandatory fields}, that |
|
175 is, fields that must be filled before the user can press the |
|
176 \gui Next button (\gui Continue on Mac OS X). The fields' values |
|
177 can be accessed from any other page using QWizardPage::field(). |
|
178 |
|
179 Resetting the page amounts to clearing the two text fields. |
|
180 |
|
181 \snippet examples/dialogs/licensewizard/licensewizard.cpp 23 |
|
182 |
|
183 The next page is always the \c ConclusionPage. |
|
184 |
|
185 \section1 The ConclusionPage Class |
|
186 |
|
187 The \c RegisterPage and \c DetailsPage are very similar to \c |
|
188 EvaluatePage. Let's go directly to the \c ConclusionPage: |
|
189 |
|
190 \snippet examples/dialogs/licensewizard/licensewizard.h 6 |
|
191 |
|
192 This time, we reimplement QWizardPage::initializePage() and |
|
193 QWidget::setVisible(), in addition to |
|
194 \l{QWizardPage::}{nextId()}. We also declare a private slot: |
|
195 \c printButtonClicked(). |
|
196 |
|
197 \snippet examples/dialogs/licensewizard/licensewizard.cpp 18 |
|
198 |
|
199 The default implementation of QWizardPage::nextId() returns |
|
200 the page with the next ID, or -1 if the current page has the |
|
201 highest ID. This behavior would work here, because \c |
|
202 Page_Conclusion equals 5 and there is no page with a higher ID, |
|
203 but to avoid relying on such subtle behavior, we reimplement |
|
204 \l{QWizardPage::}{nextId()} to return -1. |
|
205 |
|
206 \snippet examples/dialogs/licensewizard/licensewizard.cpp 27 |
|
207 |
|
208 We use QWizard::hasVisitedPage() to determine the type of |
|
209 license agreement the user has chosen. If the user filled the \c |
|
210 EvaluatePage, the license text refers to an Evaluation License |
|
211 Agreement. If the user filled the \c DetailsPage, the license |
|
212 text is a First-Time License Agreement. If the user provided an |
|
213 upgrade key and skipped the \c DetailsPage, the license text is |
|
214 an Update License Agreement. |
|
215 |
|
216 \snippet examples/dialogs/licensewizard/licensewizard.cpp 28 |
|
217 |
|
218 We want to display a \gui Print button in the wizard when the \c |
|
219 ConclusionPage is up. One way to accomplish this is to reimplement |
|
220 QWidget::setVisible(): |
|
221 |
|
222 \list |
|
223 \o If the page is shown, we set the \l{QWizard::}{CustomButton1} button's |
|
224 text to \gui{\underline{P}rint}, we enable the \l{QWizard::}{HaveCustomButton1} |
|
225 option, and we connect the QWizard's \l{QWizard::}{customButtonClicked()} |
|
226 signal to our \c printButtonClicked() slot. |
|
227 \o If the page is hidden, we disable the \l{QWizard::}{HaveCustomButton1} |
|
228 option and disconnect the \c printButtonClicked() slot. |
|
229 \endlist |
|
230 |
|
231 \sa QWizard, {Class Wizard Example}, {Trivial Wizard Example} |
|
232 */ |