Initial import from the monolithic Qt.

This is the beginning of revision history for this module. If you
want to look at revision history older than this, please refer to the
Qt Git wiki for how to use Git history grafting. At the time of
writing, this wiki is located here:

http://qt.gitorious.org/qt/pages/GitIntroductionWithQt

If you have already performed the grafting and you don't see any
history beyond this commit, try running "git log" with the "--follow"
argument.

Branched from the monolithic repo, Qt master branch, at commit
896db169ea224deb96c59ce8af800d019de63f12

1 files changed, 218 insertions, 0 deletions

diff --git a/doc/src/examples/licensewizard.qdoc b/doc/src/examples/licensewizard.qdoc
new file mode 100644
index 0000000000..0b335349fd
--- /dev/null
+++ b/doc/src/examples/licensewizard.qdoc
@@ -0,0 +1,218 @@
+/****************************************************************************
+**
+** 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}
+*/