Tulip  5.7.4
Large graphs analysis and drawing
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 
38 namespace 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  */
48 TLP_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  */
59 TLP_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 subclassed. 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::WithParameters for the declaration and retrieval of parameters
76  * @see tlp::WithDependencies for the declaration and retrieval of dependencies
77  * @see tlp::PluginFactory for plugin creation and registration
78  * @see tlp::PluginContext and its subclasses for passing runtime parameters.
79  *
80  * @see tlp::Algorithm for plugins operating on the tlp::Graph structure.
81  * @see tlp::PropertyAlgorithm and its subclasses for plugins operating on graph properties
82  * @see tlp::View for panel plugins
83  * @see tlp::Interactor for plugins responsible for user interactions.
84  * @see tlp::Perspective for plugins handling the main GUI
85  */
86 class TLP_SCOPE Plugin : public tlp::WithParameter, public tlp::WithDependency {
87 public:
88  virtual ~Plugin() {}
89 
90  /**
91  @brief The icon (preferably a thumbnail) of the plugin
92  @return std::string the icon path
93  */
94  virtual std::string icon() const;
95 
96  /**
97  @brief A string identifier for a plugin used for categorization purposes.
98  @returns std::string the category of the plugin.
99  */
100  virtual std::string category() const = 0;
101 
102  /**
103  * @brief Returns the name of the plug-in, as registered in the Tulip plug-in system.
104  * This name must be unique, and if multiple plug-ins have the same name,
105  * only the latest encountered will be considered.
106  * @return string the name of the plug-in.
107  */
108  virtual std::string name() const = 0;
109 
110  /**
111  * @brief Returns the name of the group this plug-in belongs to.
112  * Groups and sub-groups are separated by two colons.
113  * e.g. trees::planar trees
114  * @return the group name of this plug-in.
115  */
116  virtual std::string group() const = 0;
117 
118  /**
119  * @brief The name of the author of this plug-in.
120  * @return the name of the author.
121  */
122  virtual std::string author() const = 0;
123 
124  /**
125  * @brief The creation date of the plug-in.
126  * This date is in a free format, but most Tulip plug-ins use a DD/MM/YYYY
127  * @return the creation date.
128  */
129  virtual std::string date() const = 0;
130 
131  /**
132  * @brief Information about the plug-in, from the plug-in author.
133  * This information can contains anything, and the developer is completely free to put anything
134  * here.
135  * Most plug-ins by the Tulip team use an html format to generate help from these information.
136  * @return string The information associated with this plug-in.
137  */
138  virtual std::string info() const = 0;
139 
140  /**
141  * @brief The release version of the plug-in, including major and minor.
142  * The version should be X.Y, X being the major, and Y the minor.
143  * @return string The release version.
144  */
145  virtual std::string release() const = 0;
146 
147  /**
148  * @brief The version of Tulip this plug-in was built with.
149  * Tulip versions are X.Y.Z, X being the major, Y the minor, and Z the patch.
150  *
151  * @return The Tulip version the plug-in was built with.
152  */
153  virtual std::string tulipRelease() const = 0;
154 
155  /**
156  * @brief Only the major of the plug-in version.
157  * A version should be X.Y, X being the major.
158  *
159  * @return The major part of the plug-in version.
160  */
161  virtual std::string major() const;
162 
163  /**
164  * @brief Only the minor of the plug-in version.
165  * A version should be X.Y, Y being the major.
166  *
167  * @return The minor part of the plug-in version.
168  */
169  virtual std::string minor() const;
170 
171  /**
172  * @return The major Tulip version the plug-in was built with.
173  */
174  virtual std::string tulipMajor() const;
175 
176  /**
177  * @return Return the minor Tulip version this plug-in was built with.
178  */
179  virtual std::string tulipMinor() const;
180 
181  /**
182  * @brief Returns the ID of the glyph this factory builds.
183  * @TODO this member should be removed once there is a system in Tulip to handle glyphs.
184  *
185  * @return int the id of the glyph.
186  **/
187  virtual int id() const;
188 
189  /**
190  * @return Return the a string indicating the programming language used to write the plugin (C++,
191  * Python).
192  */
193  virtual std::string programmingLanguage() const;
194 
195  /**
196  * @brief Allow to declare the previous name of a plugin as deprecated
197  * in order to keep an ascending compatibility at running time
198  */
199  void declareDeprecatedName(const std::string &oldName);
200 
201  /**
202  * @return the old name of the plugin if any; returns an empty string if not.
203  */
204  std::string deprecatedName() {
205  return !oldName.empty() ? oldName : std::string();
206  }
207 
208 protected:
209  std::string oldName;
210 };
211 
212 /**
213  * @ingroup Plugins
214  * @def PLUGININFORMATION(NAME, AUTHOR, DATE, INFO, RELEASE, GROUP)
215  * @brief Declare meta-information for a plugin
216  * This is an helper macro that defines every function related to a plugin meta-information (Plugin
217  * name, author, etc).
218  * When creating a new plugin, this macro avoids having to define pure-virtual methods located into
219  * the Plugin interface and put them on the same line.
220  * @note PLUGINIFORMATION should be declared into the Plugin's class body into the public scope
221  *
222  * @param NAME The plugin name as it will be registered into the plugins system
223  * (tlp::Plugin::name())
224  * @param AUTHOR The author of the plugin (tlp::Plugin::author())
225  * @param DATE The creation date (tlp::Plugin::date())
226  * @param INFO The plugin's description (tlp::Plugin::info())
227  * @param RELEASE The plugin's version number (tlp::Plugin::version())
228  * @param GROUP The plugin's group (tlp::Plugin::group()). If the plugin does not belong to any
229  * group, set GROUP to "".
230  *
231  * @see tlp::Plugin
232  * @see PLUGIN
233  */
234 #define PLUGININFORMATION(NAME, AUTHOR, DATE, INFO, RELEASE, GROUP) \
235  std::string name() const override { \
236  return NAME; \
237  } \
238  std::string author() const override { \
239  return AUTHOR; \
240  } \
241  std::string date() const override { \
242  return DATE; \
243  } \
244  std::string info() const override { \
245  return INFO; \
246  } \
247  std::string release() const override { \
248  return RELEASE; \
249  } \
250  std::string tulipRelease() const override { \
251  return TULIP_VERSION; \
252  } \
253  std::string group() const override { \
254  return GROUP; \
255  }
256 
257 ///@cond DOXYGEN_HIDDEN
258 /**
259  * @ingroup Plugins
260  * @brief The base class for plugin factories.
261  *
262  * A plugin factory handles the creation process of a tlp::Plugin subclass. This class should never
263  *be used directly. See the PLUGIN macro for additional information.
264  * @see PLUGIN
265  **/
266 class TLP_SCOPE PluginFactory {
267 public:
268  virtual tlp::Plugin *createPluginObject(tlp::PluginContext *context) = 0;
269  static void registerFactory(PluginFactory *);
270 };
271 ///@endcond
272 
273 /**
274  * @ingroup Plugins
275  * @def PLUGIN(C)
276  * @brief Register a plugin into the plugin system.
277  * This macro is mandatory in order to register a plugin into Tulip. This will generate a Factory
278 that will handle the plugin's creation.
279  * @param C The classname of the plugin.
280  * @note This macro should be called outside of the class body @endnote
281  *
282 @code{.cpp}
283 // This sample shows a basic skeleton for a plugin class declaration:
284 class MyPlugin: public tlp::PluginBase { // tlp::PluginBase is replaced by the actual Plugin
285 interface (tlp::Algorithm, tlp::View, etc)
286  public:
287  PLUGININFORMATION("My plugin", "Me", "28/09/2012", "My first plugin example", "1.0", "")
288  // Class declaration and extra methods
289 };
290 
291 PLUGIN(MyPlugin) // Register MyPlugin into Tulip
292 @endcode
293  *
294  * @see tlp::Plugin
295  * @see PLUGININFORMATION
296  */
297 #define PLUGIN(C) \
298  class C##Factory : public tlp::PluginFactory { \
299  public: \
300  C##Factory() { \
301  registerFactory(this); \
302  } \
303  ~C##Factory() {} \
304  tlp::Plugin *createPluginObject(tlp::PluginContext *context) { \
305  C *tmp = new C(context); \
306  return tmp; \
307  } \
308  }; \
309  \
310  extern "C" { \
311  C##Factory C##FactoryInitializer; \
312  }
313 } // namespace tlp
314 
315 #endif // TULIP_PLUGIN_H
Contains runtime parameters for a plugin.
Definition: PluginContext.h:42
Top-level interface for plug-ins.
Definition: Plugin.h:86
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:204
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,...