Tulip  4.6.0
Better Visualization Through Research
library/tulip-core/include/tulip/Algorithm.h
00001 /*
00002  *
00003  * This file is part of Tulip (www.tulip-software.org)
00004  *
00005  * Authors: David Auber and the Tulip development Team
00006  * from LaBRI, University of Bordeaux
00007  *
00008  * Tulip is free software; you can redistribute it and/or modify
00009  * it under the terms of the GNU Lesser General Public License
00010  * as published by the Free Software Foundation, either version 3
00011  * of the License, or (at your option) any later version.
00012  *
00013  * Tulip is distributed in the hope that it will be useful,
00014  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00015  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
00016  * See the GNU General Public License for more details.
00017  *
00018  */
00019 
00020 #ifndef _ALGORITHM_H
00021 #define _ALGORITHM_H
00022 
00023 #include <list>
00024 #include <string>
00025 #include <tulip/Plugin.h>
00026 #include <tulip/PluginContext.h>
00027 
00028 namespace tlp {
00029 
00030 static const std::string ALGORITHM_CATEGORY = "Algorithm";
00031 
00032 class PluginProgress;
00033 class Graph;
00034 class DataSet;
00035 
00036 
00037 /**
00038  * @ingroup Plugins
00039  * @brief This abstract class describes a basic algorithm plugin.
00040  *
00041  * It inherits on WithParameter and WithDependency for convenience.
00042  * 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.
00043  * 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, ...).
00044  */
00045 class Algorithm : public tlp::Plugin {
00046 public :
00047   /**
00048    * @brief Constructs an algorithm and initializes members from the AlgorithmContext.
00049    *
00050    * @param context The context this algorithm runs in, containing the graph, a DataSet for the parameters, and a PluginProgress
00051    * to give feedback to the user about the tasks the algorithm is performing.
00052    */
00053   Algorithm (const PluginContext* context) : graph(NULL),pluginProgress(NULL),dataSet(NULL) {
00054     if(context != NULL) {
00055       const AlgorithmContext* algorithmContext = dynamic_cast<const AlgorithmContext*>(context);
00056       assert(algorithmContext != NULL);
00057       graph = algorithmContext->graph;
00058       pluginProgress = algorithmContext->pluginProgress;
00059       dataSet = algorithmContext->dataSet;
00060     }
00061   }
00062   virtual ~Algorithm() {}
00063 
00064   std::string icon() const {
00065     return ":/tulip/gui/icons/32/plugin_algorithm.png";
00066   }
00067   /**
00068    * @brief Runs the algorithm.
00069    * It is a good practice to report progress through the PluginProgress, Even if your algorithm is very fast.
00070    * Keep in mind that Tulip can handle very large graphs.
00071    * The PluginProgress should also be used to report errors, if any.
00072    *
00073    * @return bool Whether the algorithm execution was successful or not.
00074    **/
00075   virtual bool run() = 0;
00076 
00077   virtual std::string category() const {
00078     return ALGORITHM_CATEGORY;
00079   }
00080   /**
00081    * @brief Checks whether the algorithm can be applied on this graph or not.
00082    * If not, the reason why should be reported through the PluginProgress.
00083    *
00084    * @param errorMessage A string whose value will be modified to an error message, if the check fails.
00085    * @return bool Whether the plug-in can run on this Graph.
00086    **/
00087   virtual bool check(std::string &) {
00088     return true;
00089   }
00090   /**
00091    * @brief The graph this algorithm will be run on. Retrieved from the context at construction.
00092    */
00093   Graph *graph;
00094   /**
00095    * @brief A PluginProgress to give feedback to the user, retrieved from the context. It can be a NULL pointer, so use with caution.
00096    */
00097   PluginProgress *pluginProgress;
00098   /**
00099    * @brief A DataSet containing parameters for this algorithm, if any. Retrieved from the context at construction.
00100    */
00101   DataSet *dataSet;
00102 };
00103 
00104 }
00105 #endif
 All Classes Files Functions Variables Enumerations Enumerator Properties