Tulip  5.7.4
Large graphs analysis and drawing
Algorithm.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 #ifndef _ALGORITHM_H
21 #define _ALGORITHM_H
22 
23 #include <list>
24 #include <string>
25 #include <tulip/Plugin.h>
26 #include <tulip/PluginContext.h>
27 
28 namespace tlp {
29 
30 static const std::string ALGORITHM_CATEGORY = "Algorithm";
31 
32 class PluginProgress;
33 class Graph;
34 class DataSet;
35 
36 /**
37  * @ingroup Plugins
38  * @brief This abstract class describes a basic algorithm plugin.
39  *
40  * It inherits on WithParameter and WithDependency for convenience.
41  * Basic functionality consists in checking the algorithm can run on the current Graph (e.g. is the
42  * graph simple ?), running the algorithm and resetting the algorithm to re-apply it.
43  * The algorithm can and should report progress and which task it is performing if it is decomposed
44  * in multiple phases (e.g. layouting the graph, coloring it, ...).
45  */
46 class Algorithm : public tlp::Plugin {
47 public:
48  /**
49  * @brief Constructs an algorithm and initializes members from the AlgorithmContext.
50  *
51  * @param context The context this algorithm runs in, containing the graph, a DataSet for the
52  * parameters, and a PluginProgress
53  * to give feedback to the user about the tasks the algorithm is performing.
54  */
55  Algorithm(const PluginContext *context)
56  : graph(nullptr), pluginProgress(nullptr), dataSet(nullptr) {
57  if (context != nullptr) {
58  const AlgorithmContext *algorithmContext = static_cast<const AlgorithmContext *>(context);
59  graph = algorithmContext->graph;
60  pluginProgress = algorithmContext->pluginProgress;
61  dataSet = algorithmContext->dataSet;
62  }
63  }
64  ~Algorithm() override {}
65 
66  std::string icon() const override {
67  return ":/tulip/gui/icons/32/plugin_algorithm.png";
68  }
69  /**
70  * @brief Runs the algorithm.
71  * It is a good practice to report progress through the PluginProgress, Even if your algorithm is
72  *very fast.
73  * Keep in mind that Tulip can handle very large graphs.
74  * The PluginProgress should also be used to report errors, if any.
75  *
76  * @return bool Whether the algorithm execution was successful or not.
77  **/
78  virtual bool run() = 0;
79 
80  std::string category() const override {
81  return ALGORITHM_CATEGORY;
82  }
83  /**
84  * @brief Checks whether the algorithm can be applied on this graph or not.
85  * If not, the reason why should be reported through the PluginProgress.
86  *
87  * @param errorMessage A string whose value will be modified to an error message, if the check
88  *fails.
89  * @return bool Whether the plug-in can run on this Graph.
90  **/
91  virtual bool check(std::string &) {
92  return true;
93  }
94  /**
95  * @brief The graph this algorithm will be run on. Retrieved from the context at construction.
96  */
98  /**
99  * @brief A PluginProgress to give feedback to the user, retrieved from the context. It can be a
100  * nullptr pointer, so use with caution.
101  */
103  /**
104  * @brief A DataSet containing parameters for this algorithm, if any. Retrieved from the context
105  * at construction.
106  */
108 };
109 } // namespace tlp
110 #endif
Parameters structure for a tlp::Algorithm.
Definition: PluginContext.h:55
PluginProgress * pluginProgress
A progress handler to notify the user about the progress state of the algorithm when run.
Definition: PluginContext.h:74
DataSet * dataSet
Input parameters set by the user when running the plugin.
Definition: PluginContext.h:67
Graph * graph
The pointer to the tlp::Graph on which the algorithm will be run.
Definition: PluginContext.h:60
This abstract class describes a basic algorithm plugin.
Definition: Algorithm.h:46
Graph * graph
The graph this algorithm will be run on. Retrieved from the context at construction.
Definition: Algorithm.h:97
virtual bool check(std::string &)
Checks whether the algorithm can be applied on this graph or not. If not, the reason why should be re...
Definition: Algorithm.h:91
DataSet * dataSet
A DataSet containing parameters for this algorithm, if any. Retrieved from the context at constructio...
Definition: Algorithm.h:107
std::string category() const override
A string identifier for a plugin used for categorization purposes.
Definition: Algorithm.h:80
std::string icon() const override
The icon (preferably a thumbnail) of the plugin.
Definition: Algorithm.h:66
PluginProgress * pluginProgress
A PluginProgress to give feedback to the user, retrieved from the context. It can be a nullptr pointe...
Definition: Algorithm.h:102
Algorithm(const PluginContext *context)
Constructs an algorithm and initializes members from the AlgorithmContext.
Definition: Algorithm.h:55
virtual bool run()=0
Runs the algorithm. It is a good practice to report progress through the PluginProgress,...
A container that can store data from any type.
Definition: DataSet.h:195
Contains runtime parameters for a plugin.
Definition: PluginContext.h:42
Top-level interface for plug-ins.
Definition: Plugin.h:86
PluginProcess subclasses are meant to notify about the progress state of some process (typically a pl...