Tulip  4.1.0
Better Visualization Through Research
 All Classes Files Functions Variables Enumerations Enumerator Properties Groups Pages
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 1 and Inria Bordeaux - Sud Ouest
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 = QObject::trUtf8("Algorithm").toStdString();
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