Tulip  4.3.0
Better Visualization Through Research
 All Classes Namespaces Files Functions Variables Enumerations Enumerator Properties Groups Pages
PluginProgress.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 TLP_PROGRESS
21 #define TLP_PROGRESS
22 
23 #include <tulip/tulipconf.h>
24 #include <string>
25 
26 namespace tlp {
27 
28 /**
29  * @ingroup Plugins
30  * @brief The ProgressPreviewHandler class handles the way a process handled by a PluginProgress is handled
31  *
32  * 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
33  * Once enabled, the progressStateChanged method will be called back each time PluginProgress::progress is called to allow synchronizing the preview with progression.
34  */
35 class TLP_SCOPE ProgressPreviewHandler {
36 public:
37  virtual ~ProgressPreviewHandler();
38 
39  /**
40  * @brief @brief Called back after PluginProgress::progress has been invoked.
41  */
42  virtual void progressStateChanged(int step,int max_step)=0;
43 };
44 
45 /**
46  * @ingroup Plugins
47  *
48  * @brief This enum describes callback actions for the underleying system when calling tlp::PluginProgress::progress();
49  * @list
50  * @li TLP_CONTINUE: tells that the process monitored by the the progress should continue.
51  * @li TLP_CANCEL: The process should be cancelled, reverting all changes since it was started.
52  * @li TLP_STOP: The process should stop, leaving all the changes made since the beginning
53  * @endlist
54  *
55  * @see tlp::PluginProgress
56  **/
58  /** The plugin should continue its execution. */
60  /** The plugin should cancel, reverting all performed changes since the plugin was called. */
62  /** The plugin should stop, leaving the graph in its current state. */
64 };
65 
66 /**
67  * @ingroup Plugins
68  * @brief PluginProcess subclasses are meant to notify about the progress state of some process (typically a plugin)
69  *
70  * PluginProgress are mainly used alongside with tlp::Plugin instances to give user a visual feedback about the progress of the plugin.
71  * 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.
72  * The tlp::PluginProgress returns a tlp::ProgressState indicating what behavior the underleying system should have (see tlp::ProgressState for details)
73  **/
74 class TLP_SCOPE PluginProgress {
75  ProgressPreviewHandler* _previewHandler;
76 
77 public:
79  virtual ~PluginProgress();
80  void setPreviewHandler(ProgressPreviewHandler*);
81 
82  /**
83  * @brief Notifies the progression of the process.
84  *
85  * @param step The current step number.
86  * @param max_step The total number of steps.
87  *
88  * * @warning For default previsualisation handling to work, be sure to call PluginProgress::progress in this method (the return value can be ignored)
89  *
90  * @return tlp::ProgressState a value indicating whether the progress has been stopped, cancelled, or will continue.
91  * @see tlp::ProgressState
92  **/
93  virtual ProgressState progress(int step, int max_step);
94 
95  /**
96  * @brief Sets the state flag to cancel, notifying to the process that the user wants to cancel it.
97  * Canceling a process must stop it and revert all the changes performed since its start.
98  *
99  * @return void
100  **/
101  virtual void cancel()=0;
102 
103  /**
104  * @brief Sets the state flag to stop, notifying to the process that the user wants to stop it.
105  * Stopping a process does not revert changes.
106  * @return void
107  **/
108  virtual void stop()=0;
109 
110  /**
111  * @brief The preview mode redraws the graph while applying the algorithm, making it slower.
112  *
113  * @return bool Whether the preview mode is activated.
114  **/
115  virtual bool isPreviewMode() const =0;
116 
117 
118  /**
119  * @brief The preview mode redraws the graph while applying the algorithm, making it slower.
120  *
121  * @param drawPreview Whether the preview should be drawn.
122  * @return void
123  **/
124  virtual void setPreviewMode(bool drawPreview)=0;
125 
126  /**
127  * @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.
128  *
129  * @param showPreview Whether the progress widget should contain a preview checkbox or not.
130  * @return void
131  **/
132  virtual void showPreview(bool showPreview)=0;
133 
134  /**
135  * @brief Gets the current internal state of the PluginProgress.
136  *
137  * @return tlp::ProgressState The current state.
138  **/
139  virtual ProgressState state() const=0;
140 
141  /**
142  * @brief Returns a message describing the error encountered during the process. If no error has been encountered, an empty string is returned.
143  *
144  * @return :string A description of the encountered error, if any.
145  **/
146  virtual std::string getError()=0;
147 
148  /**
149  * @brief Sets the message describing the error encountered during the process.
150  *
151  * @param error The description of the encountered error.
152  * @return void
153  **/
154  virtual void setError(const std::string& error)=0;
155 
156  /**
157  * @brief Changes the comment about the process progression.
158  *
159  * @param comment A description of what the plugin is currently doing, displayed to inform the user.
160  * @return void
161  **/
162  virtual void setComment(const std::string& comment)=0;
163 
164  /**
165  * @brief Changes the title of that plugin progress
166  *
167  * @param title the title to set
168  * @return void
169  **/
170  virtual void setTitle(const std::string& title)=0;
171 
172 
173 };
174 
175 }
176 #endif