From deb13f7c5eac296c7c0cea98e13fa69bf1afe3dd Mon Sep 17 00:00:00 2001
From: Friedemann Kleint <Friedemann.Kleint@nokia.com>
Date: Fri, 1 Apr 2011 12:18:25 +0200
Subject: [PATCH] Documentation: BaseFileWizard.
---
src/plugins/coreplugin/basefilewizard.cpp | 135 ++++++++++++++++++++--
src/plugins/coreplugin/basefilewizard.h | 53 +--------
2 files changed, 130 insertions(+), 58 deletions(-)
diff --git a/src/plugins/coreplugin/basefilewizard.cpp b/src/plugins/coreplugin/basefilewizard.cpp
index e9060e99f41..8e34928b329 100644
--- a/src/plugins/coreplugin/basefilewizard.cpp
+++ b/src/plugins/coreplugin/basefilewizard.cpp
@@ -61,6 +61,17 @@
enum { debugWizard = 0 };
+/*!
+ \class Core::GeneratedFile
+ \brief Represents a file generated by a wizard.
+
+ The Wizard class will check for each file whether it already exists and will
+ report any errors that may occur during creation of the files.
+
+ \sa Core::BaseFileWizardParameters, Core::BaseFileWizard, Core::StandardFileWizard
+ \sa Core::Internal::WizardEventLoop
+ */
+
namespace Core {
class GeneratedFilePrivate : public QSharedData
@@ -230,6 +241,15 @@ void BaseFileWizardParameterData::clear()
displayCategory.clear();
}
+/*!
+ \class Core::BaseFileWizardParameters
+ \brief Parameter class for passing parameters to instances of class Wizard
+ containing name, icon and such.
+
+ \sa Core::GeneratedFile, Core::BaseFileWizard, Core::StandardFileWizard
+ \sa Core::Internal::WizardEventLoop
+*/
+
BaseFileWizardParameters::BaseFileWizardParameters(IWizard::WizardKind kind) :
m_d(new BaseFileWizardParameterData(kind))
{
@@ -336,15 +356,24 @@ void BaseFileWizardParameters::setDisplayCategory(const QString &v)
m_d->displayCategory = v;
}
-/* WizardEventLoop: Special event loop that runs a QWizard and terminates if the page changes.
- * Synopsis:
- * \code
+/*!
+ \class Core::Internal::WizardEventLoop
+ \brief Special event loop that runs a QWizard and terminates if the page changes.
+
+ Use by Core::BaseFileWizard to intercept the change from the standard wizard pages
+ to the extension pages (as the latter require the list of Core::GeneratedFile generated).
+
+ Synopsis:
+ \code
Wizard wizard(parent);
WizardEventLoop::WizardResult wr;
do {
wr = WizardEventLoop::execWizardPage(wizard);
} while (wr == WizardEventLoop::PageChanged);
- * \endcode */
+ \endcode
+
+ \sa Core::GeneratedFile, Core::BaseFileWizardParameters, Core::BaseFileWizard, Core::StandardFileWizard
+*/
class WizardEventLoop : public QEventLoop
{
@@ -422,7 +451,24 @@ void WizardEventLoop::rejected()
quit();
}
-// ---------------- BaseFileWizardPrivate
+/*!
+ \class Core::BaseFileWizard
+ \brief A generic wizard for creating files.
+
+ The abstract methods:
+ \list
+ \o createWizardDialog(): Called to create the QWizard dialog to be shown
+ \o generateFiles(): Generate file content
+ \endlist
+
+ must be implemented.
+ The behaviour can be further customized by overwriting the virtual method \c postGenerateFiles(),
+ which is called after generating the files.
+
+ \sa Core::GeneratedFile, Core::BaseFileWizardParameters, Core::StandardFileWizard
+ \sa Core::Internal::WizardEventLoop
+*/
+
struct BaseFileWizardPrivate
{
explicit BaseFileWizardPrivate(const Core::BaseFileWizardParameters ¶meters)
@@ -587,7 +633,27 @@ void BaseFileWizard::runWizard(const QString &path, QWidget *parent)
QMessageBox::critical(0, tr("File Generation Failure"), errorMessage);
}
-// Write
+/*!
+ \fn virtual QWizard *Core::BaseFileWizard::createWizardDialog(QWidget *parent,
+ const QString &defaultPath,
+ const WizardPageList &extensionPages) const = 0
+ \brief Implement to create the wizard dialog on the parent, adding the extension pages.
+*/
+
+/*!
+ \fn virtual Core::GeneratedFiles Core::BaseFileWizard::generateFiles(const QWizard *w,
+ QString *errorMessage) const = 0
+ \brief Overwrite to query the parameters from the dialog and generate the files.
+
+ Note: This does not generate physical files, but merely the list of Core::GeneratedFile.
+*/
+
+/*!
+ \brief Physically write files.
+
+ Re-implement (calling the base implementation) to create files with CustomGeneratorAttribute set.
+*/
+
bool BaseFileWizard::writeFiles(const GeneratedFiles &files, QString *errorMessage)
{
foreach (const GeneratedFile &generatedFile, files)
@@ -597,6 +663,9 @@ bool BaseFileWizard::writeFiles(const GeneratedFiles &files, QString *errorMessa
return true;
}
+/*!
+ \brief Sets some standard options on a QWizard
+*/
void BaseFileWizard::setupWizard(QWizard *w)
{
@@ -605,6 +674,11 @@ void BaseFileWizard::setupWizard(QWizard *w)
w->setOption(QWizard::NoBackButtonOnStartPage, true);
}
+/*!
+ \brief Read "shortTitle" dynamic property of the pageId and apply it as the title
+ of corresponding progress item
+*/
+
void BaseFileWizard::applyExtensionPageShortTitle(Utils::Wizard *wizard, int pageId)
{
if (pageId < 0)
@@ -620,11 +694,21 @@ void BaseFileWizard::applyExtensionPageShortTitle(Utils::Wizard *wizard, int pag
item->setTitle(shortTitle);
}
+/*!
+ \brief Overwrite to perform steps to be done after files are actually created.
+
+ The default implementation opens editors with the newly generated files.
+*/
+
bool BaseFileWizard::postGenerateFiles(const QWizard *, const GeneratedFiles &l, QString *errorMessage)
{
return BaseFileWizard::postGenerateOpenEditors(l, errorMessage);
}
+/*!
+ \brief Utility to open the editors for the files whose attribute is set accordingly.
+*/
+
bool BaseFileWizard::postGenerateOpenEditors(const GeneratedFiles &l, QString *errorMessage)
{
Core::EditorManager *em = Core::EditorManager::instance();
@@ -640,6 +724,11 @@ bool BaseFileWizard::postGenerateOpenEditors(const GeneratedFiles &l, QString *e
return true;
}
+/*!
+ \brief Utility that performs an overwrite check on a set of files. It checks if
+ the file exists, can be overwritten at all and prompts the user with a summary.
+*/
+
BaseFileWizard::OverwriteResult BaseFileWizard::promptOverwrite(const QStringList &files,
QString *errorMessage) const
{
@@ -707,6 +796,10 @@ BaseFileWizard::OverwriteResult BaseFileWizard::promptOverwrite(const QStringLis
return yes ? OverwriteOk : OverwriteCanceled;
}
+/*!
+ \brief Build a file name, adding the extension unless baseName already has one.
+*/
+
QString BaseFileWizard::buildFileName(const QString &path,
const QString &baseName,
const QString &extension)
@@ -727,6 +820,10 @@ QString BaseFileWizard::buildFileName(const QString &path,
return rc;
}
+/*!
+ \brief Utility that returns the preferred suffix for a mime type
+*/
+
QString BaseFileWizard::preferredSuffix(const QString &mimeType)
{
const QString rc = Core::ICore::instance()->mimeDatabase()->preferredSuffixByType(mimeType);
@@ -736,7 +833,23 @@ QString BaseFileWizard::preferredSuffix(const QString &mimeType)
return rc;
}
-// ------------- StandardFileWizard
+/*!
+ \class Core::StandardFileWizard
+ \brief Convenience class for creating one file.
+
+ It uses Utils::FileWizardDialog and introduces a new virtual to generate the
+ files from path and name.
+
+ \sa Core::GeneratedFile, Core::BaseFileWizardParameters, Core::BaseFileWizard
+ \sa Core::Internal::WizardEventLoop
+*/
+
+/*!
+ \fn Core::GeneratedFiles Core::StandardFileWizard::generateFilesFromPath(const QString &path,
+ const QString &name,
+ QString *errorMessage) const = 0
+ \brief Newly introduced virtual that creates the files under the path.
+*/
StandardFileWizard::StandardFileWizard(const BaseFileWizardParameters ¶meters,
QObject *parent) :
@@ -744,6 +857,10 @@ StandardFileWizard::StandardFileWizard(const BaseFileWizardParameters ¶meter
{
}
+/*!
+ \brief Implemented to create a Utils::FileWizardDialog.
+*/
+
QWizard *StandardFileWizard::createWizardDialog(QWidget *parent,
const QString &defaultPath,
const WizardPageList &extensionPages) const
@@ -757,6 +874,10 @@ QWizard *StandardFileWizard::createWizardDialog(QWidget *parent,
return standardWizardDialog;
}
+/*!
+ \brief Implemented to retrieve path and name and call generateFilesFromPath()
+*/
+
GeneratedFiles StandardFileWizard::generateFiles(const QWizard *w,
QString *errorMessage) const
{
diff --git a/src/plugins/coreplugin/basefilewizard.h b/src/plugins/coreplugin/basefilewizard.h
index 3795798fc12..52acb334e06 100644
--- a/src/plugins/coreplugin/basefilewizard.h
+++ b/src/plugins/coreplugin/basefilewizard.h
@@ -61,11 +61,6 @@ class BaseFileWizardParameterData;
struct BaseFileWizardPrivate;
class GeneratedFilePrivate;
-/*!
- * Represents a file generated by a wizard. The Wizard class will check for
- * each file whether it already exists and will report any errors that may
- * occur during creation of the files.
- */
class CORE_EXPORT GeneratedFile
{
public:
@@ -115,9 +110,6 @@ private:
typedef QList<GeneratedFile> GeneratedFiles;
-/* Parameter class for passing parameters to instances of class Wizard
- * containing name, icon and such. */
-
class CORE_EXPORT BaseFileWizardParameters
{
public:
@@ -155,18 +147,6 @@ private:
CORE_EXPORT QDebug operator<<(QDebug d, const BaseFileWizardParameters &);
-/* A generic wizard for creating files.
- *
- * The abstract methods:
- *
- * createWizardDialog() : Called to create the QWizard dialog to be shown
- * generateFiles() : Generate file content
- *
- * must be implemented. The behaviour can be further customized by overwriting
- * the virtual method:
- * postGenerateFiles() : Called after generating the files.
- */
-
class CORE_EXPORT BaseFileWizard : public IWizard
{
Q_DISABLE_COPY(BaseFileWizard)
@@ -187,13 +167,8 @@ public:
virtual void runWizard(const QString &path, QWidget *parent);
- // Build a file name, adding the extension unless baseName already has one
static QString buildFileName(const QString &path, const QString &baseName, const QString &extension);
-
- // Sets some standard options on a QWizard
static void setupWizard(QWizard *);
-
- // Read "shortTitle" dynamic property of the pageId and apply it as the title of corresponding progress item
static void applyExtensionPageShortTitle(Utils::Wizard *wizard, int pageId);
protected:
@@ -201,44 +176,27 @@ protected:
explicit BaseFileWizard(const BaseFileWizardParameters ¶meters, QObject *parent = 0);
- // Overwrite to create the wizard dialog on the parent, adding
- // the extension pages.
virtual QWizard *createWizardDialog(QWidget *parent,
const QString &defaultPath,
const WizardPageList &extensionPages) const = 0;
-
- // Overwrite to query the parameters from the dialog and generate the files.
virtual GeneratedFiles generateFiles(const QWizard *w,
QString *errorMessage) const = 0;
- /* Physically write files. Re-implement (calling the base implementation)
- * to create files with CustomGeneratorAttribute set. */
virtual bool writeFiles(const GeneratedFiles &files, QString *errorMessage);
- /* Overwrite to perform steps to be done after files are actually created.
- * The default implementation opens editors with the newly generated files. */
virtual bool postGenerateFiles(const QWizard *w, const GeneratedFiles &l, QString *errorMessage);
- // Utility that returns the preferred suffix for a mime type
static QString preferredSuffix(const QString &mimeType);
- // Utility that performs an overwrite check on a set of files. It checks if
- // the file exists, can be overwritten at all and prompts the user.
enum OverwriteResult { OverwriteOk, OverwriteError, OverwriteCanceled };
OverwriteResult promptOverwrite(const QStringList &files,
QString *errorMessage) const;
-
- // Utility to open the editors for the files whose attribute is set accordingly.
static bool postGenerateOpenEditors(const GeneratedFiles &l, QString *errorMessage = 0);
private:
BaseFileWizardPrivate *m_d;
};
-// StandardFileWizard convenience class for creating one file. It uses
-// Utils::FileWizardDialog and introduces a new virtual to generate the
-// files from path and name.
-
class CORE_EXPORT StandardFileWizard : public BaseFileWizard
{
Q_DISABLE_COPY(StandardFileWizard)
@@ -246,18 +204,11 @@ class CORE_EXPORT StandardFileWizard : public BaseFileWizard
protected:
explicit StandardFileWizard(const BaseFileWizardParameters ¶meters, QObject *parent = 0);
-
- // Implemented to create a Utils::FileWizardDialog
virtual QWizard *createWizardDialog(QWidget *parent,
const QString &defaultPath,
const WizardPageList &extensionPages) const;
- // Implemented to retrieve path and name and call generateFilesFromPath()
- virtual GeneratedFiles generateFiles(const QWizard *w,
- QString *errorMessage) const;
-
- // Newly introduced virtual that creates a file from a path
- virtual GeneratedFiles generateFilesFromPath(const QString &path,
- const QString &name,
+ virtual GeneratedFiles generateFiles(const QWizard *w, QString *errorMessage) const;
+ virtual GeneratedFiles generateFilesFromPath(const QString &path, const QString &name,
QString *errorMessage) const = 0;
};
--
GitLab