Tulip  4.4.0
Better Visualization Through Research
 All Classes Namespaces Files Functions Variables Enumerations Enumerator Properties Groups Pages
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 1 and Inria Bordeaux - Sud Ouest
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), direction(direction) {
81  }
82  /**
83  * @return The parameter's name
84  */
85  const std::string& getName() const {
86  return name;
87  }
88  /**
89  * @return The parameter's C++ type name
90  */
91  const std::string& getTypeName() const {
92  return type;
93  }
94  /**
95  * @return The parameter's help string
96  */
97  const std::string& getHelp() const {
98  return help;
99  }
100  /**
101  * @return The parameter's default value.
102  */
103  const std::string& getDefaultValue() const {
104  return defaultValue;
105  }
106  /**
107  * @brief Set the parameter's default value.
108  */
109  void setDefaultValue(const std::string& defVal) {
110  defaultValue = defVal;
111  }
112  /**
113  * @return Whether the parameter is mandatory or not.
114  */
115  bool isMandatory() const {
116  return mandatory;
117  }
118  /**
119  * @return The parameter's direction
120  */
122  return direction;
123  }
124  /**
125  * @return Set the parameter's direction
126  */
128  direction = dir;
129  }
130 };
131 
132 /**
133  * @ingroup Plugins
134  * @brief This class describes parameters taken by a plugin.
135  *
136  * It is used by WithParameter to store parameters.
137  * 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.
138  **/
139 struct TLP_SCOPE ParameterDescriptionList {
140 
142 
143  /**
144  * @brief Adds a new parameter of type T to the list.
145  *
146  * @param parameterName The name of the parameter.
147  * @param help The help string of this parameter. Defaults to std::string().
148  * @param defaultValue The default value of this parameter. Defaults to std::string().
149  * @param isMandatory Whether this parameter is mandatory or optional. Defaults to true.
150  * @param direction The parameter's direction (see tlp::ParameterDirection for details)
151  * @return void
152  **/
153  template<typename T> void add(const std::string& parameterName,
154  const std::string& help,
155  const std::string& defaultValue,
156  bool isMandatory = true,
157  ParameterDirection direction = IN_PARAM) {
158  for (unsigned int i = 0; i < parameters.size(); ++i) {
159  if (parameters[i].getName() == parameterName) {
160 #ifndef NDEBUG
161  tlp::warning() << "ParameterDescriptionList::addVar " << parameterName << " already exists" << std::endl;
162 #endif
163  return;
164  }
165  }
166 
167  ParameterDescription newParameter(parameterName,
168  typeid(T).name(),
169  help,
170  defaultValue,
171  isMandatory, direction);
172  parameters.push_back(newParameter);
173  }
174 
175  /**
176  * @brief Retrieves an Iterator on the parameters.
177  *
178  * @return An iterator over the parameters :Iterator<ParameterDescription>*
179  **/
180  tlp::Iterator<ParameterDescription>* getParameters() const;
181 
182  /**
183  * @brief retrieves the default value of a parameter.
184  *
185  * @param parameterName The name of the parameter to retrieve the default value of.
186  * @return The default value of the parameter:string
187  **/
188  const std::string& getDefaultValue(const std::string& parameterName) const;
189 
190  /**
191  * @brief Sets the default value of a parameter.
192  *
193  * @param parameterName The name of the parameter to set the value of.
194  * @param value The new value for this parameter.
195  * @return void
196  **/
197  void setDefaultValue(const std::string& parameterName,
198  const std::string& value);
199 
200  /**
201  * @brief Sets the direction of a parameter.
202  *
203  * @param parameterName The name of the parameter to set the value of.
204  * @param dir The new direction for this parameter.
205  * @return void
206  **/
207  void setDirection(const std::string& parameterName,
208  ParameterDirection direction);
209 
210  /**
211  * @brief Retrieves whether a parameter is mandatory or optional.
212  *
213  * @param parameterName The name of the parameter for which to check if it is mandatory or optional.
214  * @return bool true if the parameter is mandatory, false if it is optional.
215  **/
216  bool isMandatory(const std::string& parameterName) const;
217 
218  /**
219  * @brief Builds a DataSet containing the default values for each parameter.
220  * If the DataSet has a key which is equal to a parameter's name, the existing value is kept.
221  *
222  * @param ioDataSet The input dataset on which the parameters names will be associated with their default values.
223  * @param inG A graph on which to create properties if any parameter is of a property type. Defaults to 0.
224  * @return void
225  **/
226  void buildDefaultDataSet(DataSet& ioDataSet, Graph* inG = NULL) const;
227 
228  /**
229  * @brief Returns the number of parameters.
230  *
231  * @return The number of parameters
232  **/
233  inline unsigned int size() const {
234  return parameters.size();
235  }
236 
237  /**
238  * @brief Test if the list is empty
239  *
240  * @return bool true if the parameter description list is empty, false otherwise.
241  **/
242  inline bool empty() const {
243  return parameters.empty();
244  }
245 
246 private:
247  ParameterDescription* getParameter(const std::string& parameterName);
248  std::vector<ParameterDescription> parameters;
249 };
250 
251 
252 #define HTML_HELP_OPEN() "<!DOCTYPE html><html><head>\
253 <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; }\
254  .paramtable { width: 100%; border: 0px; border-bottom: 1px solid #C9C9C9; padding: 5px; }\
255  .help { font-style: italic; font-size: 90%; }</style>\
256 </head><body><table border=\"0\" class=\"paramtable\">"
257 
258 #define HTML_HELP_DEF(A,B) "<tr><td><b>" A "</b><td>" B "</td></tr>"
259 
260 #define HTML_HELP_BODY() "</table><p class=\"help\">"
261 
262 #define HTML_HELP_CLOSE() "</p></body></html>"
263 
264 /**
265  * @ingroup Plugins
266  * @brief This class describes parameters on a plug-in.
267  *
268  * 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.
269  * 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.
270  **/
271 struct TLP_SCOPE WithParameter {
272 
273  /**
274  * @brief Retrieves the parameters.
275  *
276  * @return :ParameterDescriptionList the parameters of the plug-in.
277  **/
278  const tlp::ParameterDescriptionList& getParameters() const;
279 
280  /**
281  * @brief Adds an IN parameter to the plug-in.
282  *
283  * @param name The name of the parameter to add.
284  * @param help A description of the parameter, that will be displayed to the user. Defaults to "".
285  * @param defaultValue The default value the parameter should take, to be the initial value in the GUI. Defaults to "".
286  * @param isMandatory Whether this parameter requires a value or not. Defaults to true.
287  * @return void
288  **/
289  template<typename T>
290  void addInParameter(const std::string &name,
291  const std::string &help,
292  const std::string &defaultValue,
293  bool isMandatory = true) {
294  parameters.template add<T>(name, help, defaultValue, isMandatory, IN_PARAM);
295  }
296 
297  /**
298  * @brief Adds an OUT 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  * @return void
305  **/
306  template<typename T>
307  void addOutParameter(const std::string &name,
308  const std::string &help=std::string(),
309  const std::string &defaultValue = std::string(),
310  bool isMandatory = true) {
311  parameters.template add<T>(name, help, defaultValue, isMandatory, OUT_PARAM);
312  }
313 
314  /**
315  * @brief Adds an INOUT parameter to the plug-in.
316  *
317  * @param name The name of the parameter to add.
318  * @param help A description of the parameter, that will be displayed to the user. Defaults to "".
319  * @param defaultValue The default value the parameter should take, to be the initial value in the GUI. Defaults to "".
320  * @param isMandatory Whether this parameter requires a value or not. Defaults to true.
321  * @return void
322  **/
323  template<typename T>
324  void addInOutParameter(const std::string &name,
325  const std::string &help=std::string(),
326  const std::string &defaultValue = std::string(),
327  bool isMandatory = true) {
328  parameters.template add<T>(name, help, defaultValue, isMandatory, INOUT_PARAM);
329  }
330 
331  /**
332  * @brief Adds an IN parameter to the plug-in (deprecated)
333  *
334  * @see addInParameter()
335  * @see addOutParameter()
336  *
337  * @param name The name of the parameter to add.
338  * @param help A description of the parameter, that will de displayed to the user. Defaults to 0.
339  * @param defaultValue The default value the parameter should take, to be the initial value in the GUI. Defaults to 0.
340  * @param isMandatory Whether this parameter requires a value or not. Defaults to true.
341  * @return void
342  **/
343  template<typename T>
344  _DEPRECATED void addParameter(const std::string &name,
345  const std::string &help=std::string(),
346  const std::string &defaultValue = std::string(),
347  bool isMandatory = true) {
348  addInParameter<T>(name, help, defaultValue, isMandatory);
349  }
350 
351  /**
352  * @brief indicates whether the embedded parameters require some user input
353  *
354  * @return true if an input parameter or a property output parameter exists
355  **/
356  bool inputRequired() const;
357 
358 protected:
359 
360  /**
361  * @brief The internal structure storing the parameters.
362  **/
364 };
365 
366 
367 }
368 #endif