src/plugins/coreplugin/basefilewizard.h

   1 /**************************************************************************
   2 **
   3 ** This file is part of Qt Creator
   4 **
   5 ** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
   6 **
   7 ** Contact: Nokia Corporation (qt-info@nokia.com)
   8 **
   9 ** No Commercial Usage
  10 **
  11 ** This file contains pre-release code and may not be distributed.
  12 ** You may use this file in accordance with the terms and conditions
  13 ** contained in the Technology Preview License Agreement accompanying
  14 ** this package.
  15 **
  16 ** GNU Lesser General Public License Usage
  17 **
  18 ** Alternatively, this file may be used under the terms of the GNU Lesser
  19 ** General Public License version 2.1 as published by the Free Software
  20 ** Foundation and appearing in the file LICENSE.LGPL included in the
  21 ** packaging of this file.  Please review the following information to
  22 ** ensure the GNU Lesser General Public License version 2.1 requirements
  23 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  24 **
  25 ** In addition, as a special exception, Nokia gives you certain additional
  26 ** rights.  These rights are described in the Nokia Qt LGPL Exception
  27 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  28 **
  29 ** If you have questions regarding the use of this file, please contact
  30 ** Nokia at qt-info@nokia.com.
  31 **
  32 **************************************************************************/
  33
  34 #ifndef BASEFILEWIZARD_H
  35 #define BASEFILEWIZARD_H
  36
  37 #include "core_global.h"
  38
  39 #include <coreplugin/dialogs/iwizard.h>
  40
  41 #include <QtCore/QSharedDataPointer>
  42 #include <QtCore/QList>
  43
  44 QT_BEGIN_NAMESPACE
  45 class QIcon;
  46 class QWizard;
  47 class QWizardPage;
  48 class QDebug;
  49 QT_END_NAMESPACE
  50
  51 namespace Utils {
  52     class Wizard;
  53 }
  54
  55 namespace Core {
  56
  57 class IEditor;
  58 class IFileWizardExtension;
  59
  60 class BaseFileWizardParameterData;
  61 struct BaseFileWizardPrivate;
  62 class GeneratedFilePrivate;
  63
  64 /*!
  65  * Represents a file generated by a wizard. The Wizard class will check for
  66  * each file whether it already exists and will report any errors that may
  67  * occur during creation of the files.
  68  */
  69 class CORE_EXPORT GeneratedFile
  70 {
  71 public:
  72     enum Attribute { // Open this file in editor
  73                      OpenEditorAttribute = 0x01,
  74                      // Open project
  75                      OpenProjectAttribute = 0x02,
  76                      /* File is generated by external scripts, do not write out,
  77                       * see BaseFileWizard::writeFiles() */
  78                      CustomGeneratorAttribute = 0x4
  79                    };
  80     Q_DECLARE_FLAGS(Attributes, Attribute)
  81
  82     GeneratedFile();
  83     explicit GeneratedFile(const QString &path);
  84     GeneratedFile(const GeneratedFile &);
  85     GeneratedFile &operator=(const GeneratedFile &);
  86     ~GeneratedFile();
  87
  88     // Full path of the file should be created, or the suggested file name
  89     QString path() const;
  90     void setPath(const QString &p);
  91
  92     // Contents of the file (UTF8)
  93     QString contents() const;
  94     void setContents(const QString &c);
  95
  96     QByteArray binaryContents() const;
  97     void setBinaryContents(const QByteArray &c);
  98
  99     // Defaults to false (Text file).
 100     bool isBinary() const;
 101     void setBinary(bool b);
 102
 103     // Id of editor to open the file with
 104     QString editorId() const;
 105     void setEditorId(const QString &k);
 106
 107     bool write(QString *errorMessage) const;
 108
 109     Attributes attributes() const;
 110     void setAttributes(Attributes a);
 111
 112 private:
 113     QSharedDataPointer<GeneratedFilePrivate> m_d;
 114 };
 115
 116 typedef QList<GeneratedFile> GeneratedFiles;
 117
 118 /* Parameter class for passing parameters to instances of class Wizard
 119  * containing name, icon and such. */
 120
 121 class CORE_EXPORT BaseFileWizardParameters
 122 {
 123 public:
 124     explicit BaseFileWizardParameters(IWizard::WizardKind kind = IWizard::FileWizard);
 125     BaseFileWizardParameters(const BaseFileWizardParameters &);
 126     BaseFileWizardParameters &operator=(const BaseFileWizardParameters&);
 127    ~BaseFileWizardParameters();
 128
 129     void clear();
 130
 131     IWizard::WizardKind kind() const;
 132     void setKind(IWizard::WizardKind k);
 133
 134     QIcon icon() const;
 135     void setIcon(const QIcon &icon);
 136
 137     QString description() const;
 138     void setDescription(const QString &description);
 139
 140     QString displayName() const;
 141     void setDisplayName(const QString &name);
 142
 143     QString id() const;
 144     void setId(const QString &id);
 145
 146     QString category() const;
 147     void setCategory(const QString &category);
 148
 149     QString displayCategory() const;
 150     void setDisplayCategory(const QString &trCategory);
 151
 152 private:
 153     QSharedDataPointer<BaseFileWizardParameterData> m_d;
 154 };
 155
 156 CORE_EXPORT QDebug operator<<(QDebug d, const BaseFileWizardParameters &);
 157
 158 /* A generic wizard for creating files.
 159  *
 160  * The abstract methods:
 161  *
 162  * createWizardDialog() : Called to create the QWizard dialog to be shown
 163  * generateFiles()      : Generate file content
 164  *
 165  * must be implemented. The behaviour can be further customized by overwriting
 166  * the virtual method:
 167  * postGenerateFiles()  :   Called after generating the files.
 168  */
 169
 170 class CORE_EXPORT BaseFileWizard : public IWizard
 171 {
 172     Q_DISABLE_COPY(BaseFileWizard)
 173     Q_OBJECT
 174
 175 public:
 176     virtual ~BaseFileWizard();
 177
 178     // IWizard
 179     virtual WizardKind kind() const;
 180     virtual QIcon icon() const;
 181     virtual QString description() const;
 182     virtual QString displayName() const;
 183     virtual QString id() const;
 184
 185     virtual QString category() const;
 186     virtual QString displayCategory() const;
 187
 188     virtual void runWizard(const QString &path, QWidget *parent);
 189
 190     // Build a file name, adding the extension unless baseName already has one
 191     static QString buildFileName(const QString &path, const QString &baseName, const QString &extension);
 192
 193     // Sets some standard options on a QWizard
 194     static void setupWizard(QWizard *);
 195
 196     // Read "shortTitle" dynamic property of the pageId and apply it as the title of corresponding progress item
 197     static void applyExtensionPageShortTitle(Utils::Wizard *wizard, int pageId);
 198
 199 protected:
 200     typedef QList<QWizardPage *> WizardPageList;
 201
 202     explicit BaseFileWizard(const BaseFileWizardParameters &parameters, QObject *parent = 0);
 203
 204     // Overwrite to create the wizard dialog on the parent, adding
 205     // the extension pages.
 206     virtual QWizard *createWizardDialog(QWidget *parent,
 207                                         const QString &defaultPath,
 208                                         const WizardPageList &extensionPages) const = 0;
 209
 210     // Overwrite to query the parameters from the dialog and generate the files.
 211     virtual GeneratedFiles generateFiles(const QWizard *w,
 212                                          QString *errorMessage) const = 0;
 213
 214     /* Physically write files. Re-implement (calling the base implementation)
 215      * to create files with CustomGeneratorAttribute set. */
 216     virtual bool writeFiles(const GeneratedFiles &files, QString *errorMessage);
 217
 218     /* Overwrite to perform steps to be done after files are actually created.
 219      * The default implementation opens editors with the newly generated files. */
 220     virtual bool postGenerateFiles(const QWizard *w, const GeneratedFiles &l, QString *errorMessage);
 221
 222     // Utility that returns the preferred suffix for a mime type
 223     static QString preferredSuffix(const QString &mimeType);
 224
 225     // Utility that performs an overwrite check on a set of files. It checks if
 226     // the file exists, can be overwritten at all and prompts the user.
 227     enum OverwriteResult { OverwriteOk,  OverwriteError,  OverwriteCanceled };
 228     OverwriteResult promptOverwrite(const QStringList &files,
 229                                     QString *errorMessage) const;
 230
 231     // Utility to open the editors for the files whose attribute is set accordingly.
 232     static bool postGenerateOpenEditors(const GeneratedFiles &l, QString *errorMessage = 0);
 233
 234 private:
 235     BaseFileWizardPrivate *m_d;
 236 };
 237
 238 // StandardFileWizard convenience class for creating one file. It uses
 239 // Utils::FileWizardDialog and introduces a new virtual to generate the
 240 // files from path and name.
 241
 242 class CORE_EXPORT StandardFileWizard : public BaseFileWizard
 243 {
 244     Q_DISABLE_COPY(StandardFileWizard)
 245     Q_OBJECT
 246
 247 protected:
 248     explicit StandardFileWizard(const BaseFileWizardParameters &parameters, QObject *parent = 0);
 249
 250     // Implemented to create a Utils::FileWizardDialog
 251     virtual QWizard *createWizardDialog(QWidget *parent,
 252                                         const QString &defaultPath,
 253                                         const WizardPageList &extensionPages) const;
 254     // Implemented to retrieve path and name and call generateFilesFromPath()
 255     virtual GeneratedFiles generateFiles(const QWizard *w,
 256                                          QString *errorMessage) const;
 257
 258     // Newly introduced virtual that creates a file from a path
 259     virtual GeneratedFiles generateFilesFromPath(const QString &path,
 260                                                  const QString &name,
 261                                                  QString *errorMessage) const = 0;
 262 };
 263
 264 } // namespace Core
 265
 266 Q_DECLARE_OPERATORS_FOR_FLAGS(Core::GeneratedFile::Attributes)
 267
 268 #endif // BASEFILEWIZARD_H