1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the documentation of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

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

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

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

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

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

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

    23 **

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

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

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

    27 **

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

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

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*!

    43     \example dialogs/classwizard

    44     \title Class Wizard Example

    45 

    46     The License Wizard example shows how to implement linear

    47     wizards using QWizard.

    48 

    49     \image classwizard.png Screenshot of the Class Wizard example

    50 

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

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

    53     complex in that they allow different traversal paths based on the

    54     information provided by the user. The

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

    56     create such wizards.

    57 

    58     The Class Wizard example consists of the following classes:

    59 

    60     \list

    61     \o \c ClassWizard inherits QWizard and provides a

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

    63        based on the user's input.

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

    65        OutputFilesPage, and \c ConclusionPage are QWizardPage

    66        subclasses that implement the wizard pages.

    67     \endlist

    68 

    69     \section1 ClassWizard Class Definition

    70 

    71     \image classwizard-flow.png The Class Wizard pages

    72 

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

    74     The concrete wizard class is called \c ClassWizard and provides

    75     five pages:

    76 

    77     \list

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

    79        the wizard is going to do.

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

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

    82        Q_OBJECT macro and what constructors it should provide.

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

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

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

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

    87        output files.

    88     \o The fifth page is a conclusion page.

    89     \endlist

    90 

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

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

    93     generated.

    94 

    95     \section1 The ClassWizard Class

    96 

    97     Here's the \c ClassWizard definition:

    98 

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

   100 

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

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

   103 

   104     Here's the constructor:

   105 

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

   107 

   108     We instantiate the five pages and insert them into the wizard

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

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

   111 

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

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

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

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

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

   117     of a Wizard Page} for more information.)

   118 

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

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

   121     \dots

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

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

   124 

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

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

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

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

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

   130     you're curious.

   131 

   132     \section1 The IntroPage Class

   133 

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

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

   136     the easiest page:

   137 

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

   139     \codeline

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

   141 

   142     A page inherits from QWizardPage. We set a

   143     \l{QWizardPage::}{title} and a

   144     \l{QWizard::WatermarkPixmap}{watermark pixmap}. By not setting

   145     any \l{QWizardPage::}{subTitle}, we ensure that no header is

   146     displayed for this page. (On Windows, it is customary for wizards

   147     to display a watermark pixmap on the first and last pages, and to

   148     have a header on the other pages.)

   149 

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

   151 

   152     \section1 The ClassInfoPage Class

   153 

   154     The second page is defined and implemented as follows:

   155 

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

   157     \codeline

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

   159     \dots

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

   161     \dots

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

   163 

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

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

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

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

   168 

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

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

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

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

   173     is, a field that must be filled before the user can press the

   174     \gui Next button (\gui Continue on Mac OS X). The fields' values

   175     can be accessed from any other page using QWizardPage::field(),

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

   177 

   178     \section1 The CodeStylePage Class

   179 

   180     The third page is defined and implemented as follows:

   181 

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

   183     \codeline

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

   185     \dots

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

   187     \codeline

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

   189 

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

   191     ClassInfoPage, so we skipped most of it.

   192 

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

   194     interesting. It is reimplemented from QWizardPage and is used to

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

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

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

   198     default macro name on page 3 is \c SUPERDUPERWIDGET_H.

   199 

   200     The \c OutputFilesPage and \c ConclusionPage classes are very

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

   202 

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

   204 */