first-plugin.qdoc 15.1 KB
Newer Older
hjk's avatar
hjk committed
1
/**************************************************************************
2
**
3
** Copyright (c) 2014 Digia Plc and/or its subsidiary(-ies).
hjk's avatar
hjk committed
4
** Contact: http://www.qt-project.org/legal
5
**
hjk's avatar
hjk committed
6
** This file is part of Qt Creator
7 8 9 10 11 12 13 14 15 16
**
**
** 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.
**
**
hjk's avatar
hjk committed
17
**************************************************************************/
18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38

/*!
    \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
Tobias Hunger's avatar
Tobias Hunger committed
39
        \li Select \gui{File > New File or Project > Libraries > Qt Creator Plugin > Choose}.
40

Tobias Hunger's avatar
Tobias Hunger committed
41
            \image firstplugin-wizard.png "Choose the \QC Plugin Wizard"
42

Tobias Hunger's avatar
Tobias Hunger committed
43
            The \gui{Introduction and Project Location} dialog opens.
44

Tobias Hunger's avatar
Tobias Hunger committed
45
            \image firstplugin-nameandpath.png "Choose Name and Place of the Project"
46

Tobias Hunger's avatar
Tobias Hunger committed
47 48 49 50
        \li 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.
51

Tobias Hunger's avatar
Tobias Hunger committed
52
            The \gui{Kit Selection} dialog opens.
53

Tobias Hunger's avatar
Tobias Hunger committed
54
            \image firstplugin-kitselection.png "Choose the kit to build and run your project with"
55

Tobias Hunger's avatar
Tobias Hunger committed
56 57 58 59 60 61 62
        \li Select the \l{glossary-buildandrun-kit}{kit} to build and run your project with.
            For a \QC plugin this needs to be a kit with \gui{Desktop} device type,
            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.
63

Tobias Hunger's avatar
Tobias Hunger committed
64
            The \gui{Plugin Information} dialog opens.
65

Tobias Hunger's avatar
Tobias Hunger committed
66
            \image firstplugin-pluginsetup.png "Specify Your Plugin Details"
67

Tobias Hunger's avatar
Tobias Hunger committed
68 69 70
        \li 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.
71

Tobias Hunger's avatar
Tobias Hunger committed
72 73 74 75
        \li 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).
76

Tobias Hunger's avatar
Tobias Hunger committed
77 78 79 80 81 82 83 84 85 86 87
            \list
               \li \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.
               \li \gui{Copyright} is a one-line, short copyright string.
               \li \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).
               \li \gui{Description} is a relatively short, but
                   possibly multi-line description of what the plugin does.
               \li \gui{URL} is a website where the user can find more
                   information about the plugin and/or organization providing it.
88 89
           \endlist

Tobias Hunger's avatar
Tobias Hunger committed
90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113
        \li 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.

        \li 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/QtProject/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"

        \li 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.
114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140
    \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
Tobias Hunger's avatar
Tobias Hunger committed
141 142
        \li File
        \li Role
143
    \row
Tobias Hunger's avatar
Tobias Hunger committed
144 145 146
        \li \c{Example.pluginspec.in}
        \li Template plugin specification. QMake creates a \c{Example.pluginspec}
            from this file, which is read by \QC to find out about the plugin.
147
    \row
Tobias Hunger's avatar
Tobias Hunger committed
148 149 150
        \li \c{example.pro}
        \li Project file, used by QMake to generate a Makefile that then is used to
            build the plugin.
151
    \row
Tobias Hunger's avatar
Tobias Hunger committed
152 153 154
        \li \c{example_global.h}
        \li Contains macro definitions that are useful when this plugin should export
            symbols to other plugins.
155
    \row
Tobias Hunger's avatar
Tobias Hunger committed
156 157
        \li \c{exampleconstants.h}
        \li Header defining constants used by the plugin code.
158
    \row
Tobias Hunger's avatar
Tobias Hunger committed
159 160
        \li \c{exampleplugin.h/.cpp}
        \li C++ header and source files that define the plugin class that will be
161 162 163 164 165 166 167 168 169 170 171 172
           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

173 174
    The first section of the .pro file 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
175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206
    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

207 208 209 210 211 212 213 214 215 216
    This section defines the name and dependencies of your plugin.
    The \c{QTC_PLUGIN_NAME} variable defines the name of your plugin, and the name of the
    dynamic library that is created for it. The \c{QTC_LIB_DEPENDS} variable is a list of
    library names of the \QC utility libraries that your plugin depends on.
    Typical values would be \c{aggregation}, \c{extensionsystem} and \c{utils}.
    The \c{QTC_PLUGIN_DEPENDS} variable defines the \QC plugins that your plugin depends on.
    Almost all \QC plugins will depend on the \c{coreplugin}. The \c{QTC_PLUGIN_RECOMMENDS}
    variable defines the \QC plugins that your plugin optionally depends on. For more information,
    see \l{Optional Dependencies}.

217
    \snippet exampleplugin/example.pro 6
218 219 220

    The included file \c{qtcreatorplugin.pri} makes sure that you build a plugin that is suitable
    for use in \QC, by using the information you gave above.
221 222

    For more information about qmake, and writing .pro files in general,
223
    see the \l{http://qt-project.org/doc/qt-4.8/qmake-manual.html}{qmake Manual}.
224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251

    \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

252 253
    The \c{$$dependencyList} variable is automatically replaced by the dependency information
    in \c{QTC_PLUGIN_DEPENDS} and \c{QTC_PLUGIN_RECOMMENDS} from your plugin's .pro file.
254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273

    \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
274
    are QObjects. The \c{Q_PLUGIN_METADATA} macro is necessary to create a valid Qt plugin.
275

276
    \snippet exampleplugin/exampleplugin.h plugin functions
277

278
    The base class defines basic functions that are called during the life cycle
279
    of a plugin, which are here implemented for your new plugin.
280
    These functions and their roles are described in detail in
281 282 283 284 285 286 287 288 289 290 291 292 293 294 295
    \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
296 297
    is done in the plugin's \c{initialize} function, which is the first thing called
    after the plugin constructor. In that function, the plugin can be sure that the basic
298 299 300
    setup of plugin's that it depends on has been done, for example the Core plugin's
    \c{ActionManager} instance has been created.

Eike Ziller's avatar
Eike Ziller committed
301 302 303
    For more information about implementing the plugin interface, see the
    \l{ExtensionSystem::IPlugin} API documentation and \l{Plugin Life Cycle}.

304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331
    \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.

*/