Tulip  4.6.0
Better Visualization Through Research
library/tulip-core/include/tulip/PluginProgress.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 TLP_PROGRESS
00021 #define TLP_PROGRESS
00022 
00023 #include <tulip/tulipconf.h>
00024 #include <string>
00025 
00026 namespace tlp {
00027 
00028 /**
00029  * @ingroup Plugins
00030  * @brief The ProgressPreviewHandler class handles the way a process handled by a PluginProgress is handled
00031  *
00032  * When PluginProgress::setPreview() is called, the associated ProgressPreviewHandler will be enabled. Allowing it to implement custom behavior to allow the user to preview the result of the underleying process
00033  * Once enabled, the progressStateChanged method will be called back each time PluginProgress::progress is called to allow synchronizing the preview with progression.
00034  */
00035 class TLP_SCOPE ProgressPreviewHandler {
00036 public:
00037   virtual ~ProgressPreviewHandler();
00038 
00039   /**
00040    * @brief @brief Called back after PluginProgress::progress has been invoked.
00041    */
00042   virtual void progressStateChanged(int step,int max_step)=0;
00043 };
00044 
00045 /**
00046  * @ingroup Plugins
00047  *
00048  * @brief This enum describes callback actions for the underleying system when calling tlp::PluginProgress::progress();
00049  * @list
00050  * @li TLP_CONTINUE: tells that the process monitored by the the progress should continue.
00051  * @li TLP_CANCEL: The process should be cancelled, reverting all changes since it was started.
00052  * @li TLP_STOP: The process should stop, leaving all the changes made since the beginning
00053  * @endlist
00054  *
00055  * @see tlp::PluginProgress
00056  **/
00057 enum ProgressState {
00058   /** The plugin should continue its execution. */
00059   TLP_CONTINUE,
00060   /** The plugin should cancel, reverting all performed changes since the plugin was called. */
00061   TLP_CANCEL,
00062   /** The plugin should stop, leaving the graph in its current state. */
00063   TLP_STOP
00064 };
00065 
00066 /**
00067  * @ingroup Plugins
00068  * @brief PluginProcess subclasses are meant to notify about the progress state of some process (typically a plugin)
00069  *
00070  * PluginProgress are mainly used alongside with tlp::Plugin instances to give user a visual feedback about the progress of the plugin.
00071  * Every plugin in tulip got a pluginProgress member they can call to give progress feedbacks. When running, the plugin should make a call to tlp::PluginProgress::progress() indicating the current state of the compuation.
00072  * The tlp::PluginProgress returns a tlp::ProgressState indicating what behavior the underleying system should have (see tlp::ProgressState for details)
00073  **/
00074 class TLP_SCOPE PluginProgress {
00075   ProgressPreviewHandler* _previewHandler;
00076 
00077 public:
00078   PluginProgress();
00079   virtual ~PluginProgress();
00080   void setPreviewHandler(ProgressPreviewHandler*);
00081 
00082   /**
00083    * @brief Notifies the progression of the process.
00084    *
00085    * @param step The current step number.
00086    * @param max_step The total number of steps.
00087    *
00088    * * @warning For default previsualisation handling to work, be sure to call PluginProgress::progress in this method (the return value can be ignored)
00089    *
00090    * @return tlp::ProgressState a value indicating whether the progress has been stopped, cancelled, or will continue.
00091    * @see tlp::ProgressState
00092    **/
00093   virtual ProgressState progress(int step, int max_step);
00094 
00095   /**
00096    * @brief Sets the state flag to cancel, notifying to the process that the user wants to cancel it.
00097    * Canceling a process must stop it and revert all the changes performed since its start.
00098    *
00099    * @return void
00100    **/
00101   virtual void cancel()=0;
00102 
00103   /**
00104   * @brief Sets the state flag to stop, notifying to the process that the user wants to stop it.
00105   * Stopping a process does not revert changes.
00106   * @return void
00107   **/
00108   virtual void stop()=0;
00109 
00110   /**
00111    * @brief The preview mode redraws the graph while applying the algorithm, making it slower.
00112    *
00113    * @return bool Whether the preview mode is activated.
00114    **/
00115   virtual bool isPreviewMode() const =0;
00116 
00117 
00118   /**
00119    * @brief The preview mode redraws the graph while applying the algorithm, making it slower.
00120    *
00121    * @param drawPreview Whether the preview should be drawn.
00122    * @return void
00123    **/
00124   virtual void setPreviewMode(bool drawPreview)=0;
00125 
00126   /**
00127    * @brief This tells the widget if it should show a preview checkbox, allowing the user to decide if the algorithm should draw a preview or not.
00128    *
00129    * @param showPreview Whether the progress widget should contain a preview checkbox or not.
00130    * @return void
00131    **/
00132   virtual void showPreview(bool showPreview)=0;
00133 
00134   /**
00135    * @brief Gets the current internal state of the PluginProgress.
00136    *
00137    * @return tlp::ProgressState The current state.
00138    **/
00139   virtual ProgressState state() const=0;
00140 
00141   /**
00142    * @brief Returns a message describing the error encountered during the process. If no error has been encountered, an empty string is returned.
00143    *
00144    * @return :string A description of the encountered error, if any.
00145    **/
00146   virtual std::string getError()=0;
00147 
00148   /**
00149    * @brief Sets the message describing the error encountered during the process.
00150    *
00151    * @param error The description of the encountered error.
00152    * @return void
00153    **/
00154   virtual void setError(const std::string& error)=0;
00155 
00156   /**
00157    * @brief Changes the comment about the process progression.
00158    *
00159    * @param comment A description of what the plugin is currently doing, displayed to inform the user.
00160    * @return void
00161    **/
00162   virtual void setComment(const std::string& comment)=0;
00163 
00164   /**
00165    * @brief Changes the title of that plugin progress
00166    *
00167    * @param title the title to set
00168    * @return void
00169    **/
00170   virtual void setTitle(const std::string& title)=0;
00171 
00172 
00173 };
00174 
00175 }
00176 #endif
 All Classes Files Functions Variables Enumerations Enumerator Properties