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