Tulip 5.7.1
Large graphs analysis and drawing
Loading...
Searching...
No Matches
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
31namespace tlp {
32
33class Graph;
34class DataSet;
35template <class itType>
36struct 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 */
48enum 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 **/
70class TLP_SCOPE ParameterDescription {
71private:
72 std::string name;
73 std::string type;
74 std::string help;
75 std::string defaultValue;
76 bool mandatory;
77 ParameterDirection direction;
78
79public:
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 **/
154struct 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
279private:
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 **/
298struct 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
381protected:
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