| /**************************************************************************** |
| ** |
| ** Copyright (C) 2016 The Qt Company Ltd. |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** This file is part of the documentation of the Qt Toolkit. |
| ** |
| ** $QT_BEGIN_LICENSE:FDL$ |
| ** Commercial License Usage |
| ** Licensees holding valid commercial Qt licenses may use this file in |
| ** accordance with the commercial license agreement provided with the |
| ** Software or, alternatively, in accordance with the terms contained in |
| ** a written agreement between you and The Qt Company. For licensing terms |
| ** and conditions see https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://www.qt.io/contact-us. |
| ** |
| ** GNU Free Documentation License Usage |
| ** 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. Please review the following information to ensure |
| ** the GNU Free Documentation License version 1.3 requirements |
| ** will be met: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| /*! |
| \example dialogs/classwizard |
| \title Class Wizard Example |
| \ingroup examples-dialogs |
| |
| \brief The Class 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 \macos), 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 fields}{mandatory field}, that |
| is, a field that must be filled before the user can press the |
| \uicontrol Next button (\uicontrol Continue on \macos). 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} |
| */ |