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 _TULIPWITHPARAMETER 00021 #define _TULIPWITHPARAMETER 00022 00023 #include <string> 00024 #include <typeinfo> 00025 #include <vector> 00026 00027 #include <tulip/tulipconf.h> 00028 00029 namespace tlp { 00030 00031 class Graph; 00032 class DataSet; 00033 template<class itType > 00034 struct Iterator; 00035 00036 /** 00037 * @ingroup Plugins 00038 * @brief The ParameterDirection enum describes how a parameter is passed to a plugin 00039 * The parameter can be seen as passing parameters to a C++ functions and works as follow: 00040 * @list 00041 * @li IN_PARAM: The parameter is passes by value 00042 * @li OUT_PARAM: The parameter is a return value 00043 * @li INOUT_PARAM: The parameter is passed by reference. 00044 * @endlist 00045 */ 00046 enum ParameterDirection { IN_PARAM=0, OUT_PARAM = 1, INOUT_PARAM = 2 }; 00047 00048 /** 00049 * @ingroup Plugins 00050 * @brief Describes a plugin's parameter. 00051 * 00052 * A plugin parameter consists of the following information: 00053 * @list 00054 * @li A name (std::string) which can be used to retrieve the value of the parameter when running the plugin. 00055 * @li A type (std::string) which is the C++ typename of the parameter. 00056 * @li A help string (std::string) which gives additional information about the parameter and its possible values. 00057 * @li A default value which is mapped on the parameter if no value has been entered by the user. 00058 * @li The mandatory flag (bool) which tells if the parameter is optional or not. 00059 * @li A ParameterDirection (enum). 00060 * @endlist 00061 * 00062 * @see tlp::ParameterDirection 00063 * @see tlp::ParameterDescriptionList 00064 * @see tlp::WithParameter 00065 **/ 00066 class TLP_SCOPE ParameterDescription { 00067 private: 00068 std::string name; 00069 std::string type; 00070 std::string help; 00071 std::string defaultValue; 00072 bool mandatory; 00073 ParameterDirection direction; 00074 public: 00075 ParameterDescription() {} 00076 ParameterDescription(const std::string& name, const std::string& type, 00077 const std::string& help, const std::string& defaultValue, 00078 bool mandatory, ParameterDirection direction) 00079 : name(name), type(type), help(help), 00080 defaultValue(defaultValue), mandatory(mandatory), direction(direction) { 00081 } 00082 /** 00083 * @return The parameter's name 00084 */ 00085 const std::string& getName() const { 00086 return name; 00087 } 00088 /** 00089 * @return The parameter's C++ type name 00090 */ 00091 const std::string& getTypeName() const { 00092 return type; 00093 } 00094 /** 00095 * @return The parameter's help string 00096 */ 00097 const std::string& getHelp() const { 00098 return help; 00099 } 00100 /** 00101 * @return The parameter's default value. 00102 */ 00103 const std::string& getDefaultValue() const { 00104 return defaultValue; 00105 } 00106 /** 00107 * @brief Set the parameter's default value. 00108 */ 00109 void setDefaultValue(const std::string& defVal) { 00110 defaultValue = defVal; 00111 } 00112 /** 00113 * @return Whether the parameter is mandatory or not. 00114 */ 00115 bool isMandatory() const { 00116 return mandatory; 00117 } 00118 /** 00119 * @return The parameter's direction 00120 */ 00121 ParameterDirection getDirection() const { 00122 return direction; 00123 } 00124 /** 00125 * @return Set the parameter's direction 00126 */ 00127 void setDirection(ParameterDirection dir) { 00128 direction = dir; 00129 } 00130 }; 00131 00132 /** 00133 * @ingroup Plugins 00134 * @brief This class describes parameters taken by a plugin. 00135 * 00136 * It is used by WithParameter to store parameters. 00137 * Each parameter is identified by a name, has a default value, a value, a help string, and a boolean indicating whether it is mandatory or optional. 00138 **/ 00139 struct TLP_SCOPE ParameterDescriptionList { 00140 00141 ParameterDescriptionList() {} 00142 00143 /** 00144 * @brief Adds a new parameter of type T to the list. 00145 * 00146 * @param parameterName The name of the parameter. 00147 * @param help The help string of this parameter. Defaults to std::string(). 00148 * @param defaultValue The default value of this parameter. Defaults to std::string(). 00149 * @param isMandatory Whether this parameter is mandatory or optional. Defaults to true. 00150 * @param direction The parameter's direction (see tlp::ParameterDirection for details) 00151 * @return void 00152 **/ 00153 template<typename T> void add(const std::string& parameterName, 00154 const std::string& help, 00155 const std::string& defaultValue, 00156 bool isMandatory = true, 00157 ParameterDirection direction = IN_PARAM) { 00158 for (unsigned int i = 0; i < parameters.size(); ++i) { 00159 if (parameters[i].getName() == parameterName) { 00160 #ifndef NDEBUG 00161 tlp::warning() << "ParameterDescriptionList::addVar " << parameterName << " already exists" << std::endl; 00162 #endif 00163 return; 00164 } 00165 } 00166 00167 ParameterDescription newParameter(parameterName, 00168 typeid(T).name(), 00169 help, 00170 defaultValue, 00171 isMandatory, direction); 00172 parameters.push_back(newParameter); 00173 } 00174 00175 /** 00176 * @brief Retrieves an Iterator on the parameters. 00177 * 00178 * @return An iterator over the parameters :Iterator<ParameterDescription>* 00179 **/ 00180 tlp::Iterator<ParameterDescription>* getParameters() const; 00181 00182 /** 00183 * @brief retrieves the default value of a parameter. 00184 * 00185 * @param parameterName The name of the parameter to retrieve the default value of. 00186 * @return The default value of the parameter:string 00187 **/ 00188 const std::string& getDefaultValue(const std::string& parameterName) const; 00189 00190 /** 00191 * @brief Sets the default value of a parameter. 00192 * 00193 * @param parameterName The name of the parameter to set the value of. 00194 * @param value The new value for this parameter. 00195 * @return void 00196 **/ 00197 void setDefaultValue(const std::string& parameterName, 00198 const std::string& value); 00199 00200 /** 00201 * @brief Sets the direction of a parameter. 00202 * 00203 * @param parameterName The name of the parameter to set the value of. 00204 * @param dir The new direction for this parameter. 00205 * @return void 00206 **/ 00207 void setDirection(const std::string& parameterName, 00208 ParameterDirection direction); 00209 00210 /** 00211 * @brief Retrieves whether a parameter is mandatory or optional. 00212 * 00213 * @param parameterName The name of the parameter for which to check if it is mandatory or optional. 00214 * @return bool true if the parameter is mandatory, false if it is optional. 00215 **/ 00216 bool isMandatory(const std::string& parameterName) const; 00217 00218 /** 00219 * @brief Builds a DataSet containing the default values for each parameter. 00220 * If the DataSet has a key which is equal to a parameter's name, the existing value is kept. 00221 * 00222 * @param ioDataSet The input dataset on which the parameters names will be associated with their default values. 00223 * @param inG A graph on which to create properties if any parameter is of a property type. Defaults to 0. 00224 * @return void 00225 **/ 00226 void buildDefaultDataSet(DataSet& ioDataSet, Graph* inG = NULL) const; 00227 00228 /** 00229 * @brief Returns the number of parameters. 00230 * 00231 * @return The number of parameters 00232 **/ 00233 inline unsigned int size() const { 00234 return parameters.size(); 00235 } 00236 00237 /** 00238 * @brief Test if the list is empty 00239 * 00240 * @return bool true if the parameter description list is empty, false otherwise. 00241 **/ 00242 inline bool empty() const { 00243 return parameters.empty(); 00244 } 00245 00246 private: 00247 ParameterDescription* getParameter(const std::string& parameterName); 00248 std::vector<ParameterDescription> parameters; 00249 }; 00250 00251 00252 #define HTML_HELP_OPEN() "<!DOCTYPE html><html><head>\ 00253 <style type=\"text/css\">.body { font-family: \"Segoe UI\", Candara, \"Bitstream Vera Sans\", \"DejaVu Sans\", \"Bitstream Vera Sans\", \"Trebuchet MS\", Verdana, \"Verdana Ref\", sans-serif; }\ 00254 .paramtable { width: 100%; border: 0px; border-bottom: 1px solid #C9C9C9; padding: 5px; }\ 00255 .help { font-style: italic; font-size: 90%; }</style>\ 00256 </head><body><table border=\"0\" class=\"paramtable\">" 00257 00258 #define HTML_HELP_DEF(A,B) "<tr><td><b>" A "</b><td>" B "</td></tr>" 00259 00260 #define HTML_HELP_BODY() "</table><p class=\"help\">" 00261 00262 #define HTML_HELP_CLOSE() "</p></body></html>" 00263 00264 /** 00265 * @ingroup Plugins 00266 * @brief This class describes parameters on a plug-in. 00267 * 00268 * These parameters can be of any type, and are used to generate a GUI that will be shown when the plug-in in invoked by the user. 00269 * It is mainly used by algorithms to display options to the user, e.g. a clustering algorithm can let the user choose which measure to use. 00270 **/ 00271 struct TLP_SCOPE WithParameter { 00272 00273 /** 00274 * @brief Retrieves the parameters. 00275 * 00276 * @return :ParameterDescriptionList the parameters of the plug-in. 00277 **/ 00278 const tlp::ParameterDescriptionList& getParameters() const; 00279 00280 /** 00281 * @brief Adds an IN parameter to the plug-in. 00282 * 00283 * @param name The name of the parameter to add. 00284 * @param help A description of the parameter, that will be displayed to the user. Defaults to "". 00285 * @param defaultValue The default value the parameter should take, to be the initial value in the GUI. Defaults to "". 00286 * @param isMandatory Whether this parameter requires a value or not. Defaults to true. 00287 * @return void 00288 **/ 00289 template<typename T> 00290 void addInParameter(const std::string &name, 00291 const std::string &help, 00292 const std::string &defaultValue, 00293 bool isMandatory = true) { 00294 parameters.template add<T>(name, help, defaultValue, isMandatory, IN_PARAM); 00295 } 00296 00297 /** 00298 * @brief Adds an OUT parameter to the plug-in. 00299 * 00300 * @param name The name of the parameter to add. 00301 * @param help A description of the parameter, that will be displayed to the user. Defaults to "". 00302 * @param defaultValue The default value the parameter should take, to be the initial value in the GUI. Defaults to "". 00303 * @param isMandatory Whether this parameter requires a value or not. Defaults to true. 00304 * @return void 00305 **/ 00306 template<typename T> 00307 void addOutParameter(const std::string &name, 00308 const std::string &help=std::string(), 00309 const std::string &defaultValue = std::string(), 00310 bool isMandatory = true) { 00311 parameters.template add<T>(name, help, defaultValue, isMandatory, OUT_PARAM); 00312 } 00313 00314 /** 00315 * @brief Adds an INOUT parameter to the plug-in. 00316 * 00317 * @param name The name of the parameter to add. 00318 * @param help A description of the parameter, that will be displayed to the user. Defaults to "". 00319 * @param defaultValue The default value the parameter should take, to be the initial value in the GUI. Defaults to "". 00320 * @param isMandatory Whether this parameter requires a value or not. Defaults to true. 00321 * @return void 00322 **/ 00323 template<typename T> 00324 void addInOutParameter(const std::string &name, 00325 const std::string &help=std::string(), 00326 const std::string &defaultValue = std::string(), 00327 bool isMandatory = true) { 00328 parameters.template add<T>(name, help, defaultValue, isMandatory, INOUT_PARAM); 00329 } 00330 00331 /** 00332 * @brief Adds an IN parameter to the plug-in (deprecated) 00333 * 00334 * @see addInParameter() 00335 * @see addOutParameter() 00336 * 00337 * @param name The name of the parameter to add. 00338 * @param help A description of the parameter, that will de displayed to the user. Defaults to 0. 00339 * @param defaultValue The default value the parameter should take, to be the initial value in the GUI. Defaults to 0. 00340 * @param isMandatory Whether this parameter requires a value or not. Defaults to true. 00341 * @return void 00342 **/ 00343 template<typename T> 00344 _DEPRECATED void addParameter(const std::string &name, 00345 const std::string &help=std::string(), 00346 const std::string &defaultValue = std::string(), 00347 bool isMandatory = true) { 00348 addInParameter<T>(name, help, defaultValue, isMandatory); 00349 } 00350 00351 /** 00352 * @brief indicates whether the embedded parameters require some user input 00353 * 00354 * @return true if an input parameter or a property output parameter exists 00355 **/ 00356 bool inputRequired() const; 00357 00358 protected: 00359 00360 /** 00361 * @brief The internal structure storing the parameters. 00362 **/ 00363 ParameterDescriptionList parameters; 00364 }; 00365 00366 00367 } 00368 #endif