Commit fcdc8177 authored by Friedemann Kleint's avatar Friedemann Kleint

Documentation: Add ProjectExplorer plugin..

Reformat existing documentation to qdoc.
parent dc3c156c
......@@ -90,6 +90,11 @@
\o The core plugin. Provides the main window and managers for editors,
actions, mode windows and files, just to mention the most important ones.
\row
\o \l{ProjectExplorer}
\o The project explorer plugin. Provides base classes for
project handling.
\row
\o \l{Find}
\o Support for searching text in arbitrary widgets, and arbitrary other things.
......
......@@ -15,7 +15,8 @@ headerdirs = . \
../../src/plugins/find \
../../src/plugins/locator \
../../src/plugins/debugger \
../../src/plugins/vcsbase
../../src/plugins/vcsbase \
../../src/plugins/projectexplorer
sourcedirs = . \
../../src/libs/aggregation \
......@@ -27,7 +28,8 @@ sourcedirs = . \
../../src/plugins/find \
../../src/plugins/locator \
../../src/plugins/debugger \
../../src/plugins/vcsbase
../../src/plugins/vcsbase \
../../src/plugins/projectexplorer
# -- Generate complete documentation. Set this to 'false'
# to generate public API documentation only.
......
......@@ -39,6 +39,14 @@
#include <QtCore/QStringList>
#include <QtCore/QSysInfo>
/*!
\class ProjectExplorer::Abi
\brief Represents the Application Binary Interface (ABI) of a target platform.
\sa ProjectExplorer::ToolChain
*/
namespace ProjectExplorer {
// --------------------------------------------------------------------------
......@@ -258,6 +266,7 @@ Abi::Abi(const QString &abiString) :
else if (abiParts.at(1) == QLatin1String("windows"))
m_os = WindowsOS;
else
return;
}
......
......@@ -40,7 +40,7 @@
namespace ProjectExplorer {
// --------------------------------------------------------------------------
// ABI
// ABI (documentation inside)
// --------------------------------------------------------------------------
class PROJECTEXPLORER_EXPORT Abi
......
......@@ -46,6 +46,49 @@
using namespace ProjectExplorer;
/*!
\class ProjectExplorer::AbstractProcessStep
\brief A convenience class, which can be used as a base class instead of BuildStep.
It should be used as a base class if your buildstep just needs to run a process.
Usage:
\list
\o Use processParameters() to configure the process you want to run
(you need to do that before calling AbstractProcessStep::init()).
\o Inside YourBuildStep::init() call AbstractProcessStep::init().
\o Inside YourBuildStep::run() call AbstractProcessStep::run(), which automatically starts the proces
and by default adds the output on stdOut and stdErr to the OutputWindow.
\o If you need to process the process output override stdOut() and/or stdErr.
\endlist
The two functions processStarted() and processFinished() are called after starting/finishing the process.
By default they add a message to the output window.
Use setEnabled() to control whether the BuildStep needs to run. (A disabled BuildStep immediately returns true,
from the run function.)
\sa ProjectExplorer::ProcessParameters
*/
/*!
\fn void ProjectExplorer::AbstractProcessStep::setEnabled(bool b)
\brief Enables or disables a BuildStep.
Disabled BuildSteps immediately return true from their run method.
Should be called from init()
*/
/*!
\fn ProcessParameters *ProjectExplorer::AbstractProcessStep::processParameters()
\brief Obtain a reference to the parameters for the actual process to run.
Should be used in init()
*/
AbstractProcessStep::AbstractProcessStep(BuildStepList *bsl, const QString &id) :
BuildStep(bsl, id), m_timer(0), m_futureInterface(0),
m_enabled(true), m_ignoreReturnValue(false),
......@@ -69,6 +112,13 @@ AbstractProcessStep::~AbstractProcessStep()
delete m_outputParserChain;
}
/*!
\brief Delete all existing output parsers and start a new chain with the
given parser.
Derived classes need to call this function.
*/
void AbstractProcessStep::setOutputParser(ProjectExplorer::IOutputParser *parser)
{
delete m_outputParserChain;
......@@ -82,6 +132,10 @@ void AbstractProcessStep::setOutputParser(ProjectExplorer::IOutputParser *parser
}
}
/*!
\brief Append the given output parser to the existing chain of parsers.
*/
void AbstractProcessStep::appendOutputParser(ProjectExplorer::IOutputParser *parser)
{
if (!parser)
......@@ -97,16 +151,32 @@ ProjectExplorer::IOutputParser *AbstractProcessStep::outputParser() const
return m_outputParserChain;
}
/*!
\brief If ignoreReturnValue is set to true, then the abstractprocess step will
return success even if the return value indicates otherwise.
Should be called from init.
*/
void AbstractProcessStep::setIgnoreReturnValue(bool b)
{
m_ignoreReturnValue = b;
}
/*!
\brief Reimplemented from BuildStep::init(). You need to call this from
YourBuildStep::init()
*/
bool AbstractProcessStep::init()
{
return true;
}
/*!
\brief Reimplemented from BuildStep::init(). You need to call this from YourBuildStep::run()
*/
void AbstractProcessStep::run(QFutureInterface<bool> &fi)
{
m_futureInterface = &fi;
......@@ -172,6 +242,12 @@ void AbstractProcessStep::run(QFutureInterface<bool> &fi)
return;
}
/*!
\brief Called after the process is started.
The default implementation adds a process started message to the output message
*/
void AbstractProcessStep::processStarted()
{
emit addOutput(tr("Starting: \"%1\" %2")
......@@ -180,6 +256,12 @@ void AbstractProcessStep::processStarted()
BuildStep::MessageOutput);
}
/*!
\brief Called after the process Finished.
The default implementation adds a line to the output window
*/
void AbstractProcessStep::processFinished(int exitCode, QProcess::ExitStatus status)
{
QString command = QDir::toNativeSeparators(m_param.effectiveCommand());
......@@ -195,6 +277,12 @@ void AbstractProcessStep::processFinished(int exitCode, QProcess::ExitStatus sta
}
}
/*!
\brief Called if the process could not be started.
By default adds a message to the output window.
*/
void AbstractProcessStep::processStartupFailed()
{
emit addOutput(tr("Could not start process \"%1\" %2")
......@@ -203,6 +291,10 @@ void AbstractProcessStep::processStartupFailed()
BuildStep::ErrorMessageOutput);
}
/*!
\brief Called to test whether a prcess succeeded or not.
*/
bool AbstractProcessStep::processSucceeded(int exitCode, QProcess::ExitStatus status)
{
return exitCode == 0 && status == QProcess::NormalExit;
......@@ -217,6 +309,12 @@ void AbstractProcessStep::processReadyReadStdOutput()
}
}
/*!
\brief Called for each line of output on stdOut().
The default implementation adds the line to the application output window.
*/
void AbstractProcessStep::stdOutput(const QString &line)
{
if (m_outputParserChain)
......@@ -233,6 +331,12 @@ void AbstractProcessStep::processReadyReadStdError()
}
}
/*!
\brief Called for each line of output on StdErrror().
The default implementation adds the line to the application output window
*/
void AbstractProcessStep::stdError(const QString &line)
{
if (m_outputParserChain)
......
......@@ -50,26 +50,7 @@ QT_END_NAMESPACE
namespace ProjectExplorer {
class IOutputParser;
/*!
AbstractProcessStep is a convenience class, which can be used as a base class instead of BuildStep.
It should be used as a base class if your buildstep just needs to run a process.
Usage:
Use processParameters() to configure the process you want to run
(you need to do that before calling AbstractProcessStep::init()).
Inside YourBuildStep::init() call AbstractProcessStep::init().
Inside YourBuildStep::run() call AbstractProcessStep::run(), which automatically starts the proces
and by default adds the output on stdOut and stdErr to the OutputWindow.
If you need to process the process output override stdOut() and/or stdErr.
The two functions processStarted() and processFinished() are called after starting/finishing the process.
By default they add a message to the output window.
Use setEnabled() to control whether the BuildStep needs to run. (A disabled BuildStep immediately returns true,
from the run function.)
*/
// Documentation inside.
class PROJECTEXPLORER_EXPORT AbstractProcessStep : public BuildStep
{
Q_OBJECT
......@@ -77,35 +58,19 @@ class PROJECTEXPLORER_EXPORT AbstractProcessStep : public BuildStep
public:
virtual ~AbstractProcessStep();
/// reimplemented from BuildStep::init()
/// You need to call this from YourBuildStep::init()
virtual bool init();
/// reimplemented from BuildStep::init()
/// You need to call this from YourBuildStep::run()
virtual void run(QFutureInterface<bool> &);
virtual BuildStepConfigWidget *createConfigWidget() = 0;
virtual bool immutable() const = 0;
/// enables or disables a BuildStep
/// Disabled BuildSteps immediately return true from their run method
/// should be called from init()
void setEnabled(bool b) { m_enabled = b; }
/// obtain a reference to the parameters for the actual process to run.
/// should be used in init()
ProcessParameters *processParameters() { return &m_param; }
/// If ignoreReturnValue is set to true, then the abstractprocess step will
/// return success even if the return value indicates otherwise
/// should be called from init
void setIgnoreReturnValue(bool b);
// derived classes needs to call this function
/// Delete all existing output parsers and start a new chain with the
/// given parser.
void setOutputParser(ProjectExplorer::IOutputParser *parser);
/// Append the given output parser to the existing chain of parsers.
void appendOutputParser(ProjectExplorer::IOutputParser *parser);
ProjectExplorer::IOutputParser *outputParser() const;
......@@ -113,24 +78,11 @@ protected:
AbstractProcessStep(BuildStepList *bsl, const QString &id);
AbstractProcessStep(BuildStepList *bsl, AbstractProcessStep *bs);
/// Called after the process is started
/// the default implementation adds a process started message to the output message
virtual void processStarted();
/// Called after the process Finished
/// the default implementation adds a line to the output window
virtual void processFinished(int exitCode, QProcess::ExitStatus status);
/// Called if the process could not be started,
/// by default adds a message to the output window
virtual void processStartupFailed();
/// Called to test whether a prcess succeeded or not.
virtual bool processSucceeded(int exitCode, QProcess::ExitStatus status);
/// Called for each line of output on stdOut()
/// the default implementation adds the line to the
/// application output window
virtual void stdOutput(const QString &line);
/// Called for each line of output on StdErrror()
/// the default implementation adds the line to the
/// application output window
virtual void stdError(const QString &line);
private slots:
......
......@@ -45,6 +45,7 @@ class Environment;
namespace ProjectExplorer {
struct ApplicationLauncherPrivate;
// Documentation inside.
class PROJECTEXPLORER_EXPORT ApplicationLauncher : public QObject
{
Q_OBJECT
......
......@@ -40,6 +40,17 @@
#include <QtCore/QTimer>
#include <QtCore/QTextCodec>
/*!
\class ProjectExplorer::ApplicationLauncher
\brief Application launcher of the ProjectExplorer plugin.
Encapsulates processes running in a console or as GUI processes,
captures debug output of GUI processes on Windows (outputDebugString()).
\sa Utils::ConsoleProcess
*/
namespace ProjectExplorer {
struct ApplicationLauncherPrivate {
......
......@@ -39,6 +39,15 @@
#include <QtCore/QDir>
/*!
\class ProjectExplorer::BaseProjectWizardDialog
\brief Base class for project wizards.
Presents the introductory page and takes care of setting the folder choosen
as default projects' folder should the user wish to do that.
*/
namespace ProjectExplorer {
struct BaseProjectWizardDialogPrivate {
......
......@@ -46,10 +46,7 @@ namespace ProjectExplorer {
struct BaseProjectWizardDialogPrivate;
/* BaseProjectWizardDialog: Presents the introductory
* page and takes care of setting the directory as default
* should the user wish to do that. */
// Documentation inside.
class PROJECTEXPLORER_EXPORT BaseProjectWizardDialog : public Utils::Wizard
{
Q_OBJECT
......
......@@ -36,9 +36,15 @@
using namespace ProjectExplorer;
///
/// RunConfigurationsModel
///
/*!
\class ProjectExplorer::BuildConfigurationModel
\brief A model to represent the build configurations of a target.
To be used in for the drop down of comboboxes.
Does automatically adjust itself to added and removed BuildConfigurations
Very similar to the Run Configuration Model.
TODO might it possible to share code without making the code a complete mess.
*/
class BuildConfigurationComparer
{
......
......@@ -39,12 +39,7 @@ namespace ProjectExplorer {
class Target;
class BuildConfiguration;
/*! A model to represent the build configurations of a target.
To be used in for the drop down of comboboxes
Does automatically adjust itself to added and removed BuildConfigurations
Very similar to the Run Configuration Model
TOOD might it possible to share code without making the code a complete mess
*/
// Documentation inside.
class BuildConfigurationModel : public QAbstractListModel
{
Q_OBJECT
......
......@@ -37,6 +37,75 @@
#include "deployconfiguration.h"
#include "target.h"
/*!
\class ProjectExplorer::BuildStep
\brief BuildSteps are the primary way plugin developers can customize
how their projects (or projects from other plugins) are build.
Building a project, is done by taking the list of buildsteps
from the project and calling first init() than run() on them.
That means to change the way your project is build, reimplemnt
this class and add your Step to the buildStep list of the project.
Note: The projects own the buildstep, do not delete them yourself.
init() is called in the GUI thread and can be used to query the
project for any information you need.
run() is run via QtConccurrent in a own thread, if you need an
eventloop you need to create it yourself!
*/
/*!
\fn bool ProjectExplorer::BuildStep::init()
This function is run in the gui thread,
use it to retrieve any information that you need in run()
*/
/*!
\fn void ProjectExplorer::BuildStep::run(QFutureInterface<bool> &fi)
Reimplement this. This function is called when the target is build.
This function is NOT run in the gui thread. It runs in its own thread
If you need an event loop, you need to create one.
The absolute minimal implementation is:
\code
fi.reportResult(true);
\endcode
*/
/*!
\fn BuildStepConfigWidget *ProjectExplorer::BuildStep::createConfigWidget()
Returns the Widget shown in the target settings dialog for this buildStep;
ownership is transferred to the caller.
*/
/*!
\fn bool ProjectExplorer::BuildStep::immutable() const
If this function returns true, the user can't delete this BuildStep for this target
and the user is prevented from changing the order immutable steps are run
the default implementation returns false.
*/
/*!
\fn void ProjectExplorer::BuildStep::addTask(const ProjectExplorer::Task &task)
\brief Add a task.
*/
/*!
\fn void addOutput(const QString &string, ProjectExplorer::BuildStep::OutputFormat format,
ProjectExplorer::BuildStep::OutputNewlineSetting newlineSetting)
The string is added to the generated output, usually in the output window.
It should be in plain text, with the format in the parameter.
*/
using namespace ProjectExplorer;
BuildStep::BuildStep(BuildStepList *bsl, const QString &id) :
......
......@@ -47,28 +47,9 @@ class BuildStepList;
class DeployConfiguration;
class Target;
/*
// BuildSteps are the primary way plugin developers can customize
// how their projects (or projects from other plugins) are build.
//
// Building a project, is done by taking the list of buildsteps
// from the project and calling first init() than run() on them.
//
// That means to change the way your project is build, reimplemnt
// this class and add your Step to the buildStep list of the project.
//
// Note: The projects own the buildstep, do not delete them yourself.
//
// init() is called in the GUI thread and can be used to query the
// project for any information you need.
//
// run() is run via QtConccurrent in a own thread, if you need an
// eventloop you need to create it yourself!
//
*/
class BuildStepConfigWidget;
// Documentation inside.
class PROJECTEXPLORER_EXPORT BuildStep : public ProjectConfiguration
{
Q_OBJECT
......@@ -80,24 +61,12 @@ protected:
public:
virtual ~BuildStep();
// This function is run in the gui thread,
// use it to retrieve any information that you need in run()
virtual bool init() = 0;
// Reimplement this. This function is called when the target is build.
// This function is NOT run in the gui thread. It runs in its own thread
// If you need an event loop, you need to create one.
// The absolute minimal implementation is:
// fi.reportResult(true);
virtual void run(QFutureInterface<bool> &fi) = 0;
// the Widget shown in the target settings dialog for this buildStep
// ownership is transferred to the caller
virtual BuildStepConfigWidget *createConfigWidget() = 0;
// if this function returns true, the user can't delete this BuildStep for this target
// and the user is prevented from changing the order immutable steps are run
// the default implementation returns false
virtual bool immutable() const;
BuildConfiguration *buildConfiguration() const;
......@@ -108,12 +77,8 @@ public:
enum OutputNewlineSetting { DoAppendNewline, DontAppendNewline };
signals:
// Add a task.
void addTask(const ProjectExplorer::Task &task);
// The string is added to the generated output, usually in the output
// window.
// It should be in plain text, with the format in the parameter
void addOutput(const QString &string, ProjectExplorer::BuildStep::OutputFormat format,
ProjectExplorer::BuildStep::OutputNewlineSetting newlineSetting = DoAppendNewline);
};
......
......@@ -55,6 +55,20 @@ static const char configFileC[] = "wizard.xml";
namespace ProjectExplorer {
/*!
\class ProjectExplorer::ICustomWizardFactory
\brief Factory for creating custom wizards extending the base class
(CustomWizard or CustomProjectWizard)
The factory can be registered under a name in CustomWizard. The name can
be specified in the \c <wizard class=''...> attribute in the \c wizard.xml file
and thus allows for specifying a C++ derived wizard class.
For example, this is currently used in Qt4ProjectManager to get Qt-specific
aspects into the custom wizard.
\sa ProjectExplorer::CustomWizard, ProjectExplorer::CustomProjectWizard
*/
struct CustomWizardPrivate {
CustomWizardPrivate() : m_context(new Internal::CustomWizardContext) {}
......@@ -65,6 +79,16 @@ struct CustomWizardPrivate {
int CustomWizardPrivate::verbose = 0;
/*!
\class ProjectExplorer::CustomWizard
\brief Base classes for custom wizards based on file templates and a XML
configuration file (\c share/qtcreator/templates/wizards).
Presents CustomWizardDialog (fields page containing path control) for wizards
of type "class" or "file". Serves as base class for project wizards.
*/
CustomWizard::CustomWizard(const Core::BaseFileWizardParameters& baseFileParameters,
QObject *parent) :
Core::BaseFileWizard(baseFileParameters, parent),
......@@ -379,8 +403,16 @@ static QString listWizards()
return rc;
}
// Scan the subdirectories of the template directory for directories
// containing valid configuration files and parse them into wizards.
/*!
\brief Reads \c share/qtcreator/templates/wizards and creates all custom wizards.
As other plugins might register factories for derived
classes, call it in extensionsInitialized().
Scans the subdirectories of the template directory for directories
containing valid configuration files and parse them into wizards.
*/
QList<CustomWizard*> CustomWizard::createWizards()
{
QList<CustomWizard*> rc;
......@@ -464,7 +496,17 @@ QList<CustomWizard*> CustomWizard::createWizards()
return rc;
}
// --------------- CustomProjectWizard
/*!
\class ProjectExplorer::CustomProjectWizard
\brief A custom project wizard.
Presents a CustomProjectWizardDialog (Project intro page and fields page)
for wizards of type "project".
Overwrites postGenerateFiles() to open the project files according to the
file attributes. Also inserts \c '%ProjectName%' into the base
replacement map once the intro page is left to have it available
for QLineEdit-type fields' default text.
*/
CustomProjectWizard::CustomProjectWizard(const Core::BaseFileWizardParameters& baseFileParameters,
QObject *parent) :
......@@ -472,6 +514,12 @@ CustomProjectWizard::CustomProjectWizard(const Core::BaseFileWizardParameters& b
{
}
/*!
\brief Can be reimplemented to create custom project wizards.
initProjectWizardDialog() needs to be called.
*/
QWizard *CustomProjectWizard::createWizardDialog(QWidget *parent,
const QString &defaultPath,
const WizardPageList &extensionPages) const
......@@ -529,6 +577,11 @@ Core::GeneratedFiles CustomProjectWizard::generateFiles(const QWizard *w, QStrin
return generatedFiles;
}
/*!
\brief Utility to open the projects and editors for the files that have
the respective attributes set.
*/
bool CustomProjectWizard::postGenerateOpen(const Core::GeneratedFiles &l, QString *errorMessage)
{
// Post-Generate: Open the project and the editors as desired
......
......@@ -59,11 +59,7 @@ namespace Internal {
struct CustomWizardContext;
}
// Factory for creating custom wizards derived from the base classes
// The factory can be registered under a name in CustomWizard. The name can
// be specified in the <wizard class=''...> attribute in the wizard.xml file
// and thus allows for specifying a C++ derived wizard class (see Qt4ProjectManager).
// Documentation inside.
class ICustomWizardFactory {
public:
virtual CustomWizard *create(const Core::BaseFileWizardParameters& baseFileParameters,
......@@ -78,10 +74,7 @@ template <class Wizard> class CustomWizardFactory : public ICustomWizardFactory
{ return new Wizard(baseFileParameters, parent); }
};
// A custom wizard presenting CustomWizardDialog (fields page containing
// path control) for wizards of type "class" or "file". Serves as base class
// for project wizards.
// Documentation inside.
class PROJECTEXPLORER_EXPORT CustomWizard : public Core::BaseFileWizard
{
Q_OBJECT
......@@ -137,13 +130,7 @@ private:
CustomWizardPrivate *d;
};
// A custom project wizard presenting CustomProjectWizardDialog
// (Project intro page and fields page) for wizards of type "project".
// Overwrites postGenerateFiles() to open the project files according to the
// file attributes. Also inserts '%ProjectName%' into the base
// replacement map once the intro page is left to have it available
// for QLineEdit-type fields' default text.
// Documentation inside.