diff --git a/doc/api/coding-style.qdoc b/doc/api/coding-style.qdoc index 8836532846e..b42f63d3b95 100644 --- a/doc/api/coding-style.qdoc +++ b/doc/api/coding-style.qdoc @@ -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} diff --git a/doc/api/creating-plugins.qdoc b/doc/api/creating-plugins.qdoc new file mode 100644 index 00000000000..29af076e79c --- /dev/null +++ b/doc/api/creating-plugins.qdoc @@ -0,0 +1,68 @@ +/**************************************************************************** +** +** 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 +*/ diff --git a/doc/api/examples/exampleplugin/Example.pluginspec.in b/doc/api/examples/exampleplugin/Example.pluginspec.in new file mode 100644 index 00000000000..6a99316d1aa --- /dev/null +++ b/doc/api/examples/exampleplugin/Example.pluginspec.in @@ -0,0 +1,17 @@ +//! [1] + +//! [1] +//! [2] + MyCompany + (C) MyCompany + BSD + Minimal plugin example + http://www.mycompany.com +//! [2] +//! [3] + + + +//! [3] + + diff --git a/doc/api/examples/exampleplugin/example.pro b/doc/api/examples/exampleplugin/example.pro new file mode 100644 index 00000000000..060aa5aa8fa --- /dev/null +++ b/doc/api/examples/exampleplugin/example.pro @@ -0,0 +1,50 @@ +#! [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 +## /plugins/ +## where 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] + diff --git a/doc/api/examples/exampleplugin/example_global.h b/doc/api/examples/exampleplugin/example_global.h new file mode 100644 index 00000000000..b51935fdaf6 --- /dev/null +++ b/doc/api/examples/exampleplugin/example_global.h @@ -0,0 +1,13 @@ +#ifndef EXAMPLE_GLOBAL_H +#define EXAMPLE_GLOBAL_H + +#include + +#if defined(EXAMPLE_LIBRARY) +# define EXAMPLESHARED_EXPORT Q_DECL_EXPORT +#else +# define EXAMPLESHARED_EXPORT Q_DECL_IMPORT +#endif + +#endif // EXAMPLE_GLOBAL_H + diff --git a/doc/api/examples/exampleplugin/exampleconstants.h b/doc/api/examples/exampleplugin/exampleconstants.h new file mode 100644 index 00000000000..1fe6b83bc1f --- /dev/null +++ b/doc/api/examples/exampleplugin/exampleconstants.h @@ -0,0 +1,14 @@ +#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 + diff --git a/doc/api/examples/exampleplugin/exampleplugin.cpp b/doc/api/examples/exampleplugin/exampleplugin.cpp new file mode 100644 index 00000000000..18501674bc5 --- /dev/null +++ b/doc/api/examples/exampleplugin/exampleplugin.cpp @@ -0,0 +1,88 @@ +#include "exampleplugin.h" +#include "exampleconstants.h" + +#include +#include +#include +#include +#include +#include + +#include +#include +#include +#include + +#include + +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] diff --git a/doc/api/examples/exampleplugin/exampleplugin.h b/doc/api/examples/exampleplugin/exampleplugin.h new file mode 100644 index 00000000000..c288abf0855 --- /dev/null +++ b/doc/api/examples/exampleplugin/exampleplugin.h @@ -0,0 +1,39 @@ +#ifndef EXAMPLE_H +#define EXAMPLE_H + +#include "example_global.h" + +#include + +//! [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 + diff --git a/doc/api/first-plugin.qdoc b/doc/api/first-plugin.qdoc new file mode 100644 index 00000000000..4a8f0c53ade --- /dev/null +++ b/doc/api/first-plugin.qdoc @@ -0,0 +1,334 @@ +/**************************************************************************** +** +** 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 + detail in \l{Menus and Menu Items}. + + \snippet exampleplugin/exampleplugin.cpp slot implementation + + This part defines the code that is called when the menu item is triggered. + It uses the Qt API to open a message box that displays informative text and + an \gui OK button. + + \snippet exampleplugin/exampleplugin.cpp export plugin + + At the end of the file, the Qt macro \c{Q_EXPORT_PLUGIN2} is used to register + the plugin with Qt's plugin loader system. This is necessary for Qt to + be able to load your plugin. + +*/ diff --git a/doc/api/getting-and-building.qdoc b/doc/api/getting-and-building.qdoc new file mode 100644 index 00000000000..35a6da76595 --- /dev/null +++ b/doc/api/getting-and-building.qdoc @@ -0,0 +1,100 @@ +/**************************************************************************** +** +** 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 + ./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 + 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{}) + you build it on Linux and Mac with + \code + cd /.. + mkdir qtcreator-build + cd qtcreator-build + /bin/qmake -r + 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 + /bin/qmake -r QT_PRIVATE_HEADERS=/include + \endcode +*/ diff --git a/doc/api/images/firstplugin-menuitem.png b/doc/api/images/firstplugin-menuitem.png new file mode 100644 index 00000000000..fa60a0d271d Binary files /dev/null and b/doc/api/images/firstplugin-menuitem.png differ diff --git a/doc/api/images/firstplugin-nameandpath.png b/doc/api/images/firstplugin-nameandpath.png new file mode 100644 index 00000000000..36777784502 Binary files /dev/null and b/doc/api/images/firstplugin-nameandpath.png differ diff --git a/doc/api/images/firstplugin-pluginsetup.png b/doc/api/images/firstplugin-pluginsetup.png new file mode 100644 index 00000000000..f9cd6ae2035 Binary files /dev/null and b/doc/api/images/firstplugin-pluginsetup.png differ diff --git a/doc/api/images/firstplugin-runsettings.png b/doc/api/images/firstplugin-runsettings.png new file mode 100644 index 00000000000..26ec79d0257 Binary files /dev/null and b/doc/api/images/firstplugin-runsettings.png differ diff --git a/doc/api/images/firstplugin-summary.png b/doc/api/images/firstplugin-summary.png new file mode 100644 index 00000000000..9b6586535da Binary files /dev/null and b/doc/api/images/firstplugin-summary.png differ diff --git a/doc/api/images/firstplugin-target.png b/doc/api/images/firstplugin-target.png new file mode 100644 index 00000000000..b8e741b4a1a Binary files /dev/null and b/doc/api/images/firstplugin-target.png differ diff --git a/doc/api/images/firstplugin-wizard.png b/doc/api/images/firstplugin-wizard.png new file mode 100644 index 00000000000..8ad598e1d21 Binary files /dev/null and b/doc/api/images/firstplugin-wizard.png differ diff --git a/doc/api/qtcreator-dev.qdoc b/doc/api/qtcreator-dev.qdoc index e0de2bd7522..37532a2601c 100644 --- a/doc/api/qtcreator-dev.qdoc +++ b/doc/api/qtcreator-dev.qdoc @@ -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. diff --git a/doc/config/qtcreator-developer.qdocconf b/doc/config/qtcreator-developer.qdocconf index ba161ea34d0..4e5637abff9 100644 --- a/doc/config/qtcreator-developer.qdocconf +++ b/doc/config/qtcreator-developer.qdocconf @@ -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) diff --git a/doc/doc.pri b/doc/doc.pri index a62b701f8b3..8b5995c1053 100644 --- a/doc/doc.pri +++ b/doc/doc.pri @@ -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 diff --git a/share/qtcreator/templates/wizards/qtcreatorplugin/myplugin.cpp b/share/qtcreator/templates/wizards/qtcreatorplugin/myplugin.cpp index 19ef252e3bf..87a426e31e5 100644 --- a/share/qtcreator/templates/wizards/qtcreatorplugin/myplugin.cpp +++ b/share/qtcreator/templates/wizards/qtcreatorplugin/myplugin.cpp @@ -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()