/****************************************************************************

**

** Copyright (C) 2009 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:LGPL$

** 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 Lesser General Public License Usage

** Alternatively, this file may be used under the terms of the GNU Lesser

** General Public License version 2.1 as published by the Free Software

** Foundation and appearing in the file LICENSE.LGPL included in the

** packaging of this file.  Please review the following information to

** ensure the GNU Lesser General Public License version 2.1 requirements

** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

**

** In addition, as a special exception, Nokia gives you certain additional

** rights.  These rights are described in the Nokia Qt LGPL Exception

** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

**

** If you have questions regarding the use of this file, please contact

** Nokia at qt-info@nokia.com.

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

/*!

    \example dialogs/classwizard

    \title Class Wizard Example

    The License Wizard example shows how to implement linear

    wizards using QWizard.

    \image classwizard.png Screenshot of the Class Wizard example

    Most wizards have a linear structure, with page 1 followed by

    page 2 and so on until the last page. Some wizards are more

    complex in that they allow different traversal paths based on the

    information provided by the user. The

    \l{dialogs/licensewizard}{License Wizard} example shows how to

    create such wizards.

    The Class Wizard example consists of the following classes:

    \list

    \o \c ClassWizard inherits QWizard and provides a

       three-step wizard that generates the skeleton of a C++ class

       based on the user's input.

    \o \c IntroPage, \c ClassInfoPage, \c CodeStylePage, \c

       OutputFilesPage, and \c ConclusionPage are QWizardPage

       subclasses that implement the wizard pages.

    \endlist

    \section1 ClassWizard Class Definition

    \image classwizard-flow.png The Class Wizard pages

    We will see how to subclass QWizard to implement our own wizard.

    The concrete wizard class is called \c ClassWizard and provides

    five pages:

    \list

    \o The first page is an introduction page, telling the user what

       the wizard is going to do.

    \o The second page asks for a class name and a base class, and

       allows the user to specify whether the class should have a \c

       Q_OBJECT macro and what constructors it should provide.

    \o The third page allows the user to set some options related to the code

       style, such as the macro used to protect the header file from

       multiple inclusion (e.g., \c MYDIALOG_H).

    \o The fourth page allows the user to specify the names of the

       output files.

    \o The fifth page is a conclusion page.

    \endlist

    Although the program is just an example, if you press \gui Finish

    (\gui Done on Mac OS X), actual C++ source files will actually be

    generated.

    \section1 The ClassWizard Class

    Here's the \c ClassWizard definition:

    \snippet examples/dialogs/classwizard/classwizard.h 0

    The class reimplements QDialog's \l{QDialog::}{accept()} slot.

    This slot is called when the user clicks \gui{Finish}.

    Here's the constructor:

    \snippet examples/dialogs/classwizard/classwizard.cpp 1

    We instantiate the five pages and insert them into the wizard

    using QWizard::addPage(). The order in which they are inserted

    is also the order in which they will be shown later on.

    We call QWizard::setPixmap() to set the banner and the

    background pixmaps for all pages. The banner is used as a

    background for the page header when the wizard's style is

    \l{QWizard::}{ModernStyle}; the background is used as the

    dialog's background in \l{QWizard::}{MacStyle}. (See \l{Elements

    of a Wizard Page} for more information.)

    \snippet examples/dialogs/classwizard/classwizard.cpp 3

    \snippet examples/dialogs/classwizard/classwizard.cpp 4

    \dots

    \snippet examples/dialogs/classwizard/classwizard.cpp 5

    \snippet examples/dialogs/classwizard/classwizard.cpp 6

    If the user clicks \gui Finish, we extract the information from

    the various pages using QWizard::field() and generate the files.

    The code is long and tedious (and has barely anything to do with

    noble art of designing wizards), so most of it is skipped here.

    See the actual example in the Qt distribution for the details if

    you're curious.

    \section1 The IntroPage Class

    The pages are defined in \c classwizard.h and implemented in \c

    classwizard.cpp, together with \c ClassWizard. We will start with

    the easiest page:

    \snippet examples/dialogs/classwizard/classwizard.h 1

    \codeline

    \snippet examples/dialogs/classwizard/classwizard.cpp 7

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

    Then we create a QLabel and add it to a layout.

    \section1 The ClassInfoPage Class

    The second page is defined and implemented as follows:

    \snippet examples/dialogs/classwizard/classwizard.h 2

    \codeline

    \snippet examples/dialogs/classwizard/classwizard.cpp 9

    \dots

    \snippet examples/dialogs/classwizard/classwizard.cpp 12

    \dots

    \snippet examples/dialogs/classwizard/classwizard.cpp 13

    First, we set the page's \l{QWizardPage::}{title},

    \l{QWizardPage::}{subTitle}, and \l{QWizard::LogoPixmap}{logo

    pixmap}. The logo pixmap is displayed in the page's header in

    \l{QWizard::}{ClassicStyle} and \l{QWizard::}{ModernStyle}.

    Then we create the child widgets, create \l{Registering and Using

    Fields}{wizard fields} associated with them, and put them into

    layouts. The \c className field is created with an asterisk (\c

    *) next to its name. This makes it a \l{mandatory field}, that

    is, a field 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(),

    or from the wizard code using QWizard::field().

    \section1 The CodeStylePage Class

    The third page is defined and implemented as follows:

    \snippet examples/dialogs/classwizard/classwizard.h 3

    \codeline

    \snippet examples/dialogs/classwizard/classwizard.cpp 14

    \dots

    \snippet examples/dialogs/classwizard/classwizard.cpp 15

    \codeline

    \snippet examples/dialogs/classwizard/classwizard.cpp 16

    The code in the constructor is very similar to what we did for \c

    ClassInfoPage, so we skipped most of it.

    The \c initializePage() function is what makes this class

    interesting. It is reimplemented from QWizardPage and is used to

    initialize some of the page's fields with values from the

    previous page (namely, \c className and \c baseClass). For

    example, if the class name on page 2 is \c SuperDuperWidget, the

    default macro name on page 3 is \c SUPERDUPERWIDGET_H.

    The \c OutputFilesPage and \c ConclusionPage classes are very

    similar to \c CodeStylePage, so we won't review them here.

    \sa QWizard, {License Wizard Example}, {Trivial Wizard Example}

*/