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