This section describes how to create a Qt Creator plugin by using the plugin template provided by Qt Creator, and get the first impression of what a plugin consists of and what its general structure is.
Qt Creator comes with a wizard for Qt Creator plugins, that creates a runable, minimal plugin for you. We strongly suggest that you use two different Qt Creator 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 Qt Creator build and use one for actually developing, and the other for testing your plugin with.
[Missing image firstplugin-wizard.png]
The Introduction and Project Location dialog opens.
[Missing image firstplugin-nameandpath.png]
The Kit Selection dialog opens.
[Missing image firstplugin-kitselection.png]
The Plugin Information dialog opens.
[Missing image firstplugin-pluginsetup.png]
The Project Management dialog opens.
[Missing image firstplugin-summary.png]
If you passed the correct Qt Creator 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, Qt Creator will ask you for the executable to run and you are presented the following dialog:
[Missing image firstplugin-runsettings.png]
Select the path to the Qt Creator executable from the build that you specified in the Qt Creator build setting in the project wizard and click OK. Qt Creator starts up, and you can verify that your plugin successfully loaded by looking for a menu entry Tools > Example and by looking for the plugin in the About Plugins dialog.
[Missing image firstplugin-menuitem.png]
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:
File | Role |
---|---|
Example.pluginspec.in | Template plugin specification. QMake creates a Example.pluginspec from this file, which is read by Qt Creator to find out about the plugin. |
example.pro | Project file, used by QMake to generate a Makefile that then is used to build the plugin. |
example_global.h | Contains macro definitions that are useful when this plugin should export symbols to other plugins. |
exampleconstants.h | Header defining constants used by the plugin code. |
exampleplugin.h/.cpp | C++ header and source files that define the plugin class that will be instanciated and run by Qt Creator's plugin manager. |
The qmake project file example.pro defines how your plugin should be compiled. Qt Creator plugins need to have a specific setup there, in addition to telling qmake which files need to be compiled (or handled by moc or uic). Let us have a look at what the project wizard generated for you in detail.
The first section of the .pro file defines the very basic properties of your project, the name (TARGET), and that a library should be generated, since plugins are actually libraries that are dynamically loaded (TEMPLATE = lib). The section also lets the compiler pass an EXAMPLE_LIBRARY define to the compiled code, which is used in the example_global.h header, but is not really of interest for now. You should not need to change that section of the .pro file.
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.
To compile and deploy your plugin, the project needs access to the Qt Creator sources and build. This section contains the logic that looks for the information about the location of the sources and build in the QTC_SOURCE and 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 QTC_SOURCE and 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.
Qt Creator plugins can either be installed into the Qt Creator installation's plugin directory (requires write access there), or to a user specific plugin directory. The 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).
The 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.
This section includes the necessary parts from the Qt Creator sources and makes your plugin find the Qt Creator libraries and plugins. The included file qtcreatorplugin.pri makes sure that you build a plugin that is suitable for use in Qt Creator. The file 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 qmake Manual.
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 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 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 \\ to get a backslash and \" to get a quote in the generated plugin specification).
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.
After the main tag you'll find the information about the plugin that you gave in the project wizard.
The last section tells the plugin manager about the dependencies of this plugin. Most Qt Creator plugins will at least depend on the Core plugin.
The files exampleplugin.h and 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.
The header file exampleplugin.h defines the interface of the plugin class.
The plugin is defined in a Example::Internal namespace, which conforms to the coding rules for namespacing in Qt Creator sources.
All Qt Creator plugins must be derived from ExtensionSystem::IPlugin and are QObjects.
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 The Plugin Life Cycle.
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.
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 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 ActionManager instance has been created.
For more information about implementing the plugin interface, see the ExtensionSystem::IPlugin API documentation and Plugin Life Cycle.
This part of the code creates a new QAction, registers it as a new 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 Menus and Menu Items.
Here a new menu item is created, the created command added to it, and the menu added to the Tools menu in the menu bar. Again, this is covered in more detail in Menus and Menu Items.
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 OK button.
At the end of the file, the Qt macro 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.