Tulip  5.2.0
Large graphs analysis and drawing
WithParameter.h
1 /*
2  *
3  * This file is part of Tulip (http://tulip.labri.fr)
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
55  *the plugin.
56  * @li A type (std::string) which is the C++ typename of the parameter.
57  * @li A help string (std::string) which gives additional information about the parameter and its
58  *possible values.
59  * @li A default value which is mapped on the parameter if no value has been entered by the user.
60  * @li The mandatory flag (bool) which tells if the parameter is optional or not.
61  * @li A ParameterDirection (enum).
62  * @endlist
63  *
64  * @see tlp::ParameterDirection
65  * @see tlp::ParameterDescriptionList
66  * @see tlp::WithParameter
67  **/
68 class TLP_SCOPE ParameterDescription {
69 private:
70  std::string name;
71  std::string type;
72  std::string help;
73  std::string defaultValue;
74  bool mandatory;
75  ParameterDirection direction;
76 
77 public:
79  ParameterDescription(const std::string &name, const std::string &type, const std::string &help,
80  const std::string &defaultValue, bool mandatory,
81  ParameterDirection direction)
82  : name(name), type(type), help(help), defaultValue(defaultValue), mandatory(mandatory),
83  direction(direction) {}
84 
85  /**
86  * @return The parameter's name
87  */
88  const std::string &getName() const {
89  return name;
90  }
91  /**
92  * @return The parameter's C++ type name
93  */
94  const std::string &getTypeName() const {
95  return type;
96  }
97  /**
98  * @return The parameter's help string
99  */
100  const std::string &getHelp() const {
101  return help;
102  }
103  /**
104  * @return The parameter's default value.
105  */
106  const std::string &getDefaultValue() const {
107  return defaultValue;
108  }
109  /**
110  * @brief Set the parameter's default value.
111  */
112  void setDefaultValue(const std::string &defVal) {
113  defaultValue = defVal;
114  }
115  /**
116  * @return Whether the parameter is mandatory or not.
117  */
118  bool isMandatory() const {
119  return mandatory;
120  }
121  /**
122  * @return The parameter's direction
123  */
125  return direction;
126  }
127  /**
128  * @return Set the parameter's direction
129  */
131  direction = dir;
132  }
133  /**
134  * @return Whether the parameter is editable or not.
135  */
136  bool isEditable() const {
137  // input parameters are editable
138  return (direction != OUT_PARAM) ||
139  // only property output parameters are editable
140  (type.find("Property") != std::string::npos);
141  }
142 };
143 
144 /**
145  * @ingroup Plugins
146  * @brief This class describes parameters taken by a plugin.
147  *
148  * It is used by WithParameter to store parameters.
149  * Each parameter is identified by a name, has a default value, a value, a help string, and a
150  *boolean indicating whether it is mandatory or optional.
151  **/
152 struct TLP_SCOPE ParameterDescriptionList {
153 
155 
156  /**
157  * @brief Adds a new parameter of type T to the list.
158  *
159  * @param parameterName The name of the parameter.
160  * @param help The help string of this parameter. Defaults to std::string().
161  * @param defaultValue The default value of this parameter. Defaults to std::string().
162  * @param isMandatory Whether this parameter is mandatory or optional. Defaults to true.
163  * @param direction The parameter's direction (see tlp::ParameterDirection for details)
164  * @return void
165  **/
166  template <typename T>
167  void add(const std::string &parameterName, const std::string &help,
168  const std::string &defaultValue, bool isMandatory = true,
169  ParameterDirection direction = IN_PARAM,
170  const std::string &valuesDescription = std::string()) {
171  for (unsigned int i = 0; i < parameters.size(); ++i) {
172  if (parameters[i].getName() == parameterName) {
173 #ifndef NDEBUG
174  tlp::warning() << "ParameterDescriptionList::add " << parameterName << " already exists"
175  << std::endl;
176 #endif
177  return;
178  }
179  }
180 
181  ParameterDescription newParameter(
182  parameterName, typeid(T).name(),
183  generateParameterHTMLDocumentation(parameterName, help, typeid(T).name(), defaultValue,
184  valuesDescription, direction),
185  defaultValue, isMandatory, direction);
186  parameters.push_back(newParameter);
187  }
188 
189  /**
190  * @brief Retrieves an Iterator on the parameters.
191  *
192  * @return An iterator over the parameters :Iterator<ParameterDescription>*
193  **/
194  tlp::Iterator<ParameterDescription> *getParameters() const;
195 
196  /**
197  * @brief retrieves the default value of a parameter.
198  *
199  * @param parameterName The name of the parameter to retrieve the default value of.
200  * @return The default value of the parameter:string
201  **/
202  const std::string &getDefaultValue(const std::string &parameterName) const;
203 
204  /**
205  * @brief Sets the default value of a parameter.
206  *
207  * @param parameterName The name of the parameter to set the value of.
208  * @param value The new value for this parameter.
209  * @return void
210  **/
211  void setDefaultValue(const std::string &parameterName, const std::string &value);
212 
213  /**
214  * @brief Sets the direction of a parameter.
215  *
216  * @param parameterName The name of the parameter to set the value of.
217  * @param dir The new direction for this parameter.
218  * @return void
219  **/
220  void setDirection(const std::string &parameterName, ParameterDirection direction);
221 
222  /**
223  * @brief Retrieves whether a parameter is mandatory or optional.
224  *
225  * @param parameterName The name of the parameter for which to check if it is mandatory or
226  *optional.
227  * @return bool true if the parameter is mandatory, false if it is optional.
228  **/
229  bool isMandatory(const std::string &parameterName) const;
230 
231  /**
232  * @brief Builds a DataSet containing the default values for each parameter.
233  * If the DataSet has a key which is equal to a parameter's name, the existing value is kept.
234  *
235  * @param ioDataSet The input dataset on which the parameters names will be associated with their
236  *default values.
237  * @param inG A graph on which to create properties if any parameter is of a property type.
238  *Defaults to 0.
239  * @return void
240  **/
241  void buildDefaultDataSet(DataSet &ioDataSet, Graph *inG = nullptr) const;
242 
243  /**
244  * @brief Returns the number of parameters.
245  *
246  * @return The number of parameters
247  **/
248  inline unsigned int size() const {
249  return parameters.size();
250  }
251 
252  /**
253  * @brief Test if the list is empty
254  *
255  * @return bool true if the parameter description list is empty, false otherwise.
256  **/
257  inline bool empty() const {
258  return parameters.empty();
259  }
260 
261 private:
262  ParameterDescription *getParameter(const std::string &parameterName);
263  std::string generateParameterHTMLDocumentation(const std::string &name, const std::string &help,
264  const std::string &type,
265  const std::string &defaultValue,
266  const std::string &valuesDescription,
267  const ParameterDirection &direction);
268  std::vector<ParameterDescription> parameters;
269 };
270 
271 #define HTML_HELP_OPEN() \
272  "<!DOCTYPE html><html><head>\
273 <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; }\
274  .paramtable { width: 100%; border: 0px; border-bottom: 1px solid #C9C9C9; padding: 5px; }\
275  .help { font-style: italic; font-size: 90%; }\
276  .b { padding-left: 5px; }</style>\
277 </head><body><table border=\"0\" class=\"paramtable\">"
278 
279 #define HTML_HELP_DEF(A, B) "<tr><td><b>" A "</b><td class=\"b\">" B "</td></tr>"
280 
281 #define HTML_HELP_BODY() "</table><p class=\"help\">"
282 
283 #define HTML_HELP_CLOSE() "</p></body></html>"
284 
285 /**
286  * @ingroup Plugins
287  * @brief This class describes parameters on a plug-in.
288  *
289  * These parameters can be of any type, and are used to generate a GUI that will be shown when the
290  *plug-in in invoked by the user.
291  * It is mainly used by algorithms to display options to the user, e.g. a clustering algorithm can
292  *let the user choose which measure to use.
293  **/
294 struct TLP_SCOPE WithParameter {
295 
296  /**
297  * @brief Retrieves the parameters.
298  *
299  * @return :ParameterDescriptionList the parameters of the plug-in.
300  **/
301  const tlp::ParameterDescriptionList &getParameters() const;
302 
303  /**
304  * @brief Adds an IN parameter to the plug-in.
305  *
306  * @param name The name of the parameter to add.
307  * @param help A description of the parameter, that will be displayed to the user. Defaults to "".
308  * @param defaultValue The default value the parameter should take, to be the initial value in the
309  *GUI. Defaults to "".
310  * @param isMandatory Whether this parameter requires a value or not. Defaults to true.
311  * @param valuesDescription A description of the values the parameter can take (usually for
312  *detailing the content of a StringCollection). Defaults to "".
313  * @return void
314  **/
315  template <typename T>
316  void addInParameter(const std::string &name, const std::string &help,
317  const std::string &defaultValue, bool isMandatory = true,
318  const std::string &valuesDescription = std::string()) {
319  parameters.template add<T>(name, help, defaultValue, isMandatory, IN_PARAM, valuesDescription);
320  }
321 
322  /**
323  * @brief Adds an OUT parameter to the plug-in.
324  *
325  * @param name The name of the parameter to add.
326  * @param help A description of the parameter, that will be displayed to the user. Defaults to "".
327  * @param defaultValue The default value the parameter should take, to be the initial value in the
328  *GUI. Defaults to "".
329  * @param isMandatory Whether this parameter requires a value or not. Defaults to true.
330  * @param valuesDescription A description of the values the parameter can take (usually for
331  *detailing the content of a StringCollection). Defaults to "".
332  * @return void
333  **/
334  template <typename T>
335  void addOutParameter(const std::string &name, const std::string &help = std::string(),
336  const std::string &defaultValue = std::string(), bool isMandatory = true,
337  const std::string &valuesDescription = std::string()) {
338  parameters.template add<T>(name, help, defaultValue, isMandatory, OUT_PARAM, valuesDescription);
339  }
340 
341  /**
342  * @brief Adds an INOUT parameter to the plug-in.
343  *
344  * @param name The name of the parameter to add.
345  * @param help A description of the parameter, that will be displayed to the user. Defaults to "".
346  * @param defaultValue The default value the parameter should take, to be the initial value in the
347  *GUI. Defaults to "".
348  * @param isMandatory Whether this parameter requires a value or not. Defaults to true.
349  * @param valuesDescription A description of the values the parameter can take (usually for
350  *detailing the content of a StringCollection). Defaults to "".
351  * @return void
352  **/
353  template <typename T>
354  void addInOutParameter(const std::string &name, const std::string &help = std::string(),
355  const std::string &defaultValue = std::string(), bool isMandatory = true,
356  const std::string &valuesDescription = std::string()) {
357  parameters.template add<T>(name, help, defaultValue, isMandatory, INOUT_PARAM,
358  valuesDescription);
359  }
360 
361  /**
362  * @brief Adds an IN parameter to the plug-in (deprecated)
363  *
364  * @see addInParameter()
365  * @see addOutParameter()
366  *
367  * @param name The name of the parameter to add.
368  * @param help A description of the parameter, that will de displayed to the user. Defaults to 0.
369  * @param defaultValue The default value the parameter should take, to be the initial value in the
370  *GUI. Defaults to 0.
371  * @param isMandatory Whether this parameter requires a value or not. Defaults to true.
372  * @return void
373  **/
374  template <typename T>
375  _DEPRECATED void addParameter(const std::string &name, const std::string &help = std::string(),
376  const std::string &defaultValue = std::string(),
377  bool isMandatory = true) {
378  addInParameter<T>(name, help, defaultValue, isMandatory);
379  }
380 
381  /**
382  * @brief indicates whether the embedded parameters require some user input
383  *
384  * @return true if an input parameter or a property output parameter exists
385  **/
386  bool inputRequired() const;
387 
388  ///@cond DOXYGEN_HIDDEN
389 protected:
390  /**
391  * @brief The internal structure storing the parameters.
392  **/
393  ParameterDescriptionList parameters;
394  ///@endcond
395 };
396 }
397 #endif
const std::string & getName() const
Definition: WithParameter.h:88
bool empty() const
Test if the list is empty.
Interface for Tulip iterators. Allows basic iteration operations only.
Definition: Graph.h:41
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:189
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
const std::string & getTypeName() const
Definition: WithParameter.h:94
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:68
This class describes parameters on a plug-in.