/*!
\page project-file-wizard.html
\title 8. Project/File Wizards
New projects in Qt Creator can be created by clicking on the "File -> New" menu item and selecting the required project
type. Shown below is the new project dialog box.
\inlineimage qtc-newprojectdialog-8.png
In this chapter we will learn how to add new project types into the dialog box above.
\section1 8.1 Core::IWizard interface
Qt Creator provides a Core::IWizard interface that can be implemented to support new project types. The interface is
defined as follows in \bold {src/plugins/coreplugin/dialogs/iwizard.h}.
\code
class CORE_EXPORT IWizard : public QObject
{
Q_OBJECT
public:
enum Kind {FileWizard,ClassWizard,ProjectWizard};
virtual Kind kind() const = 0;
virtual QIcon icon() const = 0;
virtual QString description() const = 0;
virtual QString name() const = 0;
virtual QString category() const = 0;
virtual QString trCategory() const = 0;
virtual QStringList runWizard(const QString &path, QWidget *parent) = 0;
};
\endcode
Qt Creator supports the following types of new entities
\list
\o File
\o Class
\o Project
\endlist
\bold {Core::IWizard} has to be implemented to support any of the above project types.
\section2 8.1.1 Sample implementation of Core::IWizard
Let's implement the \bold {IWizard} interface to support a new project type called "Custom Project". The idea is to see the
new project type listed in the new project wizard that shows up on clicking "File -> New".
\section3 Step 1: Implementing the Core::IWizard interface
Lets create a class called \bold {CustomProjectWizard} and subclass it from \bold {Core::IWizard}.
\code
class CustomProjectWizard : public Core::IWizard
{
public:
CustomProjectWizard() { }
~CustomProjectWizard() { }
Core::IWizard::Kind kind() const;
QIcon icon() const;
QString description() const;
QString name() const;
QString category() const;
QString trCategory() const;
QStringList runWizard(const QString &path, QWidget *parent);
};
\endcode
Below we will discuss the implementation of each of the functions.
\bold{The kind()} function should be implemented to return the type of "new" project we support in our implementation of
\bold {IWizard}. Valid values are \bold {FileWizard},\bold{ClassWizard} and \bold {ProjectWizard}. In our implementation we return
\bold{ProjectWizard}.
\code
Core::IWizard::Kind CustomProjectWizard::kind() const
{
return IWizard::ProjectWizard;
}
\endcode
The \bold{icon()} implementation must return an icon to use against the project type in the New project dialog box. In our
implementation we return the Qt Creator icon itself.
\code
QIcon CustomProjectWizard::icon() const
{
return qApp->windowIcon();
}
\endcode
The \bold {description()},\bold {name()} and \bold {category()} methods must return some meta data of the new project/file/class
type we are providing in the \bold {IWizard} implementation.
\code
QString CustomProjectWizard::description() const
{
return "A custom project";
}
QString CustomProjectWizard::name() const
{
return "CustomProject";
}
QString CustomProjectWizard::category() const
{
return "FooCompanyInc";
}
\endcode
The \bold{trCategory()} method should be implemented to return a translated category string. This is the name that is
shown on the "New.." dialog box.
\code
QString CustomProjectWizard::trCategory() const
{
return tr("FooCompanyInc");
}
\endcode
If the user selects the "CustomProject" category supported by our implementation of \bold{IWizard} and selects Ok in the
"New.." dialog box; then the \bold{runWizard()} method is called. This method must be implemented to show a dialog box
or \bold{QWizard}, ask questions from the user about the new project/file/class being created and return a list of newly
created files. In our implementation of the \bold{IWizard} we will return an empty string list.
\code
QStringList CustomProjectWizard::runWizard(const QString &path, QWidget *parent)
{
Q_UNUSED(path);
Q_UNUSED(parent);
QMessageBox::information(parent, "Custom Wizard Dialog", "Hi there!");
return QStringList();
}
\endcode
\section3 Step 2: Providing the wizard from a plugin
We implement a custom-project plugin using the same means as described in Chapter 2. The only change is in the
\bold{initialize()} method implementation of the plugin.
\code
bool CustomProjectPlugin::initialize(const QStringList& args, QString *errMsg)
{
Q_UNUSED(args);
Q_UNUSED(errMsg);
addAutoReleasedObject(new CustomProjectWizard);
return true;
}
\endcode
\section3 Step 3: Testing the plugin
Upon compiling the plugin and restarting Qt Creator, we can notice the new project type in the "New.." dialog box. Take
a look at the screenshot below.
\inlineimage qtc-testplugin-8.png
\section1 8.2 Predefined IWizard implementation - Core::BaseFileWizard
Qt Creator's core provides a default implementation of the \bold{IWizard} interface in the form of the
\bold {Core::BaseFileWizard} class. This class implements provides default implementation of all the methods in the
\bold {IWizard} interface and adds some virtual methods of its own. To make use of the class, we need to subclass from it and
implement one or more methods.
\section2 8.2.1 Core::GeneratedFile and Core::GeneratedFiles
Normally a new wizard (\bold{IWizard} implementation) is implemented to allow the user to provide some hints and have
one or more files automatically generated. The \bold{Core::GeneratedFile} helps abstract each of the files that need
generation. We will learn later on that within subclasses of \bold{Core::BaseFileWizard}, we create an instance of
\bold{Core::GeneratedFile} for each file that is automatically generated.
The \bold{Core::GeneratedFile} class is defined as follows in \bold{coreplugin/basefilewizard.h}
\code
class GeneratedFile
{
public:
GeneratedFile();
explicit GeneratedFile(const QString &path);
GeneratedFile(const GeneratedFile &);
GeneratedFile &operator=(const GeneratedFile &);
~GeneratedFile();
QString path() const;
void setPath(const QString &p);
QString contents() const;
void setContents(const QString &c);
QString editorKind() const;
void setEditorKind(const QString &k);
bool write(QString *errorMessage) const;
private:
QSharedDataPointer m_d;
};
typedef QList GeneratedFiles;
\endcode
Files that need to be generated by subclasses of \bold {Core::BaseFileWizard} are represented by the
\bold {Core::GeneratedFile} class. The class contains three key properties of a file that needs generation
\list 1
\o Name of the file (with its absolute path).
\o The kind of editor needed for editing the file. Some valid values for editor kind are
\list a
\o \bold{CppEditor::Constants::CPPEDITOR_KIND}
\o \bold{GenericProjectManager::Constants::PROJECT_KIND}
\o \bold{Git::Constants:: GIT_COMMAND_LOG_EDITOR_KIND}
\o \bold {Git::Constants:: C_GIT_COMMAND_LOG_EDITOR}
\endlist
\o Contents of the file.
\endlist
Suppose that we wanted to generate a C++ source file with the following contents
\code
#include
int main()
{
cout << "Hello World\n";
return 0;
}
\endcode
We would use \bold{Core::GeneratedFile} for generating the above contents as follows
\code
#include
#include
Core::GeneratedFile genFile("C:/Path/To/Source.cpp");
genFile.setEditorKind(CppEditor::Constants::CPPEDITOR_KIND);
genFile.setContents(
"#include \n"
"\n"
"int main()\n"
"{\n"
" cout << \"Hello World\n\";\n"
" \n"
" return 0;\n"
"}
);
genFile.write();
\endcode
\section2 8.2.2 The "Item Model" class wizard
Suppose that we wanted to provide a new class wizard that helps automatically generate the skeleton of an item model
based on few hints like
\list
\o Model Class Name
\o Base Class Name (can be \bold {QAbstractItemModel},\bold QAbstractListModel and
\bold{QAbstractTableModel})
\o Header file name and
\o Source file name
\endlist
Lets implement a plugin that will provide the new "Item Model" class wizard in Qt Creator.
\section3 Step 1: Design the class wizard page
Lets design a simple page in Qt Designer that accepts hints as described above.
\inlineimage qtc-designer-8.png
The design is saved as ModelNamePage.ui.
\section3 Step 2: Implement the class wizard page
Lets import the UI in a Qt/C++ and provide easy to use methods to help fetch information from the page. First we design
a structure that captures all the "item model" class hints.
\code
struct ModelClassParameters
{
QString className;
QString headerFile;
QString sourceFile;
QString baseClass;
QString path;
};
\endcode
Next we declare a wizard page class that imports the UI designed in the previous step and provides methods to access
the hints provided by the user in the page.
\code
#include
#include "ui_ModelNamePage.h"
class ModelNamePage : public QWizardPage
{
Q_OBJECT
public:
ModelNamePage(QWidget* parent=0);
~ModelNamePage();
void setPath(const QString& path);
ModelClassParameters parameters() const;
private slots:
void on_txtModelClass_textEdited(const QString& txt);
private:
Ui::ModelNamePage ui;
QString path;
};
\endcode
The constructor and destructor are straight forward and easy to understand.
\code
ModelNamePage::ModelNamePage(QWidget* parent)
:QWizardPage(parent)
{
setTitle("Enter model class information");
setSubTitle("The header and source file names will be derived from the class name");
ui.setupUi(this);
}
ModelNamePage::~ModelNamePage()
{
}
\endcode
The \bold{setPath()} method basically stores the path in the private variable.
\code
void ModelNamePage::setPath(const QString& path)
{
this->path = path;
}
\endcode
The \bold{on_txtModelClass_textEdited()} slot computes the header and source file names based on the
classname.
\code
void ModelNamePage::on_txtModelClass_textEdited(const QString& txt)
{
ui.txtHeaderFile->setText(txt + ".h");
ui.txtImplFile->setText(txt + ".cpp");
}
\endcode
Finally the \bold{parameters()} method returns all the hints entered by the user in a ModelClassParameters
instance.
\code
ModelClassParameters ModelNamePage::parameters() const
{
ModelClassParameters params;
params.className = ui.txtModelClass->text();
params.headerFile = ui.txtHeaderFile->text();
params.sourceFile = ui.txtImplFile->text();
params.baseClass = ui.cmbBaseClass->currentText();
params.path = path;
return params;
}
\endcode
\section3 Step 3: Subclass Core::BaseFileWizard
The\bold {Core::BaseFileWizard} class is defined as follows in \bold{coreplugin/basefilewizard.h}
\code
class CORE_EXPORT BaseFileWizard : public IWizard
{
public:
virtual ~BaseFileWizard();
// IWizard
virtual Kind kind() const;
virtual QIcon icon() const;
virtual QString description() const;
virtual QString name() const;
virtual QString category() const;
virtual QString trCategory() const;
virtual QStringList runWizard(const QString &path, QWidget *parent);
protected:
typedef QList WizardPageList;
explicit BaseFileWizard(const BaseFileWizardParameters ¶meters,QObject *parent = 0);
virtual QWizard *createWizardDialog(QWidget *parent,const QString &defaultPath,
const WizardPageList &extensionPages) const = 0;
virtual GeneratedFiles generateFiles(const QWizard *w,QString *errorMessage) const = 0;
virtual bool postGenerateFiles(const GeneratedFiles &l,QString *errorMessage);
};
\endcode
\underline {\bold{Note: Some methods from the actual BaseFileWizard class are not shown here.}}
The \bold{BaseFileWizard} class implements the \bold{IWizard} interface and offers three new functions
\list
\o \bold{createWizardDialog} - This function can be over-ridden by subclasses to provide a wizard that the
\bold{runWizard()} method is supposed to show.
\list
\o The \bold{parent} parameter should be used as the parent widget of the returned QWizard
\o The \bold{defaultPath} parameter should be the default location for generated files
\o The \bold{extensionPages} parameter lists out all the pages that should be shown in the wizard by default.
\endlist
\o \bold{generateFiles} - This method is called after the user is done with the wizard. Implementations of this
method must create the required files as instances of \bold{Core::GeneratedFile} class.
\o \bold{postGenerateFiles} - This method is called after \bold{generateFiles()} returns. The default
implementation opens the newly generated files; however subclasses can choose to do anything they want.
\endlist
We subclass the BaseFileWizard as follows for our "item model" wizard
\code
#include
class ModelClassWizard : public Core::BaseFileWizard
{
Q_OBJECT
public:
ModelClassWizard(const Core::BaseFileWizardParameters ¶meters,
QObject *parent = 0);
~ModelClassWizard();
QWizard *createWizardDialog(QWidget *parent,
const QString &defaultPath,
const WizardPageList &extensionPages) const;
Core::GeneratedFiles generateFiles(const QWizard *w,
QString *errorMessage) const;
private:
QString readFile(const QString& fileName,
const QMap& replacementMap) const;
};
\endcode
The constructor and destructor methods are straight forward and easy to understand.
\code
ModelClassWizard::ModelClassWizard(
const Core::BaseFileWizardParameters ¶meters,QObject *parent)
: Core::BaseFileWizard(parameters, parent)
{
}
ModelClassWizard::~ModelClassWizard()
{
}
\endcode
The \bold{createWizardDialog()} method is implemented to create a \bold{QWizard} with its first page as the
\bold{ModelNamePage} class implemented step 2. Other default pages are added as usual.
\code
QWizard* ModelClassWizard::createWizardDialog(
QWidget *parent,
const QString &defaultPath,
const WizardPageList &extensionPages) const
{
// Create a wizard
QWizard* wizard = new QWizard(parent);
wizard->setWindowTitle("Model Class Wizard");
// Make our page as first page
ModelNamePage* page = new ModelNamePage(wizard);
int pageId = wizard->addPage(page);
wizard->setProperty("_PageId_", pageId);
page->setPath(defaultPath);
// Now add the remaining pages
foreach (QWizardPage *p, extensionPages)
wizard->addPage(p);
return wizard;
}
\endcode
The \bold{readFile()} method is implemented to read a file and return its contents as a string. Before returning the file's
contents as string, the function uses the replacement table passed as second parameter to fix the string.
\code
QString ModelClassWizard::readFile(const QString& fileName, const QMap&
replacementMap) const
{
QFile file(fileName);
file.open(QFile::ReadOnly);
QString retStr = file.readAll();
QMap::const_iterator it = replacementMap.begin();
QMap::const_iterator end = replacementMap.end();
while(it != end)
{
retStr.replace(it.key(), it.value());
++it;
}
return retStr;
}
\endcode
Suppose we have a file (\bold{sample.txt}) whose contents are as follows
\code
#ifndef {{UPPER_CLASS_NAME}}_H
#define {{UPPER_CLASS_NAME}}_H
#include <{{BASE_CLASS_NAME}}>
struct {{CLASS_NAME}}Data;
class {{CLASS_NAME}} : public {{BASE_CLASS_NAME}}
{
Q_OBJECT
public:
{{CLASS_NAME}}(QObject* parent=0);
~{{CLASS_NAME}}();
int rowCount(const QModelIndex& parent) const;
QVariant data(const QModelIndex& index, int role) const;
private:
{{CLASS_NAME}}Data* d;
};
#endif // {{UPPER_CLASS_NAME}}_H
\endcode
Lets say we wanted to replace the hints in {{xyz}} with something more appropriate, we could use the following code
snippet.
\code
QMap replacementMap;
replacementMap["{{UPPER_CLASS_NAME}}"] = "LIST_MODEL";
replacementMap["{{BASE_CLASS_NAME}}"] = "QAbstractListModel";
replacementMap["{{CLASS_NAME}}"] = "ListModel";
QString contents = readFile("Sample.txt", replacementTable);
\endcode
When the above code is executed, the contents string will contain
\code
#ifndef LIST_MODEL_H
#define LIST_MODEL_H
#include
struct ListModelData;
class ListModel : public QAbstractListModel
{
Q_OBJECT
public:
ListModel(QObject* parent=0);
~ListModel();
int rowCount(const QModelIndex& parent) const;
QVariant data(const QModelIndex& index, int role) const;
private:
ListModelData* d;
};
#endif // LIST_MODEL_H
\endcode
Seems like magic isnt it? ?. We create similar "template" header and source files for item, list and table model classes
and create a resource for use in our project.
Now, lets look at the implementation of the \bold{generateFiles()} method. This method basically creates two
\bold{Core::GeneratedFile} instances and populates them with appropriate data before returning them in a list.
\code
Core::GeneratedFiles ModelClassWizard::generateFiles(
const QWizard *w,QString *errorMessage) const
{
Q_UNUSED(errorMessage);
Core::GeneratedFiles ret;
int pageId = w->property("_PageId_").toInt();
ModelNamePage* page = qobject_cast(w->page(pageId));
if(!page)
return ret;
ModelClassParameters params = page->parameters();
QMap replacementMap;
replacementMap["{{UPPER_CLASS_NAME}}"] = params.className.toUpper();
replacementMap["{{BASE_CLASS_NAME}}"] = params.baseClass;
replacementMap["{{CLASS_NAME}}"] = params.className;
replacementMap["{{CLASS_HEADER}}"] = QFileInfo(params.headerFile).fileName();
Core::GeneratedFile headerFile(params.path + "/" + params.headerFile);
headerFile.setEditorKind(CppEditor::Constants::CPPEDITOR_KIND);
Core::GeneratedFile sourceFile(params.path + "/" + params.sourceFile);
sourceFile.setEditorKind(CppEditor::Constants::CPPEDITOR_KIND);
if(params.baseClass == "QAbstractItemModel")
{
headerFile.setContents(readFile(":/CustomProject/ItemModelHeader", replacementMap) );
sourceFile.setContents(readFile(":/CustomProject/ItemModelSource", replacementMap) );
}
else if(params.baseClass == "QAbstractTableModel")
{
headerFile.setContents(readFile(":/CustomProject/TableModelHeader", replacementMap) );
sourceFile.setContents(readFile(":/CustomProject/TableModelSource", replacementMap) );
}
else if(params.baseClass == "QAbstractListModel")
{
headerFile.setContents(readFile(":/CustomProject/ListModelHeader", replacementMap) );
sourceFile.setContents(readFile(":/CustomProject/ListModelSource", replacementMap) );
}
ret << headerFile << sourceFile;
return ret;
}
\endcode
\section3 Step 4: Implementing the plugin
We implement the item model wizard plugin using the same means as described in Chapter 2. The only change is in the
\bold {initialize()} method implementation of the plugin.
\code
bool ItemModelWizard::initialize(const QStringList& args, QString *errMsg)
{
Q_UNUSED(args);
Q_UNUSED(errMsg);
Core::BaseFileWizardParameters params;
params.setKind(Core::IWizard::ClassWizard);
params.setIcon(qApp->windowIcon());
params.setDescription("Generates an item-model class");
params.setName("Item Model");
params.setCategory("FooCompany");
params.setTrCategory(tr("FooCompany"));
addAutoReleasedObject(new ModelClassWizard(params, this));
return true;
}
\endcode
\section3 Step 5: Testing the plugin
Upon compiling the plugin and restarting Qt Creator, we can notice the new project type in the "New.." dialog box. The
following screenshots showcase the wizard that was just implemented.
\inlineimage qtc-newitemmodel-8.png
Upon selecting the "Item Model" class wizard, we can see the ModelNamePage in a custom wizard.
\inlineimage qtc-customwizardone-8.png
We enter the appropriate details and click "Next" Qt Creator then shows us a built-in page to allow addition of the
newly generated files into the current project.
\inlineimage qtc-customwizardtwo-8.png
Upon clicking "Finish", we can notice the newly generated files in the editor.
\inlineimage qtc-editor-8.png
*/