Tulip  6.0.0
Large graphs analysis and drawing
WithParameter.h
1 /*
2  *
3  * This file is part of Tulip (https://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 remove an existing parameter from the list.
193  *
194  * @param parameterName The name of the parameter.
195  * @return void
196  **/
197  void remove(const std::string &parameterName);
198 
199  /**
200  * @brief Retrieves an Iterator on the parameters.
201  *
202  * @return An iterator over the parameters :Iterator<ParameterDescription>*
203  **/
204  tlp::Iterator<ParameterDescription> *getParameters() const;
205 
206  /**
207  * @brief retrieves the default value of a parameter.
208  *
209  * @param parameterName The name of the parameter to retrieve the default value of.
210  * @return The default value of the parameter:string
211  **/
212  const std::string &getDefaultValue(const std::string &parameterName) const;
213 
214  /**
215  * @brief Sets the default value of a parameter.
216  *
217  * @param parameterName The name of the parameter to set the value of.
218  * @param value The new value for this parameter.
219  * @return void
220  **/
221  void setDefaultValue(const std::string &parameterName, const std::string &value);
222 
223  /**
224  * @brief retrieves the direction of a parameter.
225  *
226  * @param parameterName The name of the parameter to retrieve the direction of.
227  * @return The direction of the parameter
228  **/
229  ParameterDirection getDirection(const std::string &parameterName) const;
230 
231  /**
232  * @brief Sets the direction of a parameter.
233  *
234  * @param parameterName The name of the parameter to set the value of.
235  * @param dir The new direction for this parameter.
236  * @return void
237  **/
238  void setDirection(const std::string &parameterName, ParameterDirection direction);
239 
240  /**
241  * @brief Retrieves whether a parameter is mandatory or optional.
242  *
243  * @param parameterName The name of the parameter for which to check if it is mandatory or
244  *optional.
245  * @return bool true if the parameter is mandatory, false if it is optional.
246  **/
247  bool isMandatory(const std::string &parameterName) const;
248 
249  /**
250  * @brief Builds a DataSet containing the default values for each parameter.
251  * If the DataSet has a key which is equal to a parameter's name, the existing value is kept.
252  *
253  * @param ioDataSet The input dataset on which the parameters names will be associated with their
254  *default values.
255  * @param inG A graph on which to create properties if any parameter is of a property type.
256  *Defaults to 0.
257  * @return void
258  **/
259  void buildDefaultDataSet(DataSet &ioDataSet, Graph *inG = nullptr) const;
260 
261  /**
262  * @brief Returns the number of parameters.
263  *
264  * @return The number of parameters
265  **/
266  inline unsigned int size() const {
267  return parameters.size();
268  }
269 
270  /**
271  * @brief Test if the list is empty
272  *
273  * @return bool true if the parameter description list is empty, false otherwise.
274  **/
275  inline bool empty() const {
276  return parameters.empty();
277  }
278 
279 private:
280  ParameterDescription *getParameter(const std::string &parameterName);
281  std::string generateParameterHTMLDocumentation(const std::string &name, const std::string &help,
282  const std::string &type,
283  const std::string &defaultValue,
284  const std::string &valuesDescription,
285  const ParameterDirection &direction);
286  std::vector<ParameterDescription> parameters;
287 };
288 
289 /**
290  * @ingroup Plugins
291  * @brief This class describes parameters on a plug-in.
292  *
293  * These parameters can be of any type, and are used to generate a GUI that will be shown when the
294  *plug-in in invoked by the user.
295  * It is mainly used by algorithms to display options to the user, e.g. a clustering algorithm can
296  *let the user choose which measure to use.
297  **/
298 struct TLP_SCOPE WithParameter {
299 
300  /**
301  * @brief Retrieves the parameters.
302  *
303  * @return :ParameterDescriptionList the parameters of the plug-in.
304  **/
305  const tlp::ParameterDescriptionList &getParameters() const;
306 
307  /**
308  * @brief Adds an IN parameter to the plug-in.
309  *
310  * @param name The name of the parameter to add. Three name prefixes have special meanings:
311  *'anyfile::' means that the parameter identifies a file, 'file::' means that the parameter
312  *identifies an already existing file, 'dir::' means that the parameter identifies an alreay
313  *existing directory.
314  * @param help A description of the parameter, that will be displayed to the user. Defaults to "".
315  * @param defaultValue The default value the parameter should take, to be the initial value in the
316  *GUI. Defaults to "".
317  * @param isMandatory Whether this parameter requires a value or not. Defaults to true.
318  * @param valuesDescription A description of the values the parameter can take (usually for
319  *detailing the content of a StringCollection). Defaults to "".
320  * @return void
321  **/
322  template <typename T>
323  void addInParameter(const std::string &name, const std::string &help,
324  const std::string &defaultValue, bool isMandatory = true,
325  const std::string &valuesDescription = std::string()) {
326  parameters.template add<T>(name, help, defaultValue, isMandatory, IN_PARAM, valuesDescription);
327  }
328 
329  /**
330  * @brief Adds an OUT parameter to the plug-in.
331  *
332  * @param name The name of the parameter to add. Three name prefixes have special meanings:
333  *'anyfile::' means that the parameter identifies a file, 'file::' means that the parameter
334  *identifies an already existing file, 'dir::' means that the parameter identifies an alreay
335  *existing directory.
336  * @param help A description of the parameter, that will be displayed to the user. Defaults to "".
337  * @param defaultValue The default value the parameter should take, to be the initial value in the
338  *GUI. Defaults to "".
339  * @param isMandatory Whether this parameter requires a value or not. Defaults to true.
340  * @param valuesDescription A description of the values the parameter can take (usually for
341  *detailing the content of a StringCollection). Defaults to "".
342  * @return void
343  **/
344  template <typename T>
345  void addOutParameter(const std::string &name, const std::string &help = std::string(),
346  const std::string &defaultValue = std::string(), bool isMandatory = true,
347  const std::string &valuesDescription = std::string()) {
348  parameters.template add<T>(name, help, defaultValue, isMandatory, OUT_PARAM, valuesDescription);
349  }
350 
351  /**
352  * @brief Adds an INOUT parameter to the plug-in.
353  *
354  * @param name The name of the parameter to add. Three name prefixes have special meaning:
355  *'anyfile::' means that the parameter identifies a file, 'file::' means that the parameter
356  *identifies an already existing file, 'dir::' means taht the parameter identifies an alreay
357  *existing directory.
358  * @param help A description of the parameter, that will be displayed to the user. Defaults to "".
359  * @param defaultValue The default value the parameter should take, to be the initial value in the
360  *GUI. Defaults to "".
361  * @param isMandatory Whether this parameter requires a value or not. Defaults to true.
362  * @param valuesDescription A description of the values the parameter can take (usually for
363  *detailing the content of a StringCollection). Defaults to "".
364  * @return void
365  **/
366  template <typename T>
367  void addInOutParameter(const std::string &name, const std::string &help = std::string(),
368  const std::string &defaultValue = std::string(), bool isMandatory = true,
369  const std::string &valuesDescription = std::string()) {
370  parameters.template add<T>(name, help, defaultValue, isMandatory, INOUT_PARAM,
371  valuesDescription);
372  }
373 
374  /**
375  * @brief indicates whether the embedded parameters require some user input
376  *
377  * @return true if an input parameter or a property output parameter exists
378  **/
379  bool inputRequired() const;
380 
381 protected:
382  /**
383  * @brief The internal structure storing the parameters.
384  **/
385  ParameterDescriptionList parameters;
386  /**
387  * @brief remove an existing parameter
388  **/
389  void removeParameter(const std::string &name) {
390  parameters.remove(name);
391  }
392 };
393 } // namespace tlp
394 #endif
395 
396 ///@endcond
Interface for Tulip iterators. Allows basic iteration operations only.
Definition: Iterator.h:74