Tulip  4.10.0
Better Visualization Through Research
WithParameter.h
1 /*
2  *
3  * This file is part of Tulip (www.tulip-software.org)
4  *
5  * Authors: David Auber and the Tulip development Team
6  * from LaBRI, University of Bordeaux
7  *
8  * Tulip is free software; you can redistribute it and/or modify
9  * it under the terms of the GNU Lesser General Public License
10  * as published by the Free Software Foundation, either version 3
11  * of the License, or (at your option) any later version.
12  *
13  * Tulip is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
16  * See the GNU General Public License for more details.
17  *
18  */
19 
20 #ifndef _TULIPWITHPARAMETER
21 #define _TULIPWITHPARAMETER
22 
23 #include <string>
24 #include <typeinfo>
25 #include <vector>
26 
27 #include <tulip/tulipconf.h>
28 
29 namespace tlp {
30 
31 class Graph;
32 class DataSet;
33 template<class itType >
34 struct Iterator;
35 
36 /**
37  * @ingroup Plugins
38  * @brief The ParameterDirection enum describes how a parameter is passed to a plugin
39  * The parameter can be seen as passing parameters to a C++ functions and works as follow:
40  * @list
41  * @li IN_PARAM: The parameter is passes by value
42  * @li OUT_PARAM: The parameter is a return value
43  * @li INOUT_PARAM: The parameter is passed by reference.
44  * @endlist
45  */
46 enum ParameterDirection { IN_PARAM=0, OUT_PARAM = 1, INOUT_PARAM = 2 };
47 
48 /**
49  * @ingroup Plugins
50  * @brief Describes a plugin's parameter.
51  *
52  * A plugin parameter consists of the following information:
53  * @list
54  * @li A name (std::string) which can be used to retrieve the value of the parameter when running the plugin.
55  * @li A type (std::string) which is the C++ typename of the parameter.
56  * @li A help string (std::string) which gives additional information about the parameter and its possible values.
57  * @li A default value which is mapped on the parameter if no value has been entered by the user.
58  * @li The mandatory flag (bool) which tells if the parameter is optional or not.
59  * @li A ParameterDirection (enum).
60  * @endlist
61  *
62  * @see tlp::ParameterDirection
63  * @see tlp::ParameterDescriptionList
64  * @see tlp::WithParameter
65  **/
66 class TLP_SCOPE ParameterDescription {
67 private:
68  std::string name;
69  std::string type;
70  std::string help;
71  std::string defaultValue;
72  bool mandatory;
73  ParameterDirection direction;
74 public:
76  ParameterDescription(const std::string& name, const std::string& type,
77  const std::string& help, const std::string& defaultValue,
78  bool mandatory, ParameterDirection direction)
79  : name(name), type(type), help(help),
80  defaultValue(defaultValue), mandatory(mandatory),
81  direction(direction) {}
82 
83  /**
84  * @return The parameter's name
85  */
86  const std::string& getName() const {
87  return name;
88  }
89  /**
90  * @return The parameter's C++ type name
91  */
92  const std::string& getTypeName() const {
93  return type;
94  }
95  /**
96  * @return The parameter's help string
97  */
98  const std::string& getHelp() const {
99  return help;
100  }
101  /**
102  * @return The parameter's default value.
103  */
104  const std::string& getDefaultValue() const {
105  return defaultValue;
106  }
107  /**
108  * @brief Set the parameter's default value.
109  */
110  void setDefaultValue(const std::string& defVal) {
111  defaultValue = defVal;
112  }
113  /**
114  * @return Whether the parameter is mandatory or not.
115  */
116  bool isMandatory() const {
117  return mandatory;
118  }
119  /**
120  * @return The parameter's direction
121  */
123  return direction;
124  }
125  /**
126  * @return Set the parameter's direction
127  */
129  direction = dir;
130  }
131  /**
132  * @return Whether the parameter is editable or not.
133  */
134  bool isEditable() const {
135  // input parameters are editable
136  return (direction != OUT_PARAM) ||
137  // only property output parameters are editable
138  (type.find("Property") != std::string::npos);
139  }
140 };
141 
142 /**
143  * @ingroup Plugins
144  * @brief This class describes parameters taken by a plugin.
145  *
146  * It is used by WithParameter to store parameters.
147  * 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.
148  **/
149 struct TLP_SCOPE ParameterDescriptionList {
150 
152 
153  /**
154  * @brief Adds a new parameter of type T to the list.
155  *
156  * @param parameterName The name of the parameter.
157  * @param help The help string of this parameter. Defaults to std::string().
158  * @param defaultValue The default value of this parameter. Defaults to std::string().
159  * @param isMandatory Whether this parameter is mandatory or optional. Defaults to true.
160  * @param direction The parameter's direction (see tlp::ParameterDirection for details)
161  * @return void
162  **/
163  template<typename T> void add(const std::string& parameterName,
164  const std::string& help,
165  const std::string& defaultValue,
166  bool isMandatory = true,
167  ParameterDirection direction = IN_PARAM,
168  const std::string &valuesDescription = std::string()) {
169  for (unsigned int i = 0; i < parameters.size(); ++i) {
170  if (parameters[i].getName() == parameterName) {
171 #ifndef NDEBUG
172  tlp::warning() << "ParameterDescriptionList::addVar " << parameterName << " already exists" << std::endl;
173 #endif
174  return;
175  }
176  }
177 
178  ParameterDescription newParameter(parameterName,
179  typeid(T).name(),
180  generateParameterHTMLDocumentation(parameterName, help, typeid(T).name(), defaultValue, valuesDescription, direction),
181  defaultValue,
182  isMandatory, direction);
183  parameters.push_back(newParameter);
184  }
185 
186  /**
187  * @brief Retrieves an Iterator on the parameters.
188  *
189  * @return An iterator over the parameters :Iterator<ParameterDescription>*
190  **/
191  tlp::Iterator<ParameterDescription>* getParameters() const;
192 
193  /**
194  * @brief retrieves the default value of a parameter.
195  *
196  * @param parameterName The name of the parameter to retrieve the default value of.
197  * @return The default value of the parameter:string
198  **/
199  const std::string& getDefaultValue(const std::string& parameterName) const;
200 
201  /**
202  * @brief Sets the default value of a parameter.
203  *
204  * @param parameterName The name of the parameter to set the value of.
205  * @param value The new value for this parameter.
206  * @return void
207  **/
208  void setDefaultValue(const std::string& parameterName,
209  const std::string& value);
210 
211  /**
212  * @brief Sets the direction of a parameter.
213  *
214  * @param parameterName The name of the parameter to set the value of.
215  * @param dir The new direction for this parameter.
216  * @return void
217  **/
218  void setDirection(const std::string& parameterName,
219  ParameterDirection direction);
220 
221  /**
222  * @brief Retrieves whether a parameter is mandatory or optional.
223  *
224  * @param parameterName The name of the parameter for which to check if it is mandatory or optional.
225  * @return bool true if the parameter is mandatory, false if it is optional.
226  **/
227  bool isMandatory(const std::string& parameterName) const;
228 
229  /**
230  * @brief Builds a DataSet containing the default values for each parameter.
231  * If the DataSet has a key which is equal to a parameter's name, the existing value is kept.
232  *
233  * @param ioDataSet The input dataset on which the parameters names will be associated with their default values.
234  * @param inG A graph on which to create properties if any parameter is of a property type. Defaults to 0.
235  * @return void
236  **/
237  void buildDefaultDataSet(DataSet& ioDataSet, Graph* inG = NULL) const;
238 
239  /**
240  * @brief Returns the number of parameters.
241  *
242  * @return The number of parameters
243  **/
244  inline unsigned int size() const {
245  return parameters.size();
246  }
247 
248  /**
249  * @brief Test if the list is empty
250  *
251  * @return bool true if the parameter description list is empty, false otherwise.
252  **/
253  inline bool empty() const {
254  return parameters.empty();
255  }
256 
257 private:
258  ParameterDescription* getParameter(const std::string& parameterName);
259  std::string generateParameterHTMLDocumentation(const std::string &name, const std::string &help,
260  const std::string &type,
261  const std::string &defaultValue,
262  const std::string &valuesDescription,
263  const ParameterDirection &direction);
264  std::vector<ParameterDescription> parameters;
265 };
266 
267 
268 #define HTML_HELP_OPEN() "<!DOCTYPE html><html><head>\
269 <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; }\
270  .paramtable { width: 100%; border: 0px; border-bottom: 1px solid #C9C9C9; padding: 5px; }\
271  .help { font-style: italic; font-size: 90%; }\
272  .b { padding-left: 5px; }</style>\
273 </head><body><table border=\"0\" class=\"paramtable\">"
274 
275 #define HTML_HELP_DEF(A,B) "<tr><td><b>" A "</b><td class=\"b\">" B "</td></tr>"
276 
277 #define HTML_HELP_BODY() "</table><p class=\"help\">"
278 
279 #define HTML_HELP_CLOSE() "</p></body></html>"
280 
281 /**
282  * @ingroup Plugins
283  * @brief This class describes parameters on a plug-in.
284  *
285  * 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.
286  * 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.
287  **/
288 struct TLP_SCOPE WithParameter {
289 
290  /**
291  * @brief Retrieves the parameters.
292  *
293  * @return :ParameterDescriptionList the parameters of the plug-in.
294  **/
295  const tlp::ParameterDescriptionList& getParameters() const;
296 
297  /**
298  * @brief Adds an IN parameter to the plug-in.
299  *
300  * @param name The name of the parameter to add.
301  * @param help A description of the parameter, that will be displayed to the user. Defaults to "".
302  * @param defaultValue The default value the parameter should take, to be the initial value in the GUI. Defaults to "".
303  * @param isMandatory Whether this parameter requires a value or not. Defaults to true.
304  * @param valuesDescription A description of the values the parameter can take (usually for detailing the content of a StringCollection). Defaults to "".
305  * @return void
306  **/
307  template<typename T>
308  void addInParameter(const std::string &name,
309  const std::string &help,
310  const std::string &defaultValue,
311  bool isMandatory = true,
312  const std::string &valuesDescription = std::string()) {
313  parameters.template add<T>(name, help, defaultValue, isMandatory, IN_PARAM, valuesDescription);
314  }
315 
316  /**
317  * @brief Adds an OUT parameter to the plug-in.
318  *
319  * @param name The name of the parameter to add.
320  * @param help A description of the parameter, that will be displayed to the user. Defaults to "".
321  * @param defaultValue The default value the parameter should take, to be the initial value in the GUI. Defaults to "".
322  * @param isMandatory Whether this parameter requires a value or not. Defaults to true.
323  * @param valuesDescription A description of the values the parameter can take (usually for detailing the content of a StringCollection). Defaults to "".
324  * @return void
325  **/
326  template<typename T>
327  void addOutParameter(const std::string &name,
328  const std::string &help=std::string(),
329  const std::string &defaultValue = std::string(),
330  bool isMandatory = true,
331  const std::string &valuesDescription = std::string()) {
332  parameters.template add<T>(name, help, defaultValue, isMandatory, OUT_PARAM, valuesDescription);
333  }
334 
335  /**
336  * @brief Adds an INOUT parameter to the plug-in.
337  *
338  * @param name The name of the parameter to add.
339  * @param help A description of the parameter, that will be displayed to the user. Defaults to "".
340  * @param defaultValue The default value the parameter should take, to be the initial value in the GUI. Defaults to "".
341  * @param isMandatory Whether this parameter requires a value or not. Defaults to true.
342  * @param valuesDescription A description of the values the parameter can take (usually for detailing the content of a StringCollection). Defaults to "".
343  * @return void
344  **/
345  template<typename T>
346  void addInOutParameter(const std::string &name,
347  const std::string &help=std::string(),
348  const std::string &defaultValue = std::string(),
349  bool isMandatory = true,
350  const std::string &valuesDescription = std::string()) {
351  parameters.template add<T>(name, help, defaultValue, isMandatory, INOUT_PARAM, valuesDescription);
352  }
353 
354  /**
355  * @brief Adds an IN parameter to the plug-in (deprecated)
356  *
357  * @see addInParameter()
358  * @see addOutParameter()
359  *
360  * @param name The name of the parameter to add.
361  * @param help A description of the parameter, that will de displayed to the user. Defaults to 0.
362  * @param defaultValue The default value the parameter should take, to be the initial value in the GUI. Defaults to 0.
363  * @param isMandatory Whether this parameter requires a value or not. Defaults to true.
364  * @return void
365  **/
366  template<typename T>
367  _DEPRECATED void addParameter(const std::string &name,
368  const std::string &help=std::string(),
369  const std::string &defaultValue = std::string(),
370  bool isMandatory = true) {
371  addInParameter<T>(name, help, defaultValue, isMandatory);
372  }
373 
374  /**
375  * @brief indicates whether the embedded parameters require some user input
376  *
377  * @return true if an input parameter or a property output parameter exists
378  **/
379  bool inputRequired() const;
380 
381 ///@cond DOXYGEN_HIDDEN
382 protected:
383 
384  /**
385  * @brief The internal structure storing the parameters.
386  **/
387  ParameterDescriptionList parameters;
388 ///@endcond
389 };
390 
391 
392 }
393 #endif
const std::string & getName() const
Definition: WithParameter.h:86
bool empty() const
Test if the list is empty.
Interface for Tulip iterators. Allows basic iteration operations only.
Definition: Iterator.h:39
void setDirection(ParameterDirection dir)
void addOutParameter(const std::string &name, const std::string &help=std::string(), const std::string &defaultValue=std::string(), bool isMandatory=true, const std::string &valuesDescription=std::string())
Adds an OUT parameter to the plug-in.
A container that can store data from any type.
Definition: DataSet.h:172
ParameterDirection getDirection() const
unsigned int size() const
Returns the number of parameters.
void setDefaultValue(const std::string &defVal)
Set the parameter&#39;s default value.
ParameterDirection
The ParameterDirection enum describes how a parameter is passed to a plugin The parameter can be seen...
Definition: WithParameter.h:46
void addParameter(const std::string &name, const std::string &help=std::string(), const std::string &defaultValue=std::string(), bool isMandatory=true)
Adds an IN parameter to the plug-in (deprecated)
void add(const std::string &parameterName, const std::string &help, const std::string &defaultValue, bool isMandatory=true, ParameterDirection direction=IN_PARAM, const std::string &valuesDescription=std::string())
Adds a new parameter of type T to the list.
void addInOutParameter(const std::string &name, const std::string &help=std::string(), const std::string &defaultValue=std::string(), bool isMandatory=true, const std::string &valuesDescription=std::string())
Adds an INOUT parameter to the plug-in.
const std::string & getHelp() const
Definition: WithParameter.h:98
const std::string & getTypeName() const
Definition: WithParameter.h:92
void addInParameter(const std::string &name, const std::string &help, const std::string &defaultValue, bool isMandatory=true, const std::string &valuesDescription=std::string())
Adds an IN parameter to the plug-in.
const std::string & getDefaultValue() const
This class describes parameters taken by a plugin.
Describes a plugin&#39;s parameter.
Definition: WithParameter.h:66
This class describes parameters on a plug-in.