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