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