feedc0de/qt-creator
1
0
Fork 0
forked from qt-creator/qt-creator
Code Pull Requests Activity

Doc: Update wizard development documentation

Browse Source 
* Remove stale examples and classes referrenced in the documentation.

Change-Id: I5141f9085b7bd5f3f237faed2ad3a4791d863022
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@theqtcompany.com>
This commit is contained in:
Tobias Hunger
2015-07-01 11:12:16 +02:00
parent d8d60c5b51
commit 90d26668be
4 changed files with 65 additions and 386 deletions
Download Patch File Download Diff File Expand all files Collapse all files

121
doc/api/examples/webpagewizard/webpagewizard.cpp
View File

@@ -1,121 +0,0 @@
//! [0]
#include "webpagewizard.h"
#include <utils/filewizarddialog.h>
#include <utils/qtcassert.h>
#include <QXmlStreamWriter>
#include <QGridLayout>
#include <QLabel>
#include <QLineEdit>
#include <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]

76
doc/api/examples/webpagewizard/webpagewizard.h
View File

@@ -1,76 +0,0 @@
//! [0]
#ifndef WEBPAGEFILEWIZARD_H
#define WEBPAGEFILEWIZARD_H
#include "basefilewizard.h"
#include "utils/filewizarddialog.h"
#include <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]

13
doc/api/examples/webpagewizard/webpagewizardplugin.cpp
View File

@@ -1,13 +0,0 @@
//! [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]

241
doc/api/qtcreator-dev-wizards.qdoc
View File

@@ -26,24 +26,18 @@
\l{http://doc.qt.io/qtcreator/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
A wizard in \QC is an instance of a class implementing
the Core::IWizardFactory interface that is registered with
ExtensionSystem::PluginManager.
Implementing wizards requires:
\list
\li Deciding on a base class:
\list
\li Core::IWizardFactory is a very generic interface that does
not make any assumption about what the wizard does and
what its UI looks like.
\li Core::BaseFileWizardFactory should be used for wizards that
generate files using a UI based on Utils::Wizard.
\endlist
\li Writing a factory class that derives from Core::IWizardFactory. This is
a very generic interface that does not make any assumption about what
the wizard does and what its UI looks like.
\li Providing a set of parameters that determine how the wizard shows up
in the list of wizards in the \uicontrol{New File or Project} dialog.
in the list of wizards in the \uicontrol {New File or Project} dialog.
When deriving from Core::IWizardFactory, the constructor has to call
the following setters provided by the base class:
@@ -61,11 +55,6 @@
\li \c setFlags
\endlist
When deriving from Core::BaseFileWizardFactory, 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.
\li Implementing the wizard UI
Typically, this will be a class derived from Utils::Wizard.
@@ -74,187 +63,87 @@
\li Implementing the wizard functionality
When deriving from Core::BaseFileWizardFactory, 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::BaseFileWizardFactory after performing overwrite checks and
prompting the user accordingly.
It is recommended to use Core::GeneratedFile to represent files
that need to be written to disk. They allow to delay writing the actual
data to disk till the wizard is done.
\endlist
\section2 Relevant Classes
\table
\header
\li Class
\li Description
\header
\li Class
\li Description
\row
\li Core::IWizardFactory
\li Qt Creator wizard interface, implementations of which are registered with
ExtensionSystem::PluginManager.
\row
\li Core::IWizardFactory
\li \QC wizard interface, implementations of which are registered
with ExtensionSystem::PluginManager.
\row
\li Core::BaseFileWizardFactory
\li Inherits Core::IWizardFactory and provides a base class for generating files with a UI
based on QWizard.
\row
\li Core::GeneratedFile
\li A file containing name, contents, and some attributes.
\row
\li Core::BaseFileWizardParameters
\li Contains parameters for Core::BaseFileWizard.
\row
\li Core::GeneratedFile
\li A file as produced by Core::BaseFileWizard, containing name, contents and some
attributes.
\row
\li Utils::FileWizardPage
\li Introductory wizard page asking for file name and path.
\row
\li Utils::FileWizardDialog
\li A wizard dialog presenting a Utils::FileWizardPage, which can be extended
by custom pages.
\row
\li Utils::ProjectIntroPage
\li Introductory wizard page asking for project name and path.
\row
\li ProjectExplorer::BaseProjectWizardDialog
\li Base class for project wizard dialogs, presenting
a Utils::ProjectIntroPage.
\row
\li Utils::FileWizardPage
\li Introductory wizard page asking for file name and path.
\row
\li Utils::ProjectIntroPage
\li Introductory wizard page asking for project name and path.
\endtable
\section2 Parameters
\section2 Setters and Getters of IWizardFactory
The parameters listed below determine how the wizard shows up
in the list of wizards in the \uicontrol{New File or Project} dialog.
Wizards in Qt Creator are grouped by categories.
The setters and getters listed below determine how the wizard shows up
in the list of wizards in the \uicontrol {New File or Project} dialog.
\table
\header
\li Type
\li Parameter Name
\li Description
\header
\li Type
\li Parameter Name
\li Description
\row
\li Core::IWizardFactory::WizardKind
\li kind
\li Enumeration value that indicates the type of the wizard (project or file).
\row
\li Core::IWizardFactory::WizardKind
\li kind
\li Enumeration value that indicates the type of the wizard
(\c project or \c file).
\row
\li QIcon
\li icon
\li Icon to show.
\row
\li QIcon
\li icon
\li Icon to show.
\row
\li QString
\li description
\li Descriptive text.
\row
\li QString
\li description
\li Descriptive text.
\row
\li QString
\li displayName
\li Name to be shown in the list.
\row
\li QString
\li displayName
\li Name to be shown in the list.
\row
\li QString
\li id
\li Unique identifier for the wizard. It also determines the order within a category.
\row
\li QString
\li id
\li Unique identifier for the wizard. It also determines the order
within a category.
\row
\li QString
\li category
\li Identifier of the category under which the wizard is to be listed. It also
determines the order of the categories.
\
\row
\li QString
\li displayCategory
\li Description of the category.
\row
\li QString
\li category
\li Identifier of the category under which the wizard is to be
listed. It also determines the order of the categories.
\row
\li QString
\li displayCategory
\li Description of the category.
\endtable
\section1 Example
All wizards that have the same category set will be grouped together in the
\uicontrol {New File or Project} dialog.
\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 \uicontrol{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 \uicontrol{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() function
of a plugin looks like:
\snippet webpagewizard/webpagewizardplugin.cpp 0
*/