forked from qt-creator/qt-creator
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>
This commit is contained in:
@@ -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
|
||||
|
122
doc/api/examples/webpagewizard/webpagewizard.cpp
Normal file
122
doc/api/examples/webpagewizard/webpagewizard.cpp
Normal file
@@ -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 ¶meters,
|
||||
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]
|
76
doc/api/examples/webpagewizard/webpagewizard.h
Normal file
76
doc/api/examples/webpagewizard/webpagewizard.h
Normal file
@@ -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 ¶meters,
|
||||
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]
|
13
doc/api/examples/webpagewizard/webpagewizardplugin.cpp
Normal file
13
doc/api/examples/webpagewizard/webpagewizardplugin.cpp
Normal file
@@ -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]
|
249
doc/api/qtcreator-dev-wizards.qdoc
Normal file
249
doc/api/qtcreator-dev-wizards.qdoc
Normal file
@@ -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
|
||||
*/
|
@@ -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
|
||||
|
||||
|
@@ -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)
|
||||
|
Reference in New Issue
Block a user