Tulip
4.6.0
Better Visualization Through Research
|
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