1 /****************************************************************************
2 **
3 ** Copyright (C) 2016 The Qt Company Ltd.
4 ** Contact: https://www.qt.io/licensing/
5 **
6 ** This file is part of Qt Creator.
7 **
8 ** Commercial License Usage
9 ** Licensees holding valid commercial Qt licenses may use this file in
10 ** accordance with the commercial license agreement provided with the
11 ** Software or, alternatively, in accordance with the terms contained in
12 ** a written agreement between you and The Qt Company. For licensing terms
13 ** and conditions see https://www.qt.io/terms-conditions. For further
14 ** information use the contact form at https://www.qt.io/contact-us.
15 **
16 ** GNU General Public License Usage
17 ** Alternatively, this file may be used under the terms of the GNU
18 ** General Public License version 3 as published by the Free Software
19 ** Foundation with exceptions as appearing in the file LICENSE.GPL3-EXCEPT
20 ** included in the packaging of this file. Please review the following
21 ** information to ensure the GNU General Public License requirements will
22 ** be met: https://www.gnu.org/licenses/gpl-3.0.html.
23 **
24 ****************************************************************************/
25
26 #include "iplugin.h"
27 #include "iplugin_p.h"
28 #include "pluginmanager.h"
29 #include "pluginspec.h"
30
31 /*!
32 \class ExtensionSystem::IPlugin
33 \inheaderfile extensionsystem/iplugin.h
34 \inmodule QtCreator
35 \ingroup mainclasses
36
37 \brief The IPlugin class is an abstract base class that must be implemented
38 once for each plugin.
39
40 A plugin needs to provide meta data in addition to the actual plugin
41 library, so the plugin manager can find the plugin, resolve its
42 dependencies, and load it. For more information, see \l{Plugin Meta Data}.
43
44 Plugins must provide one implementation of the IPlugin class, located
45 in a library that matches the \c name attribute given in their
46 meta data. The IPlugin implementation must be exported and
47 made known to Qt's plugin system, using the \c Q_PLUGIN_METADATA macro with
48 an IID set to \c "org.qt-project.Qt.QtCreatorPlugin".
49
50 For more information, see \l{Plugin Life Cycle}.
51 */
52
53 /*!
54 \enum IPlugin::ShutdownFlag
55
56 This enum type holds whether the plugin is shut down synchronously or
57 asynchronously.
58
59 \value SynchronousShutdown
60 The plugin is shut down synchronously.
61 \value AsynchronousShutdown
62 The plugin needs to perform asynchronous
63 actions before it shuts down.
64 */
65
66 /*!
67 \fn bool ExtensionSystem::IPlugin::initialize(const QStringList &arguments, QString *errorString)
68 Called after the plugin has been loaded and the IPlugin instance
69 has been created.
70
71 The initialize functions of plugins that depend on this plugin are called
72 after the initialize function of this plugin has been called with
73 \a arguments. Plugins should initialize their internal state in this
74 function.
75
76 Returns whether initialization succeeds. If it does not, \a errorString
77 should be set to a user-readable message describing the reason.
78
79 \sa extensionsInitialized()
80 \sa delayedInitialize()
81 */
82
83 /*!
84 \fn void ExtensionSystem::IPlugin::extensionsInitialized()
85 Called after the initialize() function has been called,
86 and after both the initialize() and \c extensionsInitialized()
87 functions of plugins that depend on this plugin have been called.
88
89 In this function, the plugin can assume that plugins that depend on
90 this plugin are fully \e {up and running}. It is a good place to
91 look in the global object pool for objects that have been provided
92 by weakly dependent plugins.
93
94 \sa initialize()
95 \sa delayedInitialize()
96 */
97
98 /*!
99 \fn bool ExtensionSystem::IPlugin::delayedInitialize()
100 Called after all plugins' extensionsInitialized() function has been called,
101 and after the \c delayedInitialize() function of plugins that depend on this
102 plugin have been called.
103
104 The plugins' \c delayedInitialize() functions are called after the
105 application is already running, with a few milliseconds delay to
106 application startup, and between individual \c delayedInitialize()
107 function calls. To avoid unnecessary delays, a plugin should return
108 \c true from the function if it actually implements it, to indicate
109 that the next plugins' \c delayedInitialize() call should be delayed
110 a few milliseconds to give input and paint events a chance to be processed.
111
112 This function can be used if a plugin needs to do non-trivial setup that doesn't
113 necessarily need to be done directly at startup, but still should be done within a
114 short time afterwards. This can decrease the perceived plugin or application startup
115 time a lot, with very little effort.
116
117 \sa initialize()
118 \sa extensionsInitialized()
119 */
120
121 /*!
122 \fn ExtensionSystem::IPlugin::ShutdownFlag ExtensionSystem::IPlugin::aboutToShutdown()
123 Called during a shutdown sequence in the same order as initialization
124 before the plugins get deleted in reverse order.
125
126 This function should be used to disconnect from other plugins,
127 hide all UI, and optimize shutdown in general.
128 If a plugin needs to delay the real shutdown for a while, for example if
129 it needs to wait for external processes to finish for a clean shutdown,
130 the plugin can return IPlugin::AsynchronousShutdown from this function. This
131 will keep the main event loop running after the aboutToShutdown() sequence
132 has finished, until all plugins requesting asynchronous shutdown have sent
133 the asynchronousShutdownFinished() signal.
134
135 The default implementation of this function does nothing and returns
136 IPlugin::SynchronousShutdown.
137
138 Returns IPlugin::AsynchronousShutdown if the plugin needs to perform
139 asynchronous actions before shutdown.
140
141 \sa asynchronousShutdownFinished()
142 */
143
144 /*!
145 \fn QObject *ExtensionSystem::IPlugin::remoteCommand(const QStringList &options,
146 const QString &workingDirectory,
147 const QStringList &arguments)
148
149 When \QC is executed with the \c -client argument while another \QC instance
150 is running, this function of the plugin is called in the running instance.
151
152 The \a workingDirectory argument specifies the working directory of the
153 calling process. For example, if you're in a directory, and you execute
154 \c { qtcreator -client file.cpp}, the working directory of the calling
155 process is passed to the running instance and \c {file.cpp} is transformed
156 into an absolute path starting from this directory.
157
158 Plugin-specific arguments are passed in \a options, while the rest of the
159 arguments are passed in \a arguments.
160
161 Returns a QObject that blocks the command until it is destroyed, if \c -block
162 is used.
163 */
164
165 /*!
166 \fn void ExtensionSystem::IPlugin::asynchronousShutdownFinished()
167 Sent by the plugin implementation after an asynchronous shutdown
168 is ready to proceed with the shutdown sequence.
169
170 \sa aboutToShutdown()
171 */
172
173 using namespace ExtensionSystem;
174
175 /*!
176 \internal
177 */
IPlugin()178 IPlugin::IPlugin()
179 : d(new Internal::IPluginPrivate())
180 {
181 }
182
183 /*!
184 \internal
185 */
~IPlugin()186 IPlugin::~IPlugin()
187 {
188 delete d;
189 d = nullptr;
190 }
191
192 /*!
193 Returns objects that are meant to be passed on to \l QTest::qExec().
194
195 This function will be called if the user starts \QC with
196 \c {-test PluginName} or \c {-test all}.
197
198 The ownership of returned objects is transferred to caller.
199 */
createTestObjects() const200 QVector<QObject *> IPlugin::createTestObjects() const
201 {
202 return {};
203 }
204
205 /*!
206 Returns the PluginSpec corresponding to this plugin.
207 This is not available in the constructor.
208 */
pluginSpec() const209 PluginSpec *IPlugin::pluginSpec() const
210 {
211 return d->pluginSpec;
212 }
213