Doc: Add documentation on how to write Wizards in code.

Reviewed-by: Leena Miettinen <leena.miettinen@nokia.com>
Acked-by: Alessandro Portale <alessandro.portale@nokia.com>

doc/api/api.pro

@@ -45,6 +45,7 @@ HELP_DEP_FILES = $$PWD/qtcreator-api.qdoc \
                  $$PWD/coding-style.qdoc \
                  $$PWD/external-tool-spec.qdoc \
                  $$PWD/qtcreator-dev.qdoc \
+                 $$PWD/qtcreator-dev-wizards.qdoc \
                  $$PWD/qtcreator-dev.qdocconf
 
 docs.name = CREATE API DOC

doc/api/examples/webpagewizard/webpagewizard.cpp

@@ -0,0 +1,122 @@
+//! [0]
+#include "webpagewizard.h"
+
+#include <utils/filewizarddialog.h>
+#include <utils/qtcassert.h>
+
+#include <QtCore/QXmlStreamWriter>
+
+#include <QtGui/QGridLayout>
+#include <QtGui/QLabel>
+#include <QtGui/QLineEdit>
+#include <QtGui/QPlainTextEdit>
+
+namespace MyPlugin {
+namespace Internal {
+
+//! [1]
+WebContentPageWizardPage::WebContentPageWizardPage(QWidget *parent) :
+    QWizardPage(parent),
+    m_titleLineEdit(new QLineEdit),
+    m_textEdit(new QPlainTextEdit),
+    m_complete(false)
+{
+    QGridLayout *layout = new QGridLayout(this);
+    QLabel *titleLabel = new QLabel(tr("&Title"));
+    layout->addWidget(titleLabel, 0, 0);
+    layout->addWidget(m_titleLineEdit, 0, 1);
+    QLabel *contentLabel = new QLabel(tr("&Content"));
+    layout->addWidget(contentLabel, 1, 0, 1, 1, Qt::AlignTop);
+    layout->addWidget(m_textEdit, 1, 1);
+    titleLabel->setBuddy(m_titleLineEdit);
+    contentLabel->setBuddy(m_textEdit);
+    setTitle(tr("Web Page Contents"));
+
+    connect(m_titleLineEdit, SIGNAL(textChanged(QString)), this, SLOT(slotChanged()));
+    connect(m_textEdit, SIGNAL(textChanged()), this, SLOT(slotChanged()));
+}
+
+QString WebContentPageWizardPage::title() const
+{
+    return m_titleLineEdit->text();
+}
+
+QString WebContentPageWizardPage::contents() const
+{
+    return m_textEdit->toPlainText();
+}
+
+void WebContentPageWizardPage::slotChanged()
+{
+    const bool completeNow = !m_titleLineEdit->text().isEmpty()
+            && m_textEdit->blockCount() > 0;
+    if (completeNow != m_complete) {
+        m_complete = completeNow;
+        emit completeChanged();
+    }
+}
+
+//! [1] //! [2]
+
+WebContentWizardDialog::WebContentWizardDialog(QWidget *parent) :
+    Utils::FileWizardDialog(parent), m_contentPage(new WebContentPageWizardPage)
+{
+    addPage(m_contentPage);
+}
+
+//! [2] //! [3]
+
+WebPageWizard::WebPageWizard(const Core::BaseFileWizardParameters &parameters,
+                             QObject *parent) :
+    Core::BaseFileWizard(parameters, parent)
+{
+}
+
+QWizard *WebPageWizard::createWizardDialog(QWidget *parent,
+                                    const QString &defaultPath,
+                                    const WizardPageList &extensionPages) const
+{
+    WebContentWizardDialog *dialog = new WebContentWizardDialog(parent);
+    dialog->setPath(defaultPath);
+    foreach (QWizardPage *p, extensionPages)
+        dialog->addPage(p);
+    return dialog;
+}
+
+Core::GeneratedFiles
+    WebPageWizard::generateFiles(const QWizard *w,
+                                     QString *) const
+{
+    Core::GeneratedFiles files;
+    const WebContentWizardDialog *dialog = qobject_cast<const WebContentWizardDialog*>(w);
+    QTC_ASSERT(dialog, return files; )
+
+    const QString fileName = Core::BaseFileWizard::buildFileName(dialog->path(), dialog->fileName(), QLatin1String("html"));
+
+    Core::GeneratedFile file(fileName);
+
+    QString contents;
+    QXmlStreamWriter writer(&contents);
+    writer.setAutoFormatting(true);
+    writer.writeStartDocument();
+    writer.writeStartElement(QLatin1String("html"));
+    writer.writeStartElement(QLatin1String("head"));
+    writer.writeTextElement(QLatin1String("title"), dialog->title());
+    writer.writeEndElement(); // HEAD
+    writer.writeStartElement(QLatin1String("body"));
+    writer.writeTextElement(QLatin1String("h1"), dialog->title());
+    writer.writeTextElement(QLatin1String("p"), dialog->contents());
+    writer.writeEndElement(); // BODY
+    writer.writeEndElement(); // HTML
+    file.setAttributes(Core::GeneratedFile::OpenEditorAttribute);
+    file.setContents(contents);
+    files.push_back(file);
+    return files;
+}
+
+//! [3]
+
+} // namespace Internal
+} // namespace MyPlugin
+
+//! [0]

doc/api/examples/webpagewizard/webpagewizard.h

@@ -0,0 +1,76 @@
+//! [0]
+
+#ifndef WEBPAGEFILEWIZARD_H
+#define WEBPAGEFILEWIZARD_H
+
+#include "basefilewizard.h"
+#include "utils/filewizarddialog.h"
+
+#include <QtGui/QWizardPage>
+
+QT_BEGIN_NAMESPACE
+class QLineEdit;
+class QPlainTextEdit;
+QT_END_NAMESPACE
+
+namespace MyPlugin {
+namespace Internal {
+
+//! [1]
+class WebContentPageWizardPage : public QWizardPage
+{
+    Q_OBJECT
+public:
+    explicit WebContentPageWizardPage(QWidget *parent = 0);
+
+    QString title() const;
+    QString contents() const;
+
+    virtual bool isComplete() const { return m_complete; }
+
+private slots:
+    void slotChanged();
+
+private:
+    QLineEdit *m_titleLineEdit;
+    QPlainTextEdit *m_textEdit;
+    bool m_complete;
+};
+
+//! [1] //! [2]
+
+class WebContentWizardDialog : public Utils::FileWizardDialog
+{
+    Q_OBJECT
+public:
+    explicit WebContentWizardDialog(QWidget *parent = 0);
+
+    QString title() const    { return m_contentPage->title(); }
+    QString contents() const { return m_contentPage->contents(); }
+
+private:
+    WebContentPageWizardPage *m_contentPage;
+};
+
+//! [2] //! [3]
+
+class WebPageWizard : public Core::BaseFileWizard
+{
+public:
+    explicit WebPageWizard(const Core::BaseFileWizardParameters &parameters,
+                           QObject *parent = 0);
+protected:
+    virtual QWizard *createWizardDialog(QWidget *parent,
+                                        const QString &defaultPath,
+                                        const WizardPageList &extensionPages) const;
+    virtual Core::GeneratedFiles generateFiles(const QWizard *w,
+                                         QString *errorMessage) const;
+};
+
+//! [3]
+} // namespace Internal
+} // namespace MyPlugin
+
+
+#endif // WEBPAGEFILEWIZARD_H
+//! [0]

doc/api/examples/webpagewizard/webpagewizardplugin.cpp

@@ -0,0 +1,13 @@
+//! [0]
+bool MyPlugin::initialize(const QStringList &arguments, QString *errorMessage)
+{
+    Core::BaseFileWizardParameters p(IWizard::FileWizard);
+    p.setCategory(QLatin1String("P.web"));
+    p.setDisplayCategory(tr("Web"));
+    p.setDescription(tr("Creates a Web Page."));
+    p.setDisplayName(tr("Web Page"));
+    p.setId(QLatin1String("A.WebPage"));
+    addAutoReleasedObject(new WebPageWizard(p));
+}
+
+//! [0]

doc/api/qtcreator-dev-wizards.qdoc

@@ -0,0 +1,249 @@
+/****************************************************************************
+**
+** This file is part of Qt Creator
+**
+** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
+**
+** Contact: Nokia Corporation (info@qt.nokia.com)
+**
+**
+** 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.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+****************************************************************************/
+
+/*!
+    \page qtcreator-dev-wizards.html
+    \title Creating Wizards in Code
+
+    \section1 Introduction
+
+    If the functionality provided by template-based
+    \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-project-wizards.html}{custom wizards}
+    is not sufficient for your case, you can write wizards in code.
+
+    A wizard in Qt Creator is an instance of a class implementing
+    the Core::IWizard interface that is registered with ExtensionSystem::PluginManager.
+
+    Implementing wizards requires:
+    \list
+    \o Deciding on a base class:
+       \list
+       \o Core::IWizard is a very generic interface that does
+          not make any assumption about what the wizard does and
+          what its UI looks like.
+
+       \o Core::BaseFileWizard should be used for wizards that
+          generate files using a UI based on Utils::Wizard.
+       \endlist
+
+    \o Providing a set of parameters that determine how the wizard shows up
+       in the list of wizards in the  \gui{New File or Project} dialog.
+
+       When deriving from Core::IWizard, virtual functions returning the
+       values have to be implemented.
+
+       When deriving from Core::BaseFileWizard, a parameter class
+       Core::BaseFileWizardParameters needs to be passed to the constructor,
+       on which the parameters can be set. This allows for easy creation
+       of several wizard instances with slightly different parameters.
+
+    \o Implementing the wizard UI
+
+       Typically, this will be a class derived from Utils::Wizard.
+       Utils::Wizard extends QWizard with the functionality to show a progress
+       bar on the left.
+
+    \o Implementing the wizard functionality
+
+       When deriving from Core::BaseFileWizard, a list of Core::GeneratedFile
+       needs to be populated with the files and their contents.
+       \note The files are not actually written to the disk. This will be
+       done by Core::BaseFileWizard after performing overwrite checks and prompting
+       the user accordingly.
+
+    \endlist
+
+    \section2 Relevant Classes
+
+    \table
+    \header
+    \o Class
+    \o Description
+
+    \row
+    \o Core::IWizard
+    \o Qt Creator wizard interface, implementations of which are registered with
+       ExtensionSystem::PluginManager.
+
+    \row
+    \o Core::BaseFileWizard
+    \o Inherits Core::IWizard and provides a base class for generating files with a UI
+       based on QWizard.
+
+    \row
+    \o Core::BaseFileWizardParameters
+    \o Contains parameters for Core::BaseFileWizard.
+
+    \row
+    \o Core::GeneratedFile
+    \o A file as produced by Core::BaseFileWizard, containing name, contents and some
+    attributes.
+
+    \row
+    \o Utils::FileWizardPage
+    \o Introductory wizard page asking for file name and path.
+
+    \row
+    \o Utils::FileWizardDialog
+    \o A wizard dialog presenting a Utils::FileWizardPage, which can be extended
+       by custom pages.
+
+    \row
+    \o Utils::ProjectIntroPage
+    \o Introductory wizard page asking for project name and path.
+
+    \row
+    \o ProjectExplorer::BaseProjectWizardDialog
+    \o Base class for project wizard dialogs, presenting
+        a Utils::ProjectIntroPage.
+
+    \endtable
+
+    \section2 Parameters
+
+    The parameters listed below determine how the wizard shows up
+    in the list of wizards in the  \gui{New File or Project} dialog.
+
+    Wizards in Qt Creator are grouped by categories.
+
+    \table
+    \header
+    \o Type
+    \o Parameter Name
+    \o Description
+
+    \row
+    \o Core::IWizard::WizardKind
+    \o kind
+    \o Enumeration value that indicates the type of the wizard (project, class, file).
+
+    \row
+    \o QIcon
+    \o icon
+    \o Icon to show.
+
+    \row
+    \o QString
+    \o description
+    \o Descriptive text.
+
+    \row
+    \o QString
+    \o displayName
+    \o Name to be shown in the list.
+
+    \row
+    \o QString
+    \o id
+    \o Unique identifier for the wizard. It also determines the order within a category.
+
+    \row
+    \o QString
+    \o category
+    \o Identifier of the category under which the wizard is to be listed. It also
+       determines the order of the categories.
+    \
+    \row
+    \o QString
+    \o displayCategory
+    \o Description of the category.
+    \endtable
+
+    \section1 Example
+
+    \section2 Introduction
+
+    In this example, we create a wizard
+    for writing HTML files consisting of a title and a paragraph,
+    making use of QXmlStreamWriter.
+
+    For the UI, we use Utils::FileWizardDialog and extend it by a page
+    letting the user enter title and contents.
+
+    In our BaseFileWizard implementation, we create the file contents
+    using QXmlStreamWriter.
+
+    \section2 The WebContentPageWizardPage Class
+
+    Let us start with the wizard page. We use a QLineEdit for the title
+    and a QPlainTextEdit for the content, arranged in a QGridLayout with
+    descriptive labels.
+    \note The QGridLayout was chosen to be able to accommodate the large
+    vertical span of the QPlainTextEdit. For standard controls, a
+    QFormLayout should be considered, which will lay out the labels
+    according to the platform guide lines.
+
+    On top of that, we implement validation logic to ensure content is entered.
+    We implement QWizardPage::isComplete() to return true when both input widgets
+    have contents, enabling the \gui{Next} button. For this to happen
+    as the user enters text, we need to connect to the changed() signal of the
+    controls and emit QWizardPage::completeChanged() once the complete status changes.
+
+    \snippet webpagewizard/webpagewizard.h 1
+
+    \snippet webpagewizard/webpagewizard.cpp 1
+
+    \section2 The WebContentWizardDialog Class
+
+    The wizard dialog extends Utils::FileWizardDialog, which presents an
+    introductory page asking for file name and path.
+    We add our WebContentPageWizardPage after that.
+
+    \snippet webpagewizard/webpagewizard.h 2
+
+    \snippet webpagewizard/webpagewizard.cpp 2
+
+    \section2 The WebContentWizard Class
+
+    In our implementation of Core::BaseFileWizard, we overwrite
+    createWizardDialog() to return an instance of our WebContentWizardDialog,
+    initially set to the path passed in. We also add the extension pages
+    we receive. Extension pages are for example the wizard pages asking for
+    a project to add the files to and whether to add the files to a version control
+    system.
+
+    In generateFiles(), we obtain the parameters from our wizard and populate
+    the list of Core::GeneratedFile with our file. To generate the contents,
+    we use QXmlStreamWriter.
+
+    \snippet webpagewizard/webpagewizard.h 3
+
+    \snippet webpagewizard/webpagewizard.cpp 3
+
+    \section2 Plugin Registration
+
+    In order for the wizard to be found by the \gui{New} dialog, we need to
+    register it with ExtensionSystem::PluginManager, which also takes care
+    of deleting it:
+
+    \snippet webpagewizard/webpagewizardplugin.cpp 0
+
+    \section2 Complete Example Code
+
+    Here is the complete code of \c webpagewizard.h:
+    \snippet webpagewizard/webpagewizard.h 0
+    The complete code of \c webpagewizard.cpp looks as follows:
+    \snippet webpagewizard/webpagewizard.cpp 0
+
+    The registration of the wizard in the \c initialize() method
+    of a plugin looks like:
+    \snippet webpagewizard/webpagewizardplugin.cpp 0
+*/

doc/api/qtcreator-dev.qdoc

@@ -80,7 +80,7 @@
     \list
     \o \l{Creating Plugins}
     \o \l{Qt Creator Coding Rules}
-    \o \l{Wizards}
+    \o \l{Creating Wizards in Code}
     \o \l{User Interface Text Guidelines}
     \endlist
 

doc/config/qtcreator-developer.qdocconf

@@ -39,7 +39,7 @@ sources.fileextensions  = "*.cpp *.qdoc"
 
 imagedirs = $SRCDIR/images $SRCDIR/templates/images
 outputdir = ../api/html
-exampledirs = 
+exampledirs = ../api/examples
 indexes                 = qt.index
 
 include(compat.qdocconf)