Tulip  4.3.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 informations:
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 Sets 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 
126 /**
127  * @ingroup Plugins
128  * @brief This class describes parameters taken by a plugin.
129  *
130  * It is used by WithParameter to store parameters.
131  * 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.
132  **/
133 struct TLP_SCOPE ParameterDescriptionList {
134 
136 
137  /**
138  * @brief Adds a new parameter of type T to the list.
139  *
140  * @param parameterName The name of the parameter.
141  * @param help The help string of this parameter. Defaults to std::string().
142  * @param defaultValue The default value of this parameter. Defaults to std::string().
143  * @param isMandatory Whether this parameter is mandatory or optional. Defaults to true.
144  * @param direction The parameter's direction (see tlp::ParameterDirection for details)
145  * @return void
146  **/
147  template<typename T> void add(const std::string& parameterName,
148  const std::string& help,
149  const std::string& defaultValue,
150  bool isMandatory = true,
151  ParameterDirection direction = IN_PARAM) {
152  for (unsigned int i = 0; i < parameters.size(); ++i) {
153  if (parameters[i].getName() == parameterName) {
154 #ifndef NDEBUG
155  tlp::warning() << "ParameterDescriptionList::addVar " << parameterName << " already exists" << std::endl;
156 #endif
157  return;
158  }
159  }
160 
161  ParameterDescription newParameter(parameterName,
162  typeid(T).name(),
163  help,
164  defaultValue,
165  isMandatory, direction);
166  parameters.push_back(newParameter);
167  }
168 
169  /**
170  * @brief Retrieves an Iterator on the parameters.
171  *
172  * @return An iterator over the parameters :Iterator<ParameterDescription>*
173  **/
174  tlp::Iterator<ParameterDescription>* getParameters() const;
175 
176  /**
177  * @brief retrieves the default value of a parameter.
178  *
179  * @param parameterName The name of the parameter to retrieve the default value of.
180  * @return The default value of the parameter:string
181  **/
182  const std::string& getDefaultValue(const std::string& parameterName) const;
183 
184  /**
185  * @brief Sets the default value of a parameter.
186  *
187  * @param parameterName The name of the parameter to set the value of.
188  * @param value The new value for this parameter.
189  * @return void
190  **/
191  void setDefaultValue(const std::string& parameterName,
192  const std::string& value);
193 
194  /**
195  * @brief Retrieves whether a parameter is mandatory or optional.
196  *
197  * @param parameterName The name of the parameter for which to check if it is mandatory or optional.
198  * @return bool true if the parameter is mandatory, false if it is optional.
199  **/
200  bool isMandatory(const std::string& parameterName) const;
201 
202  /**
203  * @brief Builds a DataSet containing the default values for each parameter.
204  * If the DataSet has a key which is equal to a parameter's name, the existing value is kept.
205  *
206  * @param ioDataSet The input dataset on which the parameters names will be associated with their default values.
207  * @param inG A graph on which to create properties if any parameter is of a property type. Defaults to 0.
208  * @return void
209  **/
210  void buildDefaultDataSet(DataSet& ioDataSet, Graph* inG = NULL) const;
211 
212  unsigned int size() const {
213  return parameters.size();
214  }
215 private:
216  ParameterDescription* getParameter(const std::string& parameterName);
217  std::vector<ParameterDescription> parameters;
218 };
219 
220 
221 #define HTML_HELP_OPEN() "<!DOCTYPE html><html><head>\
222 <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; }\
223  .paramtable { width: 100%; border: 0px; border-bottom: 1px solid #C9C9C9; padding: 5px; }\
224  .help { font-style: italic; font-size: 90%; }</style>\
225 </head><body><table border=\"0\" class=\"paramtable\">"
226 
227 #define HTML_HELP_DEF(A,B) "<tr><td><b>" A "</b><td>" B "</td></tr>"
228 
229 #define HTML_HELP_BODY() "</table><p class=\"help\">"
230 
231 #define HTML_HELP_CLOSE() "</p></body></html>"
232 
233 /**
234  * @ingroup Plugins
235  * @brief This class describes parameters on a plug-in.
236  *
237  * 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.
238  * 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.
239  **/
240 struct TLP_SCOPE WithParameter {
241 
242  /**
243  * @brief Retrieves the parameters.
244  *
245  * @return :ParameterDescriptionList the parameters of the plug-in.
246  **/
247  const tlp::ParameterDescriptionList& getParameters() const;
248 
249  /**
250  * @brief Adds an IN parameter to the plug-in.
251  *
252  * @param name The name of the parameter to add.
253  * @param help A description of the parameter, that will be displayed to the user. Defaults to "".
254  * @param defaultValue The default value the parameter should take, to be the initial value in the GUI. Defaults to "".
255  * @param isMandatory Whether this parameter requires a value or not. Defaults to true.
256  * @return void
257  **/
258  template<typename T>
259  void addInParameter(const std::string &name,
260  const std::string &help,
261  const std::string &defaultValue,
262  bool isMandatory = true) {
263  parameters.template add<T>(name, help, defaultValue, isMandatory, IN_PARAM);
264  }
265 
266  /**
267  * @brief Adds an OUT parameter to the plug-in.
268  *
269  * @param name The name of the parameter to add.
270  * @param help A description of the parameter, that will be displayed to the user. Defaults to "".
271  * @param defaultValue The default value the parameter should take, to be the initial value in the GUI. Defaults to "".
272  * @param isMandatory Whether this parameter requires a value or not. Defaults to true.
273  * @return void
274  **/
275  template<typename T>
276  void addOutParameter(const std::string &name,
277  const std::string &help=std::string(),
278  const std::string &defaultValue = std::string(),
279  bool isMandatory = true) {
280  parameters.template add<T>(name, help, defaultValue, isMandatory, OUT_PARAM);
281  }
282 
283  /**
284  * @brief Adds an INOUT parameter to the plug-in.
285  *
286  * @param name The name of the parameter to add.
287  * @param help A description of the parameter, that will be displayed to the user. Defaults to "".
288  * @param defaultValue The default value the parameter should take, to be the initial value in the GUI. Defaults to "".
289  * @param isMandatory Whether this parameter requires a value or not. Defaults to true.
290  * @return void
291  **/
292  template<typename T>
293  void addInOutParameter(const std::string &name,
294  const std::string &help=std::string(),
295  const std::string &defaultValue = std::string(),
296  bool isMandatory = true) {
297  parameters.template add<T>(name, help, defaultValue, isMandatory, INOUT_PARAM);
298  }
299 
300  /**
301  * @brief Adds an IN parameter to the plug-in (deprecated)
302  *
303  * @see addInParameter()
304  * @see addOutParameter()
305  *
306  * @param name The name of the parameter to add.
307  * @param help A description of the parameter, that will de displayed to the user. Defaults to 0.
308  * @param defaultValue The default value the parameter should take, to be the initial value in the GUI. Defaults to 0.
309  * @param isMandatory Whether this parameter requires a value or not. Defaults to true.
310  * @return void
311  **/
312  template<typename T>
313  void _DEPRECATED addParameter(const std::string &name,
314  const std::string &help=std::string(),
315  const std::string &defaultValue = std::string(),
316  bool isMandatory = true) {
317  addInParameter<T>(name, help, defaultValue, isMandatory);
318  }
319 
320  /**
321  * @brief indicates whether the embedded parameters require some user input
322  *
323  * @return true if an input parameter or a property output parameter exists
324  **/
325  bool inputRequired() const;
326 
327 protected:
328 
329  /**
330  * @brief The internal structure storing the parameters.
331  **/
333 };
334 
335 
336 }
337 #endif