Tulip  4.6.0
Better Visualization Through Research
library/tulip-core/include/tulip/Plugin.h
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
 All Classes Files Functions Variables Enumerations Enumerator Properties