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_PLUGINLISTER_H 00021 #define TULIP_PLUGINLISTER_H 00022 00023 #include <list> 00024 #include <string> 00025 #include <map> 00026 00027 #include <tulip/Plugin.h> 00028 #include <tulip/PluginLoader.h> 00029 #include <tulip/Observable.h> 00030 00031 00032 namespace tlp { 00033 class PluginContext; 00034 00035 /** 00036 * @ingroup Plugins 00037 * @brief The base class for plugin factories. 00038 * 00039 * A plugin factory handles the creation process of a tlp::Plugin subclass. This class should never be used directly. See the PLUGIN macro for additional information. 00040 * @see PLUGIN 00041 **/ 00042 class FactoryInterface { 00043 public: 00044 virtual tlp::Plugin* createPluginObject(tlp::PluginContext* context) = 0; 00045 }; 00046 00047 /** 00048 * @ingroup Plugins 00049 * 00050 * @brief The PluginLister class is a singleton used to list plugins currently loaded into Tulip and retrieve information about them. 00051 * 00052 * This class holds various methods to check information about plugins currently loaded into Tulip. You can use it to list plugins, get dependencies information or create an instance of a plugin. 00053 * 00054 * @note Since a plugin name is unique, Plugins are mainly identified by their name (tlp::Plugin::name()) when interfaced with the plugin lister. 00055 * 00056 * @see tlp::Plugin 00057 * @see tlp::PluginLoader 00058 * @see tlp::PluginLibraryLoader 00059 */ 00060 class TLP_SCOPE PluginLister : public Observable { 00061 private: 00062 struct PluginDescription { 00063 FactoryInterface* factory; 00064 std::string library; 00065 Plugin* infos; 00066 00067 PluginDescription(): factory(NULL), infos(NULL) {} 00068 ~PluginDescription() { 00069 delete infos; 00070 } 00071 }; 00072 00073 public: 00074 static PluginLoader *currentLoader; 00075 00076 /** 00077 * @brief Checks if all registered plug-ins have their dependencies met. 00078 * 00079 * @param loader If there are errors, the loader is informed about them so they can be displayed. 00080 * @return void 00081 **/ 00082 static void checkLoadedPluginsDependencies(tlp::PluginLoader* loader); 00083 00084 /** 00085 * @brief Gets the static instance of this class. If not already done, creates it beforehand. 00086 * 00087 * @return PluginLister< ObjectType, Context >* The only instance of this object that exists in the whole program. 00088 **/ 00089 static tlp::PluginLister* instance(); 00090 00091 /** 00092 * @brief Constructs a plug-in. 00093 * 00094 * @param name The name of the plug-in to instantiate. 00095 * @param p The context to give to the plug-in. 00096 * @return ObjectType* The newly constructed plug-in. 00097 **/ 00098 static tlp::Plugin* getPluginObject(const std::string& name, tlp::PluginContext* context); 00099 00100 /** 00101 * @brief Checks if a plugin of a given type is loaded 00102 * This method checks the plugin "pluginName" is currently loaded into Tulip and if it's of type PluginType. 00103 * @param PluginType the class type of the plugin 00104 * @param pluginName the name of the plugin 00105 * @return true if a matching plugin is currently loaded into Tulip. 00106 */ 00107 template<typename PluginType> 00108 bool pluginExists(const std::string &pluginName) { 00109 std::map<std::string, PluginDescription>::const_iterator it = 00110 _plugins.find(pluginName); 00111 return (it != _plugins.end() && 00112 (dynamic_cast<const PluginType*>(it->second.infos) != NULL)); 00113 } 00114 00115 /** 00116 * @brief Similar to tlp::PluginLister::getPluginObject() but returns a typed instance 00117 * 00118 * This method instantiate a plugin from its name and returns it casted into the given type. 00119 * 00120 * @param name The plugin's name 00121 * @param context The context to give to the plugin 00122 * 00123 * @return The plugin instance. If there is no such plugin or if the plugin does not match the required type, this method returns NULL 00124 */ 00125 template<typename PluginType> 00126 PluginType* getPluginObject(const std::string& name, 00127 tlp::PluginContext* context) { 00128 std::map<std::string, PluginDescription>::const_iterator it = 00129 _plugins.find(name); 00130 return (it != _plugins.end() && 00131 (dynamic_cast<const PluginType*>(it->second.infos) != NULL)) 00132 ? static_cast<PluginType*>(it->second.factory->createPluginObject(context)) 00133 : NULL; 00134 } 00135 00136 00137 /** 00138 * @brief Gets the list of plugins of a given type (template parameter). * 00139 * @return A std::list<std::string> containing the names of the plugins. 00140 **/ 00141 static std::list<std::string> availablePlugins(); 00142 00143 00144 template<typename PluginType> 00145 std::list<std::string> availablePlugins() { 00146 std::list<std::string> keys; 00147 00148 for(std::map<std::string, PluginDescription>::const_iterator it = _plugins.begin(); it != _plugins.end(); ++it) { 00149 PluginType* plugin = dynamic_cast<PluginType*>(it->second.infos); 00150 00151 if(plugin != NULL) { 00152 keys.push_back(it->first); 00153 } 00154 } 00155 00156 return keys; 00157 } 00158 00159 /** 00160 * @brief Gets more detailed information about one specific plug-in. 00161 * 00162 * @param name The name of the plugin to retrieve information for. 00163 * @return :const Plugin& The information on the plugin. 00164 **/ 00165 static const Plugin& pluginInformation(const std::string& name); 00166 00167 /** 00168 * @brief Gets more detailed information about one specific plug-in. 00169 * @deprecated this function should not be used anymore, please use PluginLister::pluginInformation() instead. 00170 * 00171 * @param name The name of the plugin to retrieve information for. 00172 * @return :const Plugin& The information on the plugin. 00173 **/ 00174 static _DEPRECATED const Plugin& pluginInformations(const std::string& name); 00175 00176 /** 00177 * @brief Checks if a given name is registered in this factory. 00178 * 00179 * @param pluginName The name of the plug-in to look for. 00180 * @return bool Whether there is a plug-in with the given name registered in this factory. 00181 **/ 00182 static bool pluginExists(const std::string& pluginName); 00183 00184 /** 00185 * @brief Gets the list of parameters for the given plug-in. 00186 * 00187 * @param name The name of the plug-in to retrieve the parameters of. 00188 * @return :ParameterDescriptionList The parameters of the plug-in. 00189 **/ 00190 static const ParameterDescriptionList& getPluginParameters(const std::string& name); 00191 00192 /** 00193 * @brief Gets the dependencies of a plug-in. 00194 * 00195 * @param name The name of the plug-in to retrieve the dependencies of. 00196 * @return :list< tlp::Dependency, std::allocator< tlp::Dependency > > The list of dependencies of the plug-in. 00197 **/ 00198 static const std::list<tlp::Dependency>& getPluginDependencies(const std::string& name); 00199 00200 /** 00201 * @brief Gets the library from which a plug-in has been loaded. 00202 * 00203 * @param name The name of the plug-in to retrieve the library of. 00204 * @return std::string The library from which the plug-in was loaded. 00205 **/ 00206 static std::string getPluginLibrary(const std::string& name); 00207 00208 /** 00209 * @brief Removes a plug-in from this factory. 00210 * This is usefull when a plug-in has unmet dependencies, or appears more than once. 00211 * 00212 * @param name The name of the plug-in to remove. 00213 * @return void 00214 **/ 00215 static void removePlugin(const std::string& name); 00216 00217 /** 00218 * @brief Registers a plugin into Tulip 00219 * 00220 * @warning This method should only be called by tlp::FactoryInterface subclasses 00221 * @see PLUGIN 00222 */ 00223 static void registerPlugin(FactoryInterface* objectFactory); 00224 00225 protected: 00226 00227 00228 void sendPluginAddedEvent(const std::string &pluginName); 00229 void sendPluginRemovedEvent(const std::string &pluginName); 00230 00231 static PluginLister* _instance; 00232 00233 /** 00234 * @brief Stores the factory, dependencies, and parameters of all the plugins that register into this factory. 00235 **/ 00236 std::map<std::string , PluginDescription> _plugins; 00237 00238 /** 00239 * @brief Gets the release number of the given plug-in. 00240 * 00241 * @param name The name of the plug-in to retrieve the version number of. 00242 * @return :string The version number, ussually formatted as X[.Y], where X is the major, and Y the minor. 00243 **/ 00244 static std::string getPluginRelease(const std::string& name); 00245 }; 00246 00247 class TLP_SCOPE PluginEvent : public Event { 00248 public: 00249 00250 enum PluginEventType { 00251 TLP_ADD_PLUGIN = 0, 00252 TLP_REMOVE_PLUGIN = 1 00253 }; 00254 00255 // constructor for node/edge events 00256 PluginEvent(PluginEventType pluginEvtType, const std::string& pluginName) 00257 : Event(*(tlp::PluginLister::instance()), Event::TLP_MODIFICATION), 00258 evtType(pluginEvtType), pluginName(pluginName) {} 00259 00260 PluginEventType getType() const { 00261 return evtType; 00262 } 00263 00264 std::string getPluginName() const { 00265 return pluginName; 00266 } 00267 00268 protected: 00269 00270 PluginEventType evtType; 00271 std::string pluginName; 00272 00273 }; 00274 00275 } 00276 00277 #endif //TULIP_PLUGINLISTER_H