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