Commit d0c0c062 authored by Eike Ziller's avatar Eike Ziller

Start on Creating Plugins documentation.

Change-Id: Ic75775473cfb405cee5c53b2dc24144dba51a25c
Reviewed-by: default avatarLeena Miettinen <riitta-leena.miettinen@nokia.com>
parent b0426616
......@@ -517,6 +517,7 @@
\section1 Patterns and Practices
\target coding-rules-namespacing
\section2 Namespacing
Read \l {http://wiki.qt-project.org/index.php/Qt_In_Namespace}{Qt In Namespace}
......
/****************************************************************************
**
** This file is part of Qt Creator
**
** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
**
** Contact: Nokia Corporation (info@qt.nokia.com)
**
**
** GNU Free Documentation License
**
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of this
** file.
**
** If you have questions regarding the use of this file, please contact
** Nokia at info@qt.nokia.com.
**
****************************************************************************/
/*!
\page creating-plugins.html
\title Creating Plugins
At its very core, \QC consists of a plugin loader that loads
and runs a set of plugins, which then actually provide the functionality
that you know from \QC the IDE. So, even the main application window
and menus are all provided by plugins. Plugins can use different means
to provide other plugins access to their functionality and to allow them
to extend certain aspects of the application.
For example the "Core" plugin, which is the very basic plugin that must be
present for \QC to run at all, provides the main window itself, and API
for adding menu items, modes, editor types, navigation panels and many other
things.
The "TextEditor" plugin provides a framework and base implementation for
different text editors with highlighting, completion and folding, that
is then used by other plugins to add more specialized text editor types
to \QC, like for editing C/C++ or .pro files.
After reading this guide you will know what a basic plugin consists of,
how to write a plugin specification file, what the lifecycle of a plugin is,
what the general principles for extending existing plugins'
functionality and providing interfaces for other plugins are, and will
be able to write your first plugin.
\section1 Basics
\list
\o \l{Getting and Building Qt Creator}
\o \l{Creating Your First Plugin}
\o \l{Plugin Specifications}
\o \l{Plugin Life Cycle}
\endlist
\section1 Design Principles
\list
\o \l{The Plugin Manager, the Object Pool, and Registered Objects}
\o \l{Aggregations}
\o \l{Extending and Providing Interfaces}
\endlist
\section1 Creating 3rd-Party Plugins
\list
\o \l{A Note on Binary Compatibility}
\o \l{Creating User-Installable Plugins}
\endlist
*/
//! [1]
<plugin name=\"Example\" version=\"0.0.1\" compatVersion=\"0.0.1\">
//! [1]
//! [2]
<vendor>MyCompany</vendor>
<copyright>(C) MyCompany</copyright>
<license>BSD</license>
<description>Minimal plugin example</description>
<url>http://www.mycompany.com</url>
//! [2]
//! [3]
<dependencyList>
<dependency name=\"Core\" version=\"$$QTCREATOR_VERSION\"/>
</dependencyList>
//! [3]
</plugin>
#! [1]
TARGET = Example
TEMPLATE = lib
DEFINES += EXAMPLE_LIBRARY
#! [1]
# Example files
#! [2]
SOURCES += exampleplugin.cpp
HEADERS += exampleplugin.h\
example_global.h\
exampleconstants.h
#! [2]
# Qt Creator linking
#! [3]
## set the QTC_SOURCE environment variable to override the setting here
QTCREATOR_SOURCES = $$(QTC_SOURCE)
isEmpty(QTCREATOR_SOURCES):QTCREATOR_SOURCES=/Users/example/qtcreator-src
## set the QTC_BUILD environment variable to override the setting here
IDE_BUILD_TREE = $$(QTC_BUILD)
isEmpty(IDE_BUILD_TREE):IDE_BUILD_TREE=/Users/example/qtcreator-build
#! [3]
#! [4]
## uncomment to build plugin into user config directory
## <localappdata>/plugins/<ideversion>
## where <localappdata> is e.g.
## "%LOCALAPPDATA%\Nokia\qtcreator" on Windows Vista and later
## "$XDG_DATA_HOME/Nokia/qtcreator" or "~/.local/share/Nokia/qtcreator" on Linux
## "~/Library/Application Support/Nokia/Qt Creator" on Mac
# USE_USER_DESTDIR = yes
#! [4]
#![5]
PROVIDER = MyCompany
#![5]
#![6]
include($$QTCREATOR_SOURCES/src/qtcreatorplugin.pri)
include($$QTCREATOR_SOURCES/src/plugins/coreplugin/coreplugin.pri)
LIBS += -L$$IDE_PLUGIN_PATH/Nokia
#![6]
#ifndef EXAMPLE_GLOBAL_H
#define EXAMPLE_GLOBAL_H
#include <QtCore/QtGlobal>
#if defined(EXAMPLE_LIBRARY)
# define EXAMPLESHARED_EXPORT Q_DECL_EXPORT
#else
# define EXAMPLESHARED_EXPORT Q_DECL_IMPORT
#endif
#endif // EXAMPLE_GLOBAL_H
#ifndef EXAMPLECONSTANTS_H
#define EXAMPLECONSTANTS_H
namespace Example {
namespace Constants {
const char ACTION_ID[] = "Example.Action";
const char MENU_ID[] = "Example.Menu";
} // namespace Example
} // namespace Constants
#endif // EXAMPLECONSTANTS_H
#include "exampleplugin.h"
#include "exampleconstants.h"
#include <coreplugin/icore.h>
#include <coreplugin/icontext.h>
#include <coreplugin/actionmanager/actionmanager.h>
#include <coreplugin/actionmanager/command.h>
#include <coreplugin/actionmanager/actioncontainer.h>
#include <coreplugin/coreconstants.h>
#include <QtGui/QAction>
#include <QtGui/QMessageBox>
#include <QtGui/QMainWindow>
#include <QtGui/QMenu>
#include <QtCore/QtPlugin>
using namespace Example::Internal;
ExamplePlugin::ExamplePlugin()
{
// Create your members
}
ExamplePlugin::~ExamplePlugin()
{
// Unregister objects from the plugin manager's object pool
// Delete members
}
bool ExamplePlugin::initialize(const QStringList &arguments, QString *errorString)
{
// Register objects in the plugin manager's object pool
// Load settings
// Add actions to menus
// Connect to other plugins' signals
// In the initialize method, a plugin can be sure that the plugins it
// depends on have initialized their members.
Q_UNUSED(arguments)
Q_UNUSED(errorString)
//! [add action]
Core::ActionManager *am = Core::ICore::instance()->actionManager();
QAction *action = new QAction(tr("Example action"), this);
Core::Command *cmd = am->registerAction(action, Constants::ACTION_ID,
Core::Context(Core::Constants::C_GLOBAL));
cmd->setDefaultKeySequence(QKeySequence(tr("Ctrl+Alt+Meta+A")));
connect(action, SIGNAL(triggered()), this, SLOT(triggerAction()));
//! [add action]
//! [add menu]
Core::ActionContainer *menu = am->createMenu(Constants::MENU_ID);
menu->menu()->setTitle(tr("Example"));
menu->addAction(cmd);
am->actionContainer(Core::Constants::M_TOOLS)->addMenu(menu);
//! [add menu]
return true;
}
void ExamplePlugin::extensionsInitialized()
{
// Retrieve objects from the plugin manager's object pool
// In the extensionsInitialized method, a plugin can be sure that all
// plugins that depend on it are completely initialized.
}
ExtensionSystem::IPlugin::ShutdownFlag ExamplePlugin::aboutToShutdown()
{
// Save settings
// Disconnect from signals that are not needed during shutdown
// Hide UI (if you add UI that is not in the main window directly)
return SynchronousShutdown;
}
//! [slot implementation]
void ExamplePlugin::triggerAction()
{
QMessageBox::information(Core::ICore::instance()->mainWindow(),
tr("Action triggered"),
tr("This is an action from Example."));
}
//! [slot implementation]
//! [export plugin]
Q_EXPORT_PLUGIN2(Example, ExamplePlugin)
//! [export plugin]
#ifndef EXAMPLE_H
#define EXAMPLE_H
#include "example_global.h"
#include <extensionsystem/iplugin.h>
//! [namespaces]
namespace Example {
namespace Internal {
//! [namespaces]
//! [base class]
class ExamplePlugin : public ExtensionSystem::IPlugin
{
Q_OBJECT
//! [base class]
public:
ExamplePlugin();
~ExamplePlugin();
//! [plugin methods]
bool initialize(const QStringList &arguments, QString *errorString);
void extensionsInitialized();
ShutdownFlag aboutToShutdown();
//! [plugin methods]
//! [slot]
private slots:
void triggerAction();
//! [slot]
};
} // namespace Internal
} // namespace Example
#endif // EXAMPLE_H
This diff is collapsed.
/****************************************************************************
**
** This file is part of Qt Creator
**
** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
**
** Contact: Nokia Corporation (info@qt.nokia.com)
**
**
** GNU Free Documentation License
**
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of this
** file.
**
** If you have questions regarding the use of this file, please contact
** Nokia at info@qt.nokia.com.
**
****************************************************************************/
/*!
\page getting-and-building.html
\title Getting and Building Qt Creator
\code
TODO: This should be extended.
* How to avoid building Qt
* Windows specific hassle, see README in \QC sources
\endcode
There are several reasons why you might want to do your own build of \QC,
like using the most current development version and being able to tweak
\QC at one or the other place. It is also necessary if you want to
create your own \QC plugin.
\section1 Getting and Building Qt
\QC usually uses the latest stable release of Qt,
you can see the exact minimum requirement at the top of \QC's qtcreator.pro.
(You can find the current version in our source repository here:
\l{https://qt.gitorious.org/qt-creator/qt-creator/blobs/master/qtcreator.pro}.)
You find the sources for the different Qt versions for example on our gitorious repository
\l{http://qt.gitorious.org/qt}.
\QC requires private headers of Qt, which are unfortunately not installed
by the Qt binary packages, and also are not copied to the installation directory when
using \c{make install} on a self-compiled Qt. To solve this problem
configure Qt with the \c{-developer-build} option, which sets the install
directory to the build directory itself (you are not required to run
\c{make install} in that case).
In Linux and Mac terminals, enter the following commands:
\code
cd <QtSources>
./configure -developer-build
make
\endcode
On Windows, open a command prompt where your developer tools are set up, and enter
the following commands for MSVC builds
\code
cd <QtSources>
configure -developer-build
nmake
\endcode
If you really need to use a Qt build that does not have private headers in its
installation directory, you can set the \c{QT_PRIVATE_HEADERS} qmake variable
to the include path which contains them, when running qmake on the \QC
sources (see below).
\section1 Getting and Building \QC
You can get the \QC sources for a specific version either by using one of the
released source bundles, or from the Gitorious repository
\l{http://qt.gitorious.org/qt-creator}. If you intend to contribute to \QC
itself, you should use the repository from our Gerrit review tool as described
in the developer wiki here: \l{http://wiki.qt-project.org/Setting_up_Gerrit}.
We strongly encourage you to do out-of-source builds of \QC (also called
shadow-builds).
After you put the \QC sources somewhere (lets call the path \c{<QtCreatorSources>})
you build it on Linux and Mac with
\code
cd <QtCreatorSources>/..
mkdir qtcreator-build
cd qtcreator-build
<QtInstall>/bin/qmake -r <QtCreatorSources>
make
\endcode
or the corresponding commands on Windows systems.
If your Qt installation does not contain private headers (see above), you can point \QC
to the private headers by setting the \c{QT_PRIVATE_HEADERS} qmake variable
to the include directory that contains them. On Linux and Mac, enter the following command
instead of the qmake call above:
\code
<QtInstall>/bin/qmake -r QT_PRIVATE_HEADERS=<QtSources>/include <QtCreatorSources>
\endcode
*/
......@@ -22,7 +22,6 @@
/*!
\page index.html
\title Extending Qt Creator Manual
\nextpage
Qt Creator is a cross-platform integrated development environment (IDE)
tailored to the needs of Qt developers.
......
......@@ -41,9 +41,9 @@ showinternal = true
headers.fileextensions = "*.h"
sources.fileextensions = "*.cpp *.qdoc"
imagedirs = $SRCDIR/images $SRCDIR/templates/images
imagedirs = $SRCDIR/api/images $SRCDIR/images $SRCDIR/templates/images
outputdir = $OUTDIR
exampledirs = ../api/examples
exampledirs = $SRCDIR/api/examples
indexes = qt.index
include(compat.qdocconf)
......
......@@ -51,6 +51,9 @@ DEV_HELP_DEP_FILES = \
$$PWD/api/external-tool-spec.qdoc \
$$PWD/api/qtcreator-dev.qdoc \
$$PWD/api/qtcreator-dev-wizards.qdoc \
$$PWD/api/creating-plugins.qdoc \
$$PWD/api/getting-and-building.qdoc \
$$PWD/api/first-plugin.qdoc \
$$PWD/api/qtcreator-dev.qdocconf
dev_html_docs.commands = $$qdoc($$OUT_PWD/doc/html-dev) $$PWD/api/qtcreator-dev.qdocconf
......
......@@ -33,9 +33,9 @@ bool %PluginName%Plugin::initialize(const QStringList &arguments, QString *error
// Register objects in the plugin manager's object pool
// Load settings
// Add actions to menus
// connect to other plugins' signals
// "In the initialize method, a plugin can be sure that the plugins it
// depends on have initialized their members."
// Connect to other plugins' signals
// In the initialize method, a plugin can be sure that the plugins it
// depends on have initialized their members.
Q_UNUSED(arguments)
Q_UNUSED(errorString)
......@@ -58,8 +58,8 @@ bool %PluginName%Plugin::initialize(const QStringList &arguments, QString *error
void %PluginName%Plugin::extensionsInitialized()
{
// Retrieve objects from the plugin manager's object pool
// "In the extensionsInitialized method, a plugin can be sure that all
// plugins that depend on it are completely initialized."
// In the extensionsInitialized method, a plugin can be sure that all
// plugins that depend on it are completely initialized.
}
ExtensionSystem::IPlugin::ShutdownFlag %PluginName%Plugin::aboutToShutdown()
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment