diff options
Diffstat (limited to 'examples/widgets/doc/classwizard.qdoc')
| -rw-r--r-- | examples/widgets/doc/classwizard.qdoc | 190 |
1 files changed, 190 insertions, 0 deletions
diff --git a/examples/widgets/doc/classwizard.qdoc b/examples/widgets/doc/classwizard.qdoc new file mode 100644 index 0000000000..0c357b7286 --- /dev/null +++ b/examples/widgets/doc/classwizard.qdoc @@ -0,0 +1,190 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $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 + \li \c ClassWizard inherits QWizard and provides a + three-step wizard that generates the skeleton of a C++ class + based on the user's input. + \li \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 + \li The first page is an introduction page, telling the user what + the wizard is going to do. + \li 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. + \li 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). + \li The fourth page allows the user to specify the names of the + output files. + \li The fifth page is a conclusion page. + \endlist + + Although the program is just an example, if you press \uicontrol Finish + (\uicontrol Done on Mac OS X), actual C++ source files will actually be + generated. + + \section1 The ClassWizard Class + + Here's the \c ClassWizard definition: + + \snippet dialogs/classwizard/classwizard.h 0 + + The class reimplements QDialog's \l{QDialog::}{accept()} slot. + This slot is called when the user clicks \uicontrol{Finish}. + + Here's the constructor: + + \snippet 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 dialogs/classwizard/classwizard.cpp 3 + \snippet dialogs/classwizard/classwizard.cpp 4 + \dots + \snippet dialogs/classwizard/classwizard.cpp 5 + \snippet dialogs/classwizard/classwizard.cpp 6 + + If the user clicks \uicontrol 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 dialogs/classwizard/classwizard.h 1 + \codeline + \snippet 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 dialogs/classwizard/classwizard.h 2 + \codeline + \snippet dialogs/classwizard/classwizard.cpp 9 + \dots + \snippet dialogs/classwizard/classwizard.cpp 12 + \dots + \snippet 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 + \uicontrol Next button (\uicontrol 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 dialogs/classwizard/classwizard.h 3 + \codeline + \snippet dialogs/classwizard/classwizard.cpp 14 + \dots + \snippet dialogs/classwizard/classwizard.cpp 15 + \codeline + \snippet 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} +*/ |