Tulip  4.1.0
Better Visualization Through Research
 All Classes 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 
26 #include <tulip/tulipconf.h>
27 
28 namespace tlp {
29 
30 class Graph;
31 class DataSet;
32 template<class itType >
33 struct Iterator;
34 
35 /**
36  * @ingroup Plugins
37  * @brief The ParameterDirection enum describes how a parameter is passed to a plugin
38  * The parameter can be seen as passing parameters to a C++ functions and works as follow:
39  * @list
40  * @li IN_PARAM: The parameter is passes by value
41  * @li OUT_PARAM: The parameter is a return value
42  * @li INOUT_PARAM: The parameter is passed by reference.
43  * @endlist
44  */
45 enum ParameterDirection { IN_PARAM=0, OUT_PARAM = 1, INOUT_PARAM = 2 };
46 
47 /**
48  * @ingroup Plugins
49  * @brief Describes a plugin's parameter.
50  *
51  * A plugin parameter consists of the following informations:
52  * @list
53  * @li A name (std::string) which can be used to retrieve the value of the parameter when running the plugin.
54  * @li A type (std::string) which is the C++ typename of the parameter.
55  * @li A help string (std::string) which gives additional information about the parameter and its possible values.
56  * @li A default value which is mapped on the parameter if no value has been entered by the user.
57  * @li The mandatory flag (bool) which tells if the parameter is optional or not.
58  * @li A ParameterDirection (enum).
59  * @endlist
60  *
61  * @see tlp::ParameterDirection
62  * @see tlp::ParameterDescriptionList
63  * @see tlp::WithParameter
64  **/
65 class TLP_SCOPE ParameterDescription {
66 private:
67  std::string name;
68  std::string type;
69  std::string help;
70  std::string defaultValue;
71  bool mandatory;
72  ParameterDirection direction;
73 public:
75  ParameterDescription(const std::string& name, const std::string& type,
76  const std::string& help, const std::string& defaultValue,
77  bool mandatory, ParameterDirection direction)
78  : name(name), type(type), help(help),
79  defaultValue(defaultValue), mandatory(mandatory), direction(direction) {
80  }
81  /**
82  * @return The parameter's name
83  */
84  const std::string& getName() const {
85  return name;
86  }
87  /**
88  * @return The parameter's C++ type name
89  */
90  const std::string& getTypeName() const {
91  return type;
92  }
93  /**
94  * @return The parameter's help string
95  */
96  const std::string& getHelp() const {
97  return help;
98  }
99  /**
100  * @return The parameter's default value.
101  */
102  const std::string& getDefaultValue() const {
103  return defaultValue;
104  }
105  /**
106  * @brief Sets the parameter's default value.
107  */
108  void setDefaultValue(const std::string& defVal) {
109  defaultValue = defVal;
110  }
111  /**
112  * @return Whether the parameter is mandatory or not.
113  */
114  bool isMandatory() {
115  return mandatory;
116  }
117  /**
118  * @return The parameter's direction
119  */
121  return direction;
122  }
123 };
124 
125 /**
126  * @ingroup Plugins
127  * @brief This class describes parameters taken by a plugin.
128  *
129  * It is used by WithParameter to store parameters.
130  * 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.
131  **/
132 struct TLP_SCOPE ParameterDescriptionList {
133 
135 
136  /**
137  * @brief Adds a new parameter of type T to the list.
138  *
139  * @param parameterName The name of the parameter.
140  * @param help The help string of this parameter. Defaults to std::string().
141  * @param defaultValue The default value of this parameter. Defaults to std::string().
142  * @param isMandatory Whether this parameter is mandatory or optional. Defaults to true.
143  * @param direction The parameter's direction (see tlp::ParameterDirection for details)
144  * @return void
145  **/
146  template<typename T> void add(const std::string& parameterName,
147  const std::string& help,
148  const std::string& defaultValue,
149  bool isMandatory = true,
150  ParameterDirection direction = IN_PARAM) {
151  for (unsigned int i = 0; i < parameters.size(); ++i) {
152  if (parameters[i].getName() == parameterName) {
153 #ifndef NDEBUG
154  qWarning() << "ParameterDescriptionList::addVar " << parameterName << " already exists";
155 #endif
156  return;
157  }
158  }
159 
160  ParameterDescription newParameter(parameterName,
161  typeid(T).name(),
162  help,
163  defaultValue,
164  isMandatory, direction);
165  parameters.push_back(newParameter);
166  }
167 
168  /**
169  * @brief Retrieves an Iterator on the parameters.
170  *
171  * @return An iterator over the parameters :Iterator<ParameterDescription>*
172  **/
173  tlp::Iterator<ParameterDescription>* getParameters() const;
174 
175  /**
176  * @brief retrieves the default value of a parameter.
177  *
178  * @param parameterName The name of the parameter to retrieve the default value of.
179  * @return The default value of the parameter:string
180  **/
181  const std::string& getDefaultValue(const std::string& parameterName) const;
182 
183  /**
184  * @brief Sets the default value of a parameter.
185  *
186  * @param parameterName The name of the parameter to set the value of.
187  * @param value The new value for this parameter.
188  * @return void
189  **/
190  void setDefaultValue(const std::string& parameterName,
191  const std::string& value);
192 
193  /**
194  * @brief Retrieves whether a parameter is mandatory or optional.
195  *
196  * @param parameterName The name of the parameter for which to check if it is mandatory or optional.
197  * @return bool true if the parameter is mandatory, false if it is optional.
198  **/
199  bool isMandatory(const std::string& parameterName) const;
200 
201  /**
202  * @brief Builds a DataSet containing the default values for each parameter.
203  * If the DataSet has a key which is equal to a parameter's name, the existing value is kept.
204  *
205  * @param ioDataSet The input dataset on which the parameters names will be associated with their default values.
206  * @param inG A graph on which to create properties if any parameter is of a property type. Defaults to 0.
207  * @return void
208  **/
209  void buildDefaultDataSet(DataSet& ioDataSet, Graph* inG = NULL) const;
210 
211  unsigned int size() const {
212  return parameters.size();
213  }
214 private:
215  ParameterDescription* getParameter(const std::string& parameterName);
216  template<typename TYPEINTERFACE>
217  void insertData(tlp::DataSet &,const std::string &param,const std::string &defaultValue) const;
218  std::vector<ParameterDescription> parameters;
219 };
220 
221 
222 #define HTML_HELP_OPEN() "<!DOCTYPE html><html><head>\
223 <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; }\
224  .paramtable { width: 100%; border: 0px; border-bottom: 1px solid #C9C9C9; padding: 5px; }\
225  .help { font-style: italic; font-size: 90%; }</style>\
226 </head><body><table border=\"0\" class=\"paramtable\">"
227 
228 #define HTML_HELP_DEF(A,B) "<tr><td><b>"A"</b><td>"B"</td></tr>"
229 
230 #define HTML_HELP_BODY() "</table><p class=\"help\">"
231 
232 #define HTML_HELP_CLOSE() "</p></body></html>"
233 
234 /**
235  * @ingroup Plugins
236  * @brief This class describes parameters on a plug-in.
237  *
238  * 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.
239  * 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.
240  **/
241 struct TLP_SCOPE WithParameter {
242 
243  /**
244  * @brief Retrieves the parameters.
245  *
246  * @return :ParameterDescriptionList the parameters of the plug-in.
247  **/
248  const tlp::ParameterDescriptionList& getParameters() const;
249 
250  /**
251  * @brief Adds an IN parameter to the plug-in.
252  *
253  * @param name The name of the parameter to add.
254  * @param help A description of the parameter, that will be displayed to the user. Defaults to "".
255  * @param defaultValue The default value the parameter should take, to be the initial value in the GUI. Defaults to "".
256  * @param isMandatory Whether this parameter requires a value or not. Defaults to true.
257  * @return void
258  **/
259  template<typename T>
260  void addInParameter(const std::string &name,
261  const std::string &help,
262  const std::string &defaultValue,
263  bool isMandatory = true) {
264  parameters.template add<T>(name, help, defaultValue, isMandatory, IN_PARAM);
265  }
266 
267  /**
268  * @brief Adds an OUT parameter to the plug-in.
269  *
270  * @param name The name of the parameter to add.
271  * @param help A description of the parameter, that will be displayed to the user. Defaults to "".
272  * @param defaultValue The default value the parameter should take, to be the initial value in the GUI. Defaults to "".
273  * @param isMandatory Whether this parameter requires a value or not. Defaults to true.
274  * @return void
275  **/
276  template<typename T>
277  void addOutParameter(const std::string &name,
278  const std::string &help=std::string(),
279  const std::string &defaultValue = std::string(),
280  bool isMandatory = true) {
281  parameters.template add<T>(name, help, defaultValue, isMandatory, OUT_PARAM);
282  }
283 
284  /**
285  * @brief Adds an INOUT parameter to the plug-in.
286  *
287  * @param name The name of the parameter to add.
288  * @param help A description of the parameter, that will be displayed to the user. Defaults to "".
289  * @param defaultValue The default value the parameter should take, to be the initial value in the GUI. Defaults to "".
290  * @param isMandatory Whether this parameter requires a value or not. Defaults to true.
291  * @return void
292  **/
293  template<typename T>
294  void addInOutParameter(const std::string &name,
295  const std::string &help=std::string(),
296  const std::string &defaultValue = std::string(),
297  bool isMandatory = true) {
298  parameters.template add<T>(name, help, defaultValue, isMandatory, INOUT_PARAM);
299  }
300 
301  /**
302  * @brief Adds an IN parameter to the plug-in (deprecated)
303  *
304  * @see addInParameter()
305  * @see addOutParameter()
306  *
307  * @param name The name of the parameter to add.
308  * @param help A description of the parameter, that will de displayed to the user. Defaults to 0.
309  * @param defaultValue The default value the parameter should take, to be the initial value in the GUI. Defaults to 0.
310  * @param isMandatory Whether this parameter requires a value or not. Defaults to true.
311  * @return void
312  **/
313  template<typename T>
314  void _DEPRECATED addParameter(const std::string &name,
315  const std::string &help=std::string(),
316  const std::string &defaultValue = std::string(),
317  bool isMandatory = true) {
318  addInParameter<T>(name, help, defaultValue, isMandatory);
319  }
320 protected:
321 
322  /**
323  * @brief The internal structure storing the parameters.
324  **/
326 };
327 
328 
329 }
330 #endif