Commit d0c0c062 authored by Eike Ziller's avatar Eike Ziller
Browse files

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 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 first-plugin.html
\title Creating Your First Plugin
This section describes how to create a \QC plugin by using the plugin
template provided by \QC, and get the first impression of what
a plugin consists of and what its general structure is.
\section1 Creating a Plugin Project
\QC comes with a wizard for \QC plugins, that creates a
runable, \e minimal plugin for you. We strongly suggest that you
use two different \QC instances for developing and testing
your plugin with. Otherwise your plugin will also be loaded in your
development environment, which can make that unstable while your
plugin is still unstable. You can just create a copy of your \QC
build and use one for actually developing, and the other for testing
your plugin with.
\list 1
\o Select \gui{File > New File or Project > Other Qt Project > Qt Creator Plugin > Choose}.
\image firstplugin-wizard.png "Choose the \QC Plugin Wizard"
The \gui{Introduction and Project Location} dialog opens.
\image firstplugin-nameandpath.png "Choose Name and Place of the Project"
\o Give your project a name and specify in which path
this project will be created. The actual plugin's name can be different
from the project name. You will choose that name later in the wizard.
Continue to the next page.
The \gui{Target Setup} dialog opens.
\image firstplugin-target.png "Choose the Desktop Target and Matching Qt"
\o Select the target and Qt version to build your project with.
For a \QC plugin this needs to be the \gui{Desktop} target,
and a Qt version that is compatible with the Qt version that your
\QC was built with (in the best case the exact same build).
If you use an incompatible Qt version to build your plugin, you
will get errors while \QC tries to load your plugin.
Continue to the next page.
The \gui{Plugin Information} dialog opens.
\image firstplugin-pluginsetup.png "Specify Your Plugin Details"
\o In the \gui{Plugin name} field, type \gui{Example}. The name of the plugin
is used as its identifier, and also is the base for the file names and
classes in the code.
\o The values of the following fields are mainly informational, and
are shown in the detailed view in \QC's plugin overview
(\gui{Help > About Plugins}, or \gui{Qt Creator > About Plugins}
on Mac).
\list
\o \gui{Vendor name} is a short one-word name of the company
or organization that created the plugin. This is also used for
the path name where the plugin will be deployed to.
\o \gui{Copyright} is a one-line, short copyright string.
\o \gui{License} is a multi-line license text (but shouldn't be pages over pages long,
since the interface doesn't allow nice reading of long texts).
\o \gui{Description} is a relatively short, but
possibly multi-line description of what the plugin does.
\o \gui{URL} is a website where the user can find more
information about the plugin and/or organization providing it.
\endlist
\o Set the \gui{Qt Creator sources} and \gui{Qt Creator build} fields to
the source and build directory of the \QC
instance you want to use to test your plugin with, respectively.
If you don't do that correctly you will get compile errors for your
plugin, and your plugin might not show up in \QC at all.
\o In the \gui{Deploy into} list, select \gui{Qt Creator build}. This sets
your .pro file up to deploy your plugin directly into your \QC build's
plugin directory (requires you to have write permissions there).
The other option, \gui{Local user settings}, sets your .pro file up to
deploy your plugin into \QC's user plugin path
(for example \c{~/.config/Nokia/qtcreator/plugins} on Unix systems).
We choose \gui{Qt Creator build} because we use a self-compiled
\QC, and want the plugin to be only loaded by that \QC
instance.
Continue to the next page.
The \gui{Project Management} dialog opens.
\image firstplugin-summary.png "Summary of Created Files"
\o Review the files that will be created, choose a version control
system that \QC should use for your project (always a good idea!),
and finish the wizard.
\endlist
\section1 Building and Running the Plugin
If you passed the correct \QC source and build paths in the project
wizard, your plugin should just build fine when pressing the build button.
When you try to run your project, \QC will ask you for the executable to run and
you are presented the following dialog:
\image firstplugin-runsettings.png "Specify the Executable to Run"
Select the path to the \QC executable from the build that you specified
in the \gui{Qt Creator build} setting in the project wizard and click \gui OK.
\QC starts up, and you can verify that your plugin successfully loaded
by looking for a menu entry \gui{Tools > Example} and by looking for
the plugin in the \gui{About Plugins} dialog.
\image firstplugin-menuitem.png "Menu Registered by the Plugin"
\section1 File Structure
The plugin wizard creates a set of basic files that a plugin needs or should have.
We will have a look at some of them in detail in the following sections, here is a short
overview:
\table
\header
\o File
\o Role
\row
\o \c{Example.pluginspec.in}
\o Template plugin specification. QMake creates a \c{Example.pluginspec}
from this file, which is read by \QC to find out about the plugin.
\row
\o \c{example.pro}
\o Project file, used by QMake to generate a Makefile that then is used to
build the plugin.
\row
\o \c{example_global.h}
\o Contains macro definitions that are useful when this plugin should export
symbols to other plugins.
\row
\o \c{exampleconstants.h}
\o Header defining constants used by the plugin code.
\row
\o \c{exampleplugin.h/.cpp}
\o C++ header and source files that define the plugin class that will be
instanciated and run by \QC's plugin manager.
\endtable
\section1 qmake Project
The qmake project file \c{example.pro} defines how your plugin should be compiled.
\QC plugins need to have a specific setup there, in addition to telling qmake
which files need to be compiled (or handled by \c moc or \c uic).
Let us have a look at what the project wizard generated for you in detail.
\snippet exampleplugin/example.pro 1
The first section of the .pro file defines the very basic properties of your project,
the name (\c{TARGET}), and that a library should be generated,
since plugins are actually libraries that are dynamically loaded (\c{TEMPLATE = lib}).
The section also lets the compiler pass an \c EXAMPLE_LIBRARY define to the compiled
code, which is used in the \c{example_global.h} header, but is not really of interest
for now. You should not need to change that section of the .pro file.
\snippet exampleplugin/example.pro 2
This section tells qmake about the files of your project that it should let
compile or otherwise handle. You need to expand that section with any files
you add to the project.
\snippet exampleplugin/example.pro 3
To compile and deploy your plugin, the project needs access to the \QC sources and
build. This section contains the logic that looks for the information about
the location of the sources and build in the \c{QTC_SOURCE} and \c{QTC_BUILD}
environment variables. If these are not defined, it uses the defaults you
set in the project wizard.
So, if someone else opens your plugin project on their machine, they do not
need to edit the .pro file, but instead they should set the \c{QTC_SOURCE} and
\c{QTC_BUILD} environment variables correctly for the plugin's build environment.
You should not need to change this section, except perhaps to adapt the defaults.
\snippet exampleplugin/example.pro 4
\QC plugins can either be installed into the \QC installation's plugin directory
(requires write access there), or to a user specific plugin directory.
The \c USE_USER_DESTDIR switch in the .pro file defines which method is used for building
the plugin (which is independent from what you can later use for distributing your
plugin to other users).
\snippet exampleplugin/example.pro 5
The \c{PROVIDER} variable is for example used to deploy your plugin to a provider specific
plugin subdirectory, and the value is taken from the information that
you gave in the plugin project wizard.
\snippet exampleplugin/example.pro 6
This section includes the necessary parts from the \QC sources and makes your
plugin find the \QC libraries and plugins. The included file
\c{qtcreatorplugin.pri} makes sure that you build a plugin that is suitable
for use in \QC. The file \c{plugins/coreplugin/coreplugin.pri} makes your
plugin dependent on the Core plugin and makes sure that you can access its
public API.
If you want to use or extend functionality from other plugins, you
need to add the corresponding .pri file of the plugin here.
For more information about qmake, and writing .pro files in general,
see the \l{http://doc.qt.nokia.com/4.7/qmake-manual.html}{qmake Manual}.
\section1 Plugin Specification
The .pluginspec file is an XML file that contains information that is needed by
the plugin manager to find your plugin and resolve its dependencies before actually
loading your plugin's library file. We will only have a short look at it here.
For more information, see \l{Plugin Specifications}.
The wizard doesn't actually create a .pluginspec file directly, but instead a
.pluginspec.in file. qmake uses this to generate the actual plugin specification
file, replacing variables like \c{QTCREATOR_VERSION} with their actual values.
Therefore you need to escape all backslashes and quotes in the .pluginspec.in file
(i.e. you need to write \c{\\} to get a backslash and \c{\"} to get a quote
in the generated plugin specification).
\snippet exampleplugin/Example.pluginspec.in 1
The main tag of the plugin specification that is created by the wizard
defines the name of your plugin, its version, and with what version of this plugin
the current version is binary compatible with.
\snippet exampleplugin/Example.pluginspec.in 2
After the main tag you'll find the information about the plugin
that you gave in the project wizard.
\snippet exampleplugin/Example.pluginspec.in 3
The last section tells the plugin manager about the dependencies of this
plugin. Most \QC plugins will at least depend on the \c{Core} plugin.
\section1 Plugin Class
The files \c{exampleplugin.h} and \c{exampleplugin.cpp} define the plugin
implementation of your little plugin. We'll concentrate on some highlights
here, and give pointers to more detailed information for the various parts.
\section2 Header File
The header file \c{exampleplugin.h} defines the interface of the plugin class.
\snippet exampleplugin/exampleplugin.h namespaces
The plugin is defined in a \c{Example::Internal} namespace, which conforms to
the coding rules for \l{coding-rules-namespacing}{namespacing}
in \QC sources.
\snippet exampleplugin/exampleplugin.h base class
All \QC plugins must be derived from \l{ExtensionSystem::IPlugin} and
are QObjects.
\snippet exampleplugin/exampleplugin.h plugin methods
The base class defines basic methods that are called during the life cycle
of a plugin, which are here implemented for your new plugin.
These methods and their roles are described in detail in
\l{The Plugin Life Cycle}.
\snippet exampleplugin/exampleplugin.h slot
The plugin has an additional custom slot, that is used to pop up a dialog
when the user chooses the menu item that this plugin adds.
\section2 Source File
The source file contains the actual implementation of the plugin, which registers
a new menu and menu item, and opens a message box when that item is triggered.
All the necessary header files from the plugin code itself,
from the Core plugin, and from Qt are included in the beginning of the file.
The setup of the menu and menu item
is done in the plugin's \c{initialize} method, which is the first thing called
after the plugin constructor. In that method, the plugin can be sure that the basic
setup of plugin's that it depends on has been done, for example the Core plugin's
\c{ActionManager} instance has been created.
\snippet exampleplugin/exampleplugin.cpp add action
This part of the code creates a new \c{QAction}, registers it as a new
\c{Command} in the action manager, and connects it to the plugin's slot.
The action manager provides a central place where the user can assign and
change keyboard shortcuts, and manages cases where for example a menu item should be
directed to different plugins under different circumstances, as well as a few
other things. This is described in more detail in \l{Menus and Menu Items}.
\snippet exampleplugin/exampleplugin.cpp add menu
Here a new menu item is created, the created command added to it, and the menu
added to the \gui{Tools} menu in the menu bar. Again, this is covered in more