/*!
    \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:

    \quotefromfile dialogs/licensewizard/licensewizard.h
    \skipto class LicenseWizard :
    \printuntil /^\};$/

    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.

    \quotefromfile dialogs/licensewizard/licensewizard.cpp
    \skipto ::LicenseWizard
    \printuntil setStartId

    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.

    \printline Q_WS_MAC
    \printuntil endif

    We set the style to \l{QWizard::}{ModernStyle} on all platforms
    except Mac OS X,

    \printline setOption
    \printuntil /^\}$/

    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).

    \printline ::showHelp
    \printuntil break
    \dots
    \skipto default:
    \printuntil /^\}$/

    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}:

    \quotefromfile dialogs/licensewizard/licensewizard.h
    \skipto class IntroPage :
    \printuntil };

    \quotefromfile dialogs/licensewizard/licensewizard.cpp
    \skipto ::IntroPage
    \printuntil }

    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.)

    \printuntil IntroPage::nextId
    \printuntil /^\}$/

    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:

    \quotefromfile dialogs/licensewizard/licensewizard.h
    \skipto class EvaluatePage :
    \printuntil };

    \quotefromfile dialogs/licensewizard/licensewizard.cpp
    \skipto ::EvaluatePage
    \printuntil nameLineEdit = new
    \dots
    \skipto registerField
    \printuntil email
    \dots
    \skipto /^\}$/
    \printline }

    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.

    \skipto EvaluatePage::nextId()
    \printuntil /^\}$/

    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:

    \quotefromfile dialogs/licensewizard/licensewizard.h
    \skipto class ConclusionPage :
    \printuntil };

    This time, we reimplement QWizardPage::initializePage() and
    QWidget::setVisible(), in addition to
    \l{QWizardPage::}{nextId()}. We also declare a private slot:
    \c printButtonClicked().

    \quotefromfile dialogs/licensewizard/licensewizard.cpp
    \skipto ::nextId
    \printuntil /^\}/

    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.

    \skipto ConclusionPage::initializePage
    \printuntil /^\}$/

    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.

    \skipto ::setVisible
    \printuntil /^\}/

    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}
*/
