Tulip
4.6.0
Better Visualization Through Research
|
00001 /* 00002 * 00003 * This file is part of Tulip (www.tulip-software.org) 00004 * 00005 * Authors: David Auber and the Tulip development Team 00006 * from LaBRI, University of Bordeaux 00007 * 00008 * Tulip is free software; you can redistribute it and/or modify 00009 * it under the terms of the GNU Lesser General Public License 00010 * as published by the Free Software Foundation, either version 3 00011 * of the License, or (at your option) any later version. 00012 * 00013 * Tulip is distributed in the hope that it will be useful, 00014 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 00016 * See the GNU General Public License for more details. 00017 * 00018 */ 00019 00020 #ifndef TULIP_PLUGIN_H 00021 #define TULIP_PLUGIN_H 00022 00023 #include <string> 00024 00025 #include <tulip/WithParameter.h> 00026 #include <tulip/WithDependency.h> 00027 #include <tulip/PluginContext.h> 00028 #include <tulip/TulipRelease.h> 00029 00030 #ifdef major 00031 #undef major 00032 #endif 00033 00034 #ifdef minor 00035 #undef minor 00036 #endif 00037 00038 namespace tlp { 00039 00040 /** 00041 * @ingroup Plugins 00042 * @brief Splits the string and returns everything befor the first dot ('.'). 00043 * This is used to return major version number, as version numbers are formatted as X.Y.Z, 00044 * X being the major, Y the minor, and Z the patch version. 00045 * 00046 * @return string The part of the string before the first dot. 00047 */ 00048 TLP_SCOPE std::string getMajor(const std::string &release); 00049 00050 /** 00051 * @ingroup Plugins 00052 * @brief Splits the string and return the minor version. 00053 * If the string does not contain any dot, then 0 is returned. 00054 * If the string contains only one dot (X.Y), then everything after the first dot is returned (Y). 00055 * If the string is a full version with two dots (X.Y.Z), everything between the first and last dots is returned (Y). 00056 * If there are more than two dots, everything between the first and last dots is returned. 00057 */ 00058 TLP_SCOPE std::string getMinor(const std::string &release); 00059 00060 /** 00061 * @ingroup Plugins 00062 * @brief Top-level interface for plug-ins. 00063 * 00064 * This class holds meta-information about a plug-in (group/author/version...). It stands as a unique base-class for every plugin type. 00065 * This interface is not intended to be directly sublassed. Plugin objects are mainly used internally into the plugin lister system. 00066 * 00067 * This classe also holds extra information about the Tulip system such as the library version the plugin was built against. 00068 * Plugin creation is handled by factories generated by the PLUGIN macro and the default Plugin constructor should never be called as is. 00069 * 00070 * @see tlp::FactoryInterface for more advanced operation such as plugin creation and retrieving dependencies. 00071 * @see tlp::PluginContext and its subclasses for parameters handling. 00072 * 00073 * @see tlp::Algorithm for plugins operating on the tlp::Graph structure. 00074 * @see tlp::TemplateAlgorithm and its subclasses for plugins operating on graph properties 00075 * @see tlp::View for panel plugins 00076 * @see tlp::Interactor for plugins responisble for user interactions. 00077 * @see tlp::Perspective for plugins handling the main GUI 00078 */ 00079 class TLP_SCOPE Plugin : public tlp::WithParameter, public tlp::WithDependency { 00080 public: 00081 virtual ~Plugin() {} 00082 00083 /** 00084 @brief The icon (preferably a thumbnail) of the plugin 00085 @return std::string the icon path 00086 */ 00087 virtual std::string icon() const; 00088 00089 /** 00090 @brief A string identifier for a plugin used for categorization purposes. 00091 @returns std::string the category of the plugin. 00092 */ 00093 virtual std::string category() const=0; 00094 00095 /** 00096 * @brief Returns the name of the plug-in, as registered in the Tulip plug-in system. 00097 * This name must be unique, and if multiple plug-ins have the same name, 00098 * only the latest encountered will be considered. 00099 * @return string the name of the plug-in. 00100 */ 00101 virtual std::string name() const=0; 00102 00103 /** 00104 * @brief Returns the name of the group this plug-in belongs to. 00105 * Groups and sub-groups are separated by two colons. 00106 * e.g. trees::planar trees 00107 * @return the group name of this plug-in. 00108 */ 00109 virtual std::string group() const=0; 00110 00111 /** 00112 * @brief The name of the author of this plug-in. 00113 * @return the name of the author. 00114 */ 00115 virtual std::string author() const=0; 00116 00117 /** 00118 * @brief The creation date of the plug-in. 00119 * This date is in a free format, but most Tulip plug-ins use a DD/MM/YYYY 00120 * @return the creation date. 00121 */ 00122 virtual std::string date() const=0; 00123 00124 /** 00125 * @brief Information about the plug-in, from the plug-in author. 00126 * This information can contains anything, and the developer is completely free to put anything here. 00127 * Most plug-ins by the Tulip team use an html format to generate help from these information. 00128 * @return string The information associated with this plug-in. 00129 */ 00130 virtual std::string info() const=0; 00131 00132 /** 00133 * @brief The release version of the plug-in, including major and minor. 00134 * The version should be X.Y, X being the major, and Y the minor. 00135 * @return string The release version. 00136 */ 00137 virtual std::string release() const=0; 00138 00139 /** 00140 * @brief The version of Tulip this plug-in was built with. 00141 * Tulip versions are X.Y.Z, X eing the major, Y the minor, and Z the patch. 00142 * 00143 * @return The Tulip version the plug-in was built with. 00144 */ 00145 virtual std::string tulipRelease() const=0; 00146 00147 /** 00148 * @brief Only the major of the plug-in version. 00149 * A version should be X.Y, X being the major. 00150 * 00151 * @return The major part of the plug-in version. 00152 */ 00153 virtual std::string major() const; 00154 00155 /** 00156 * @brief Only the minor of the plug-in version. 00157 * A version should be X.Y, Y being the major. 00158 * 00159 * @return The minor part of the plug-in version. 00160 */ 00161 virtual std::string minor() const; 00162 00163 /** 00164 * @return The major Tulip version the plug-in was built with. 00165 */ 00166 virtual std::string tulipMajor() const; 00167 00168 /** 00169 * @return Return the minor Tulip version this plug-in was built with. 00170 */ 00171 virtual std::string tulipMinor() const; 00172 00173 /** 00174 * @brief Returns the ID of the glyph this factory builds. 00175 * @TODO this member should be removed once there is a system in Tulip to handle glyphs. 00176 * 00177 * @return int the id of the glyph. 00178 **/ 00179 virtual int id() const; 00180 00181 virtual std::string programmingLanguage() const; 00182 00183 }; 00184 00185 /** 00186 * @ingroup Plugins 00187 * @def PLUGININFORMATION(NAME, AUTHOR, DATE, INFO, RELEASE, GROUP) 00188 * @brief Declare meta-information for a plugin 00189 * This is an helper macro that defines every function related to a plugin meta-information (Plugin name, author, etc). 00190 * 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. 00191 * @note PLUGINIFORMATION should be declared into the Plugin's class body into the public scope 00192 * 00193 * @param NAME The plugin name as it will be registered into the plugins system (tlp::Plugin::name()) 00194 * @param AUTHOR The author of the plugin (tlp::Plugin::author()) 00195 * @param DATE The creation date (tlp::Plugin::date()) 00196 * @param INFO The plugin's description (tlp::Plugin::info()) 00197 * @param RELEASE The plugin's version number (tlp::Plugin::version()) 00198 * @param GROUP The plugin's group (tlp::Plugin::group()). If the plugin does not belong to any group, set GROUP to "". 00199 * 00200 * @see tlp::Plugin 00201 * @see PLUGIN 00202 */ 00203 #define PLUGININFORMATION(NAME, AUTHOR, DATE, INFO, RELEASE, GROUP)\ 00204 std::string name() const { return NAME; } \ 00205 std::string author() const { return AUTHOR; }\ 00206 std::string date() const { return DATE; } \ 00207 std::string info() const { return INFO; } \ 00208 std::string release() const { return RELEASE; }\ 00209 std::string tulipRelease() const { return TULIP_MM_VERSION; }\ 00210 std::string group() const { return GROUP; } 00211 00212 #define PLUGININFORMATIONS(NAME, AUTHOR, DATE, INFO, RELEASE, GROUP)\ 00213 PLUGININFORMATION(NAME, AUTHOR, DATE, INFO, RELEASE, GROUP) 00214 } 00215 00216 //This include is here because the PluginLister needs to know the Plugin type, and the PLUGIN macro needs to know the PluginLister. 00217 #include <tulip/PluginLister.h> 00218 namespace tlp { 00219 /** 00220 * @ingroup Plugins 00221 * @def PLUGIN(C) 00222 * @brief Register a plugin into the plugin system. 00223 * This macro is mandatory in order to register a plugin into Tulip. This will generate a Factory that will handle the plugin's creation. 00224 * @param C The classname of the plugin. 00225 * @note This macro should be called outside of the class body @endnote 00226 * 00227 @code{.cpp} 00228 // This sample shows a basic skeleton for a plugin class declaration: 00229 class MyPlugin: public tlp::PluginBase { // tlp::PluginBase is replaced by the acutal Plugin interface (tlp::Algorithm, tlp::View, etc) 00230 public: 00231 PLUGININFORMATION("My plugin", "Me", "28/09/2012", "My first plugin example", "1.0", "") 00232 // Class declaration and extra methods 00233 }; 00234 00235 PLUGIN(MyPlugin) // Register MyPlugin into Tulip 00236 @endcode 00237 * 00238 * @see tlp::Plugin 00239 * @see PLUGININFORMATION 00240 */ 00241 #define PLUGIN(C) \ 00242 class C##Factory : public tlp::FactoryInterface { \ 00243 public: \ 00244 C##Factory() { \ 00245 tlp::PluginLister::registerPlugin(this); \ 00246 } \ 00247 ~C##Factory(){} \ 00248 tlp::Plugin* createPluginObject(tlp::PluginContext* context) { \ 00249 C* tmp = new C(context); \ 00250 return tmp; \ 00251 } \ 00252 }; \ 00253 \ 00254 extern "C" { \ 00255 C##Factory C##FactoryInitializer; \ 00256 } 00257 00258 00259 } 00260 00261 #endif //TULIP_PLUGIN_H