Tulip  4.10.0
Better Visualization Through Research
Plugin.h
1 /*
2  *
3  * This file is part of Tulip (www.tulip-software.org)
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 befor 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 is returned (Y).
56  * If there are more than two dots, everything between the first and last dots is returned.
57  */
58 TLP_SCOPE std::string getMinor(const std::string &release);
59 
60 /**
61  * @ingroup Plugins
62  * @brief Top-level interface for plug-ins.
63  *
64  * This class holds meta-information about a plug-in (group/author/version...). It stands as a unique base-class for every plugin type.
65  * This interface is not intended to be directly sublassed. Plugin objects are mainly used internally into the plugin lister system.
66  *
67  * This classe also holds extra information about the Tulip system such as the library version the plugin was built against.
68  * Plugin creation is handled by factories generated by the PLUGIN macro and the default Plugin constructor should never be called as is.
69  *
70  * @see tlp::FactoryInterface for more advanced operation such as plugin creation and retrieving dependencies.
71  * @see tlp::PluginContext and its subclasses for parameters handling.
72  *
73  * @see tlp::Algorithm for plugins operating on the tlp::Graph structure.
74  * @see tlp::TemplateAlgorithm and its subclasses for plugins operating on graph properties
75  * @see tlp::View for panel plugins
76  * @see tlp::Interactor for plugins responisble for user interactions.
77  * @see tlp::Perspective for plugins handling the main GUI
78  */
79 class TLP_SCOPE Plugin : public tlp::WithParameter, public tlp::WithDependency {
80 public:
81  virtual ~Plugin() {}
82 
83  /**
84  @brief The icon (preferably a thumbnail) of the plugin
85  @return std::string the icon path
86  */
87  virtual std::string icon() const;
88 
89  /**
90  @brief A string identifier for a plugin used for categorization purposes.
91  @returns std::string the category of the plugin.
92  */
93  virtual std::string category() const=0;
94 
95  /**
96  * @brief Returns the name of the plug-in, as registered in the Tulip plug-in system.
97  * This name must be unique, and if multiple plug-ins have the same name,
98  * only the latest encountered will be considered.
99  * @return string the name of the plug-in.
100  */
101  virtual std::string name() const=0;
102 
103  /**
104  * @brief Returns the name of the group this plug-in belongs to.
105  * Groups and sub-groups are separated by two colons.
106  * e.g. trees::planar trees
107  * @return the group name of this plug-in.
108  */
109  virtual std::string group() const=0;
110 
111  /**
112  * @brief The name of the author of this plug-in.
113  * @return the name of the author.
114  */
115  virtual std::string author() const=0;
116 
117  /**
118  * @brief The creation date of the plug-in.
119  * This date is in a free format, but most Tulip plug-ins use a DD/MM/YYYY
120  * @return the creation date.
121  */
122  virtual std::string date() const=0;
123 
124  /**
125  * @brief Information about the plug-in, from the plug-in author.
126  * This information can contains anything, and the developer is completely free to put anything here.
127  * Most plug-ins by the Tulip team use an html format to generate help from these information.
128  * @return string The information associated with this plug-in.
129  */
130  virtual std::string info() const=0;
131 
132  /**
133  * @brief The release version of the plug-in, including major and minor.
134  * The version should be X.Y, X being the major, and Y the minor.
135  * @return string The release version.
136  */
137  virtual std::string release() const=0;
138 
139  /**
140  * @brief The version of Tulip this plug-in was built with.
141  * Tulip versions are X.Y.Z, X being the major, Y the minor, and Z the patch.
142  *
143  * @return The Tulip version the plug-in was built with.
144  */
145  virtual std::string tulipRelease() const=0;
146 
147  /**
148  * @brief Only the major of the plug-in version.
149  * A version should be X.Y, X being the major.
150  *
151  * @return The major part of the plug-in version.
152  */
153  virtual std::string major() const;
154 
155  /**
156  * @brief Only the minor of the plug-in version.
157  * A version should be X.Y, Y being the major.
158  *
159  * @return The minor part of the plug-in version.
160  */
161  virtual std::string minor() const;
162 
163  /**
164  * @return The major Tulip version the plug-in was built with.
165  */
166  virtual std::string tulipMajor() const;
167 
168  /**
169  * @return Return the minor Tulip version this plug-in was built with.
170  */
171  virtual std::string tulipMinor() const;
172 
173  /**
174  * @brief Returns the ID of the glyph this factory builds.
175  * @TODO this member should be removed once there is a system in Tulip to handle glyphs.
176  *
177  * @return int the id of the glyph.
178  **/
179  virtual int id() const;
180 
181  virtual std::string programmingLanguage() const;
182 
183 };
184 
185 /**
186  * @ingroup Plugins
187  * @def PLUGININFORMATION(NAME, AUTHOR, DATE, INFO, RELEASE, GROUP)
188  * @brief Declare meta-information for a plugin
189  * This is an helper macro that defines every function related to a plugin meta-information (Plugin name, author, etc).
190  * When creating a new plugin, this macro avoids having to define pure-virtual methods located into the Plugin interface and put them on the same line.
191  * @note PLUGINIFORMATION should be declared into the Plugin's class body into the public scope
192  *
193  * @param NAME The plugin name as it will be registered into the plugins system (tlp::Plugin::name())
194  * @param AUTHOR The author of the plugin (tlp::Plugin::author())
195  * @param DATE The creation date (tlp::Plugin::date())
196  * @param INFO The plugin's description (tlp::Plugin::info())
197  * @param RELEASE The plugin's version number (tlp::Plugin::version())
198  * @param GROUP The plugin's group (tlp::Plugin::group()). If the plugin does not belong to any group, set GROUP to "".
199  *
200  * @see tlp::Plugin
201  * @see PLUGIN
202  */
203 #define PLUGININFORMATION(NAME, AUTHOR, DATE, INFO, RELEASE, GROUP)\
204 std::string name() const { return NAME; } \
205 std::string author() const { return AUTHOR; }\
206 std::string date() const { return DATE; } \
207 std::string info() const { return INFO; } \
208 std::string release() const { return RELEASE; }\
209 std::string tulipRelease() const { return TULIP_VERSION; }\
210 std::string group() const { return GROUP; }
211 
212 #define PLUGININFORMATIONS(NAME, AUTHOR, DATE, INFO, RELEASE, GROUP)\
213 PLUGININFORMATION(NAME, AUTHOR, DATE, INFO, RELEASE, GROUP)
214 }
215 
216 //This include is here because the PluginLister needs to know the Plugin type, and the PLUGIN macro needs to know the PluginLister.
217 #include <tulip/PluginLister.h>
218 namespace tlp {
219 /**
220  * @ingroup Plugins
221  * @def PLUGIN(C)
222  * @brief Register a plugin into the plugin system.
223  * This macro is mandatory in order to register a plugin into Tulip. This will generate a Factory that will handle the plugin's creation.
224  * @param C The classname of the plugin.
225  * @note This macro should be called outside of the class body @endnote
226  *
227 @code{.cpp}
228 // This sample shows a basic skeleton for a plugin class declaration:
229 class MyPlugin: public tlp::PluginBase { // tlp::PluginBase is replaced by the actual Plugin interface (tlp::Algorithm, tlp::View, etc)
230  public:
231  PLUGININFORMATION("My plugin", "Me", "28/09/2012", "My first plugin example", "1.0", "")
232  // Class declaration and extra methods
233 };
234 
235 PLUGIN(MyPlugin) // Register MyPlugin into Tulip
236 @endcode
237  *
238  * @see tlp::Plugin
239  * @see PLUGININFORMATION
240  */
241 #define PLUGIN(C) \
242 class C##Factory : public tlp::FactoryInterface { \
243 public: \
244  C##Factory() { \
245  tlp::PluginLister::registerPlugin(this); \
246 } \
247 ~C##Factory(){} \
248 tlp::Plugin* createPluginObject(tlp::PluginContext* context) { \
249 C* tmp = new C(context); \
250 return tmp; \
251 } \
252 }; \
253 \
254 extern "C" { \
255 C##Factory C##FactoryInitializer; \
256 }
257 
258 
259 }
260 
261 #endif //TULIP_PLUGIN_H
Describes the dependencies of a plug-in on other plug-ins, identified by their name and their version...
std::string getMinor(const std::string &release)
Splits the string and return the minor version. If the string does not contain any dot...
Top-level interface for plug-ins.
Definition: Plugin.h:79
std::string getMajor(const std::string &release)
Splits the string and returns everything befor the first dot (&#39;.&#39;). This is used to return major vers...
This class describes parameters on a plug-in.