219 lines
8.6 KiB
Plaintext
219 lines
8.6 KiB
Plaintext
|
/****************************************************************************
|
||
|
**
|
||
|
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
|
||
|
** All rights reserved.
|
||
|
** Contact: Nokia Corporation (qt-info@nokia.com)
|
||
|
**
|
||
|
** This file is part of the documentation of the Qt Toolkit.
|
||
|
**
|
||
|
** $QT_BEGIN_LICENSE:FDL$
|
||
|
** No Commercial Usage
|
||
|
** This file contains pre-release code and may not be distributed.
|
||
|
** You may use this file in accordance with the terms and conditions
|
||
|
** contained in the Technology Preview License Agreement accompanying
|
||
|
** this package.
|
||
|
**
|
||
|
** 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.
|
||
|
**
|
||
|
** If you have questions regarding the use of this file, please contact
|
||
|
** Nokia at qt-info@nokia.com.
|
||
|
** $QT_END_LICENSE$
|
||
|
**
|
||
|
****************************************************************************/
|
||
|
|
||
|
/*!
|
||
|
\example dialogs/licensewizard
|
||
|
\title License Wizard Example
|
||
|
|
||
|
The License Wizard example shows how to implement complex wizards in
|
||
|
Qt.
|
||
|
|
||
|
\image licensewizard-example.png Screenshot of the License Wizard example
|
||
|
|
||
|
Most wizards have a linear structure, with page 1 followed by
|
||
|
page 2 and so on until the last page. The
|
||
|
\l{dialogs/classwizard}{Class Wizard} example shows how to create
|
||
|
such wizards.
|
||
|
|
||
|
Some wizards are more complex in that they allow different
|
||
|
traversal paths based on the information provided by the user.
|
||
|
The License Wizard example illustrates this. It provides five
|
||
|
wizard pages; depending on which options are selected, the user
|
||
|
can reach different pages.
|
||
|
|
||
|
\image licensewizard-flow.png The License Wizard pages
|
||
|
|
||
|
The example consists of the following classes:
|
||
|
|
||
|
\list
|
||
|
\o \c LicenseWizard inherits QWizard and implements a non-linear
|
||
|
five-page wizard that leads the user through the process of
|
||
|
choosing a license agreement.
|
||
|
\o \c IntroPage, \c EvaluatePage, \c RegisterPage, \c
|
||
|
DetailsPage, and \c ConclusionPage are QWizardPage subclasses
|
||
|
that implement the wizard pages.
|
||
|
\endlist
|
||
|
|
||
|
\section1 The LicenseWizard Class
|
||
|
|
||
|
The \c LicenseWizard class derives from QWizard and provides a
|
||
|
five-page wizard that guides the user through the process of
|
||
|
registering their copy of a fictitious software product. Here's
|
||
|
the class definition:
|
||
|
|
||
|
\snippet examples/dialogs/licensewizard/licensewizard.h 1
|
||
|
|
||
|
The class's public API is limited to a constructor and an enum.
|
||
|
The enum defines the IDs associated with the various pages:
|
||
|
|
||
|
\table
|
||
|
\header \o Class name \o Enum value \o Page ID
|
||
|
\row \o \c IntroPage \o \c Page_Intro \o 0
|
||
|
\row \o \c EvaluatePage \o \c Page_Evaluate \o 1
|
||
|
\row \o \c RegisterPage \o \c Page_Register \o 2
|
||
|
\row \o \c DetailsPage \o \c Page_Details \o 3
|
||
|
\row \o \c ConclusionPage \o \c Page_Conclusion \o 4
|
||
|
\endtable
|
||
|
|
||
|
For this example, the IDs are arbitrary. The only constraints are
|
||
|
that they must be unique and different from -1. IDs allow us to
|
||
|
refer to pages.
|
||
|
|
||
|
\snippet examples/dialogs/licensewizard/licensewizard.cpp 2
|
||
|
|
||
|
In the constructor, we create the five pages, insert them into
|
||
|
the wizard using QWizard::setPage(), and set \c Page_Intro to be
|
||
|
the first page.
|
||
|
|
||
|
\snippet examples/dialogs/licensewizard/licensewizard.cpp 3
|
||
|
\snippet examples/dialogs/licensewizard/licensewizard.cpp 4
|
||
|
|
||
|
We set the style to \l{QWizard::}{ModernStyle} on all platforms
|
||
|
except Mac OS X,
|
||
|
|
||
|
\snippet examples/dialogs/licensewizard/licensewizard.cpp 5
|
||
|
\snippet examples/dialogs/licensewizard/licensewizard.cpp 6
|
||
|
|
||
|
We configure the QWizard to show a \gui Help button, which is
|
||
|
connected to our \c showHelp() slot. We also set the
|
||
|
\l{QWizard::}{LogoPixmap} for all pages that have a header (i.e.,
|
||
|
\c EvaluatePage, \c RegisterPage, and \c DetailsPage).
|
||
|
|
||
|
\snippet examples/dialogs/licensewizard/licensewizard.cpp 9
|
||
|
\snippet examples/dialogs/licensewizard/licensewizard.cpp 11
|
||
|
\dots
|
||
|
\snippet examples/dialogs/licensewizard/licensewizard.cpp 13
|
||
|
|
||
|
In \c showHelp(), we display help texts that are appropiate for
|
||
|
the current page. If the user clicks \gui Help twice for the same
|
||
|
page, we say, "Sorry, I already gave what help I could. Maybe you
|
||
|
should try asking a human?"
|
||
|
|
||
|
\section1 The IntroPage Class
|
||
|
|
||
|
The pages are defined in \c licensewizard.h and implemented in \c
|
||
|
licensewizard.cpp, together with \c LicenseWizard.
|
||
|
|
||
|
Here's the definition and implementation of \c{IntroPage}:
|
||
|
|
||
|
\snippet examples/dialogs/licensewizard/licensewizard.h 4
|
||
|
\codeline
|
||
|
\snippet examples/dialogs/licensewizard/licensewizard.cpp 16
|
||
|
|
||
|
A page inherits from QWizardPage. We set a
|
||
|
\l{QWizardPage::}{title} and a
|
||
|
\l{QWizard::WatermarkPixmap}{watermark pixmap}. By not setting
|
||
|
any \l{QWizardPage::}{subTitle}, we ensure that no header is
|
||
|
displayed for this page. (On Windows, it is customary for wizards
|
||
|
to display a watermark pixmap on the first and last pages, and to
|
||
|
have a header on the other pages.)
|
||
|
|
||
|
\snippet examples/dialogs/licensewizard/licensewizard.cpp 17
|
||
|
\snippet examples/dialogs/licensewizard/licensewizard.cpp 19
|
||
|
|
||
|
The \c nextId() function returns the ID for \c EvaluatePage if
|
||
|
the \gui{Evaluate the product for 30 days} option is checked;
|
||
|
otherwise it returns the ID for \c RegisterPage.
|
||
|
|
||
|
\section1 The EvaluatePage Class
|
||
|
|
||
|
The \c EvaluatePage is slightly more involved:
|
||
|
|
||
|
\snippet examples/dialogs/licensewizard/licensewizard.h 5
|
||
|
\codeline
|
||
|
\snippet examples/dialogs/licensewizard/licensewizard.cpp 20
|
||
|
\dots
|
||
|
\snippet examples/dialogs/licensewizard/licensewizard.cpp 21
|
||
|
\dots
|
||
|
\snippet examples/dialogs/licensewizard/licensewizard.cpp 22
|
||
|
|
||
|
First, we set the page's \l{QWizardPage::}{title}
|
||
|
and \l{QWizardPage::}{subTitle}.
|
||
|
|
||
|
Then we create the child widgets, create \l{Registering and Using
|
||
|
Fields}{wizard fields} associated with them, and put them into
|
||
|
layouts. The fields are created with an asterisk (\c
|
||
|
*) next to their name. This makes them \l{mandatory fields}, that
|
||
|
is, fields that must be filled before the user can press the
|
||
|
\gui Next button (\gui Continue on Mac OS X). The fields' values
|
||
|
can be accessed from any other page using QWizardPage::field().
|
||
|
|
||
|
Resetting the page amounts to clearing the two text fields.
|
||
|
|
||
|
\snippet examples/dialogs/licensewizard/licensewizard.cpp 23
|
||
|
|
||
|
The next page is always the \c ConclusionPage.
|
||
|
|
||
|
\section1 The ConclusionPage Class
|
||
|
|
||
|
The \c RegisterPage and \c DetailsPage are very similar to \c
|
||
|
EvaluatePage. Let's go directly to the \c ConclusionPage:
|
||
|
|
||
|
\snippet examples/dialogs/licensewizard/licensewizard.h 6
|
||
|
|
||
|
This time, we reimplement QWizardPage::initializePage() and
|
||
|
QWidget::setVisible(), in addition to
|
||
|
\l{QWizardPage::}{nextId()}. We also declare a private slot:
|
||
|
\c printButtonClicked().
|
||
|
|
||
|
\snippet examples/dialogs/licensewizard/licensewizard.cpp 18
|
||
|
|
||
|
The default implementation of QWizardPage::nextId() returns
|
||
|
the page with the next ID, or -1 if the current page has the
|
||
|
highest ID. This behavior would work here, because \c
|
||
|
Page_Conclusion equals 5 and there is no page with a higher ID,
|
||
|
but to avoid relying on such subtle behavior, we reimplement
|
||
|
\l{QWizardPage::}{nextId()} to return -1.
|
||
|
|
||
|
\snippet examples/dialogs/licensewizard/licensewizard.cpp 27
|
||
|
|
||
|
We use QWizard::hasVisitedPage() to determine the type of
|
||
|
license agreement the user has chosen. If the user filled the \c
|
||
|
EvaluatePage, the license text refers to an Evaluation License
|
||
|
Agreement. If the user filled the \c DetailsPage, the license
|
||
|
text is a First-Time License Agreement. If the user provided an
|
||
|
upgrade key and skipped the \c DetailsPage, the license text is
|
||
|
an Update License Agreement.
|
||
|
|
||
|
\snippet examples/dialogs/licensewizard/licensewizard.cpp 28
|
||
|
|
||
|
We want to display a \gui Print button in the wizard when the \c
|
||
|
ConclusionPage is up. One way to accomplish this is to reimplement
|
||
|
QWidget::setVisible():
|
||
|
|
||
|
\list
|
||
|
\o If the page is shown, we set the \l{QWizard::}{CustomButton1} button's
|
||
|
text to \gui{\underline{P}rint}, we enable the \l{QWizard::}{HaveCustomButton1}
|
||
|
option, and we connect the QWizard's \l{QWizard::}{customButtonClicked()}
|
||
|
signal to our \c printButtonClicked() slot.
|
||
|
\o If the page is hidden, we disable the \l{QWizard::}{HaveCustomButton1}
|
||
|
option and disconnect the \c printButtonClicked() slot.
|
||
|
\endlist
|
||
|
|
||
|
\sa QWizard, {Class Wizard Example}, {Trivial Wizard Example}
|
||
|
*/
|