From 90d26668be2e59ea887ee9c0c2f61b57a32653bb Mon Sep 17 00:00:00 2001 From: Tobias Hunger Date: Wed, 1 Jul 2015 11:12:16 +0200 Subject: [PATCH] Doc: Update wizard development documentation * Remove stale examples and classes referrenced in the documentation. Change-Id: I5141f9085b7bd5f3f237faed2ad3a4791d863022 Reviewed-by: Leena Miettinen --- .../examples/webpagewizard/webpagewizard.cpp | 121 --------- .../examples/webpagewizard/webpagewizard.h | 76 ------ .../webpagewizard/webpagewizardplugin.cpp | 13 - doc/api/qtcreator-dev-wizards.qdoc | 241 +++++------------- 4 files changed, 65 insertions(+), 386 deletions(-) delete mode 100644 doc/api/examples/webpagewizard/webpagewizard.cpp delete mode 100644 doc/api/examples/webpagewizard/webpagewizard.h delete mode 100644 doc/api/examples/webpagewizard/webpagewizardplugin.cpp diff --git a/doc/api/examples/webpagewizard/webpagewizard.cpp b/doc/api/examples/webpagewizard/webpagewizard.cpp deleted file mode 100644 index ca7ef77ef69..00000000000 --- a/doc/api/examples/webpagewizard/webpagewizard.cpp +++ /dev/null @@ -1,121 +0,0 @@ -//! [0] -#include "webpagewizard.h" - -#include -#include - -#include - -#include -#include -#include -#include - -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(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] diff --git a/doc/api/examples/webpagewizard/webpagewizard.h b/doc/api/examples/webpagewizard/webpagewizard.h deleted file mode 100644 index 2cf9bf4d83a..00000000000 --- a/doc/api/examples/webpagewizard/webpagewizard.h +++ /dev/null @@ -1,76 +0,0 @@ -//! [0] - -#ifndef WEBPAGEFILEWIZARD_H -#define WEBPAGEFILEWIZARD_H - -#include "basefilewizard.h" -#include "utils/filewizarddialog.h" - -#include - -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] diff --git a/doc/api/examples/webpagewizard/webpagewizardplugin.cpp b/doc/api/examples/webpagewizard/webpagewizardplugin.cpp deleted file mode 100644 index 29720c50cf3..00000000000 --- a/doc/api/examples/webpagewizard/webpagewizardplugin.cpp +++ /dev/null @@ -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] diff --git a/doc/api/qtcreator-dev-wizards.qdoc b/doc/api/qtcreator-dev-wizards.qdoc index 303954a327d..fc548da07ae 100644 --- a/doc/api/qtcreator-dev-wizards.qdoc +++ b/doc/api/qtcreator-dev-wizards.qdoc @@ -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 */