Tulip 5.7.1
Large graphs analysis and drawing
Loading...
Searching...
No Matches
Plugin.h
1/*
2 *
3 * This file is part of Tulip (https://tulip.labri.fr)
4 *
5 * Authors: David Auber and the Tulip development Team
6 * from LaBRI, University of Bordeaux
7 *
8 * Tulip is free software; you can redistribute it and/or modify
9 * it under the terms of the GNU Lesser General Public License
10 * as published by the Free Software Foundation, either version 3
11 * of the License, or (at your option) any later version.
12 *
13 * Tulip is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
16 * See the GNU General Public License for more details.
17 *
18 */
19
20#ifndef TULIP_PLUGIN_H
21#define TULIP_PLUGIN_H
22
23#include <string>
24
25#include <tulip/WithParameter.h>
26#include <tulip/WithDependency.h>
27#include <tulip/PluginContext.h>
28#include <tulip/TulipRelease.h>
29
30#ifdef major
31#undef major
32#endif
33
34#ifdef minor
35#undef minor
36#endif
37
38namespace tlp {
39
40/**
41 * @ingroup Plugins
42 * @brief Splits the string and returns everything before the first dot ('.').
43 * This is used to return major version number, as version numbers are formatted as X.Y.Z,
44 * X being the major, Y the minor, and Z the patch version.
45 *
46 * @return string The part of the string before the first dot.
47 */
48TLP_SCOPE std::string getMajor(const std::string &release);
49
50/**
51 * @ingroup Plugins
52 * @brief Splits the string and return the minor version.
53 * If the string does not contain any dot, then 0 is returned.
54 * If the string contains only one dot (X.Y), then everything after the first dot is returned (Y).
55 * If the string is a full version with two dots (X.Y.Z), everything between the first and last dots
56 * is returned (Y).
57 * If there are more than two dots, everything between the first and last dots is returned.
58 */
59TLP_SCOPE std::string getMinor(const std::string &release);
60
61/**
62 * @ingroup Plugins
63 * @brief Top-level interface for plug-ins.
64 *
65 * This class holds meta-information about a plug-in (group/author/version...). It stands as a
66 * unique base-class for every plugin type.
67 * This interface is not intended to be directly sublassed. Plugin objects are mainly used
68 * internally into the plugin lister system.
69 *
70 * This class also holds extra information about the Tulip system such as the library version the
71 * plugin was built against.
72 * Plugin creation is handled by factories generated by the PLUGIN macro and the default Plugin
73 * constructor should never be called as is.
74 *
75 * @see tlp::FactoryInterface for more advanced operation such as plugin creation and retrieving
76 * dependencies.
77 * @see tlp::PluginContext and its subclasses for parameters handling.
78 *
79 * @see tlp::Algorithm for plugins operating on the tlp::Graph structure.
80 * @see tlp::TemplateAlgorithm and its subclasses for plugins operating on graph properties
81 * @see tlp::View for panel plugins
82 * @see tlp::Interactor for plugins responsible for user interactions.
83 * @see tlp::Perspective for plugins handling the main GUI
84 */
85class TLP_SCOPE Plugin : public tlp::WithParameter, public tlp::WithDependency {
86public:
87 virtual ~Plugin() {}
88
89 /**
90 @brief The icon (preferably a thumbnail) of the plugin
91 @return std::string the icon path
92 */
93 virtual std::string icon() const;
94
95 /**
96 @brief A string identifier for a plugin used for categorization purposes.
97 @returns std::string the category of the plugin.
98 */
99 virtual std::string category() const = 0;
100
101 /**
102 * @brief Returns the name of the plug-in, as registered in the Tulip plug-in system.
103 * This name must be unique, and if multiple plug-ins have the same name,
104 * only the latest encountered will be considered.
105 * @return string the name of the plug-in.
106 */
107 virtual std::string name() const = 0;
108
109 /**
110 * @brief Returns the name of the group this plug-in belongs to.
111 * Groups and sub-groups are separated by two colons.
112 * e.g. trees::planar trees
113 * @return the group name of this plug-in.
114 */
115 virtual std::string group() const = 0;
116
117 /**
118 * @brief The name of the author of this plug-in.
119 * @return the name of the author.
120 */
121 virtual std::string author() const = 0;
122
123 /**
124 * @brief The creation date of the plug-in.
125 * This date is in a free format, but most Tulip plug-ins use a DD/MM/YYYY
126 * @return the creation date.
127 */
128 virtual std::string date() const = 0;
129
130 /**
131 * @brief Information about the plug-in, from the plug-in author.
132 * This information can contains anything, and the developer is completely free to put anything
133 * here.
134 * Most plug-ins by the Tulip team use an html format to generate help from these information.
135 * @return string The information associated with this plug-in.
136 */
137 virtual std::string info() const = 0;
138
139 /**
140 * @brief The release version of the plug-in, including major and minor.
141 * The version should be X.Y, X being the major, and Y the minor.
142 * @return string The release version.
143 */
144 virtual std::string release() const = 0;
145
146 /**
147 * @brief The version of Tulip this plug-in was built with.
148 * Tulip versions are X.Y.Z, X being the major, Y the minor, and Z the patch.
149 *
150 * @return The Tulip version the plug-in was built with.
151 */
152 virtual std::string tulipRelease() const = 0;
153
154 /**
155 * @brief Only the major of the plug-in version.
156 * A version should be X.Y, X being the major.
157 *
158 * @return The major part of the plug-in version.
159 */
160 virtual std::string major() const;
161
162 /**
163 * @brief Only the minor of the plug-in version.
164 * A version should be X.Y, Y being the major.
165 *
166 * @return The minor part of the plug-in version.
167 */
168 virtual std::string minor() const;
169
170 /**
171 * @return The major Tulip version the plug-in was built with.
172 */
173 virtual std::string tulipMajor() const;
174
175 /**
176 * @return Return the minor Tulip version this plug-in was built with.
177 */
178 virtual std::string tulipMinor() const;
179
180 /**
181 * @brief Returns the ID of the glyph this factory builds.
182 * @TODO this member should be removed once there is a system in Tulip to handle glyphs.
183 *
184 * @return int the id of the glyph.
185 **/
186 virtual int id() const;
187
188 /**
189 * @return Return the a string indicating the programming language used to write the plugin (C++,
190 * Python).
191 */
192 virtual std::string programmingLanguage() const;
193
194 /**
195 * @brief Allow to declare the previous name of a plugin as deprecated
196 * in order to keep an ascending compatibility at running time
197 */
198 void declareDeprecatedName(const std::string &oldName);
199
200 /**
201 * @return the old name of the plugin if any; returns an empty string if not.
202 */
203 std::string deprecatedName() {
204 return !oldName.empty() ? oldName : std::string();
205 }
206
207protected:
208 std::string oldName;
209};
210
211/**
212 * @ingroup Plugins
213 * @def PLUGININFORMATION(NAME, AUTHOR, DATE, INFO, RELEASE, GROUP)
214 * @brief Declare meta-information for a plugin
215 * This is an helper macro that defines every function related to a plugin meta-information (Plugin
216 * name, author, etc).
217 * When creating a new plugin, this macro avoids having to define pure-virtual methods located into
218 * the Plugin interface and put them on the same line.
219 * @note PLUGINIFORMATION should be declared into the Plugin's class body into the public scope
220 *
221 * @param NAME The plugin name as it will be registered into the plugins system
222 * (tlp::Plugin::name())
223 * @param AUTHOR The author of the plugin (tlp::Plugin::author())
224 * @param DATE The creation date (tlp::Plugin::date())
225 * @param INFO The plugin's description (tlp::Plugin::info())
226 * @param RELEASE The plugin's version number (tlp::Plugin::version())
227 * @param GROUP The plugin's group (tlp::Plugin::group()). If the plugin does not belong to any
228 * group, set GROUP to "".
229 *
230 * @see tlp::Plugin
231 * @see PLUGIN
232 */
233#define PLUGININFORMATION(NAME, AUTHOR, DATE, INFO, RELEASE, GROUP) \
234 std::string name() const override { \
235 return NAME; \
236 } \
237 std::string author() const override { \
238 return AUTHOR; \
239 } \
240 std::string date() const override { \
241 return DATE; \
242 } \
243 std::string info() const override { \
244 return INFO; \
245 } \
246 std::string release() const override { \
247 return RELEASE; \
248 } \
249 std::string tulipRelease() const override { \
250 return TULIP_VERSION; \
251 } \
252 std::string group() const override { \
253 return GROUP; \
254 }
255
256///@cond DOXYGEN_HIDDEN
257/**
258 * @ingroup Plugins
259 * @brief The base class for plugin factories.
260 *
261 * A plugin factory handles the creation process of a tlp::Plugin subclass. This class should never
262 *be used directly. See the PLUGIN macro for additional information.
263 * @see PLUGIN
264 **/
265class TLP_SCOPE PluginFactory {
266public:
267 virtual tlp::Plugin *createPluginObject(tlp::PluginContext *context) = 0;
268 static void registerFactory(PluginFactory *);
269};
270///@endcond
271
272/**
273 * @ingroup Plugins
274 * @def PLUGIN(C)
275 * @brief Register a plugin into the plugin system.
276 * This macro is mandatory in order to register a plugin into Tulip. This will generate a Factory
277that will handle the plugin's creation.
278 * @param C The classname of the plugin.
279 * @note This macro should be called outside of the class body @endnote
280 *
281@code{.cpp}
282// This sample shows a basic skeleton for a plugin class declaration:
283class MyPlugin: public tlp::PluginBase { // tlp::PluginBase is replaced by the actual Plugin
284interface (tlp::Algorithm, tlp::View, etc)
285 public:
286 PLUGININFORMATION("My plugin", "Me", "28/09/2012", "My first plugin example", "1.0", "")
287 // Class declaration and extra methods
288};
289
290PLUGIN(MyPlugin) // Register MyPlugin into Tulip
291@endcode
292 *
293 * @see tlp::Plugin
294 * @see PLUGININFORMATION
295 */
296#define PLUGIN(C) \
297 class C##Factory : public tlp::PluginFactory { \
298 public: \
299 C##Factory() { \
300 registerFactory(this); \
301 } \
302 ~C##Factory() {} \
303 tlp::Plugin *createPluginObject(tlp::PluginContext *context) { \
304 C *tmp = new C(context); \
305 return tmp; \
306 } \
307 }; \
308 \
309 extern "C" { \
310 C##Factory C##FactoryInitializer; \
311 }
312} // namespace tlp
313
314#endif // TULIP_PLUGIN_H
Contains runtime parameters for a plugin.
Definition: PluginContext.h:42
Top-level interface for plug-ins.
Definition: Plugin.h:85
virtual std::string major() const
Only the major of the plug-in version. A version should be X.Y, X being the major.
virtual std::string name() const =0
Returns the name of the plug-in, as registered in the Tulip plug-in system. This name must be unique,...
virtual std::string tulipRelease() const =0
The version of Tulip this plug-in was built with. Tulip versions are X.Y.Z, X being the major,...
virtual std::string tulipMajor() const
virtual int id() const
Returns the ID of the glyph this factory builds. @TODO this member should be removed once there is a ...
virtual std::string group() const =0
Returns the name of the group this plug-in belongs to. Groups and sub-groups are separated by two col...
virtual std::string release() const =0
The release version of the plug-in, including major and minor. The version should be X....
virtual std::string info() const =0
Information about the plug-in, from the plug-in author. This information can contains anything,...
virtual std::string icon() const
The icon (preferably a thumbnail) of the plugin.
void declareDeprecatedName(const std::string &oldName)
Allow to declare the previous name of a plugin as deprecated in order to keep an ascending compatibil...
virtual std::string date() const =0
The creation date of the plug-in. This date is in a free format, but most Tulip plug-ins use a DD/MM/...
virtual std::string minor() const
Only the minor of the plug-in version. A version should be X.Y, Y being the major.
virtual std::string programmingLanguage() const
virtual std::string tulipMinor() const
virtual std::string category() const =0
A string identifier for a plugin used for categorization purposes.
std::string deprecatedName()
Definition: Plugin.h:203
virtual std::string author() const =0
The name of the author of this plug-in.
std::string getMajor(const std::string &release)
Splits the string and returns everything before the first dot ('.'). This is used to return major ver...
std::string getMinor(const std::string &release)
Splits the string and return the minor version. If the string does not contain any dot,...