Tulip  5.7.4
Large graphs analysis and drawing
PluginProgress.h
1 /*
2  *
3  * This file is part of Tulip (https://tulip.labri.fr)
4  *
5  * Authors: David Auber and the Tulip development Team
6  * from LaBRI, University of Bordeaux
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
31  * handled
32  *
33  * When PluginProgress::setPreview() is called, the associated ProgressPreviewHandler will be
34  * enabled. Allowing it to implement custom behavior to allow the user to preview the result of the
35  * underlying process
36  * Once enabled, the progressStateChanged method will be called back each time
37  * PluginProgress::progress is called to allow synchronizing the preview with progression.
38  */
39 class TLP_SCOPE ProgressPreviewHandler {
40 public:
41  virtual ~ProgressPreviewHandler();
42 
43  /**
44  * @brief @brief Called back after PluginProgress::progress has been invoked.
45  */
46  virtual void progressStateChanged(int step, int max_step) = 0;
47 };
48 
49 /**
50  * @ingroup Plugins
51  *
52  * @brief This enum describes callback actions for the underlying system when calling
53  *tlp::PluginProgress::progress();
54  * @list
55  * @li TLP_CONTINUE: tells that the process monitored by the the progress should continue.
56  * @li TLP_CANCEL: The process should be cancelled, reverting all changes since it was started.
57  * @li TLP_STOP: The process should stop, leaving all the changes made since the beginning
58  * @endlist
59  *
60  * @see tlp::PluginProgress
61  **/
63  /** The plugin should continue its execution. */
65  /** The plugin should cancel, reverting all performed changes since the plugin was called. */
67  /** The plugin should stop, leaving the graph in its current state. */
68  TLP_STOP
69 };
70 
71 /**
72  * @ingroup Plugins
73  * @brief PluginProcess subclasses are meant to notify about the progress state of some process
74  *(typically a plugin)
75  *
76  * PluginProgress are mainly used alongside with tlp::Plugin instances to give user a visual
77  *feedback about the progress of the plugin. Every plugin in tulip got a pluginProgress member they
78  *can call to give progress feedbacks. When running, the plugin should make a call to
79  *tlp::PluginProgress::progress() indicating the current state of the computation. The
80  *tlp::PluginProgress returns a tlp::ProgressState indicating what behavior the underlying system
81  *should have (see tlp::ProgressState for details)
82  **/
83 class TLP_SCOPE PluginProgress {
84  ProgressPreviewHandler *_previewHandler;
85 
86 public:
88  virtual ~PluginProgress();
89  void setPreviewHandler(ProgressPreviewHandler *);
90 
91  /**
92  * @brief Notifies the progression of the process.
93  *
94  * @param step The current step number.
95  * @param max_step The total number of steps.
96  *
97  * @warning For default previsualisation handling to work, be sure to call
98  * PluginProgress::progress in this method (the return value can be ignored)
99  *
100  * @return tlp::ProgressState a value indicating whether the progress has been stopped, cancelled,
101  *or will continue.
102  * @see tlp::ProgressState
103  **/
104  virtual ProgressState progress(int step, int max_step);
105 
106  /**
107  * @brief Sets the state flag to cancel, notifying to the process that the user wants to cancel
108  *it. Canceling a process must stop it and revert all the changes performed since its start.
109  *
110  * @return void
111  **/
112  virtual void cancel() = 0;
113 
114  /**
115  * @brief Sets the state flag to stop, notifying to the process that the user wants to stop it.
116  * Stopping a process does not revert changes.
117  * @return void
118  **/
119  virtual void stop() = 0;
120 
121  /**
122  * @brief The preview mode redraws the graph while applying the algorithm, making it slower.
123  *
124  * @return bool Whether the preview mode is activated.
125  **/
126  virtual bool isPreviewMode() const = 0;
127 
128  /**
129  * @brief The preview mode redraws the graph while applying the algorithm, making it slower.
130  *
131  * @param drawPreview Whether the preview should be drawn.
132  * @return void
133  **/
134  virtual void setPreviewMode(bool drawPreview) = 0;
135 
136  /**
137  * @brief This tells the progress if it can allow the user to decide
138  * if the algorithm should draw a preview or not.
139  *
140  * @param showPreview Whether preview display can be managed or not
141  * @return void
142  **/
143  virtual void showPreview(bool showPreview) = 0;
144 
145  /**
146  * @brief This tells the progress if it can allow the user to decide
147  * to stop or cancel the plugin execution
148  *
149  * @param show Whether stop or cancellation can be managed or not
150  * @return void
151  **/
152  virtual void showStops(bool show) = 0;
153 
154  /**
155  * @brief This tells the progress if it has to show text indicating
156  * execution progression
157  *
158  * @param show Whether text has to be displayed or not
159  * @return void
160  **/
161  virtual void showText(bool /* show */) {}
162 
163  /**
164  * @brief Gets the current internal state of the PluginProgress.
165  *
166  * @return tlp::ProgressState The current state.
167  **/
168  virtual ProgressState state() const = 0;
169 
170  /**
171  * @brief Returns a message describing the error encountered during the process. If no error has
172  *been encountered, an empty string is returned.
173  *
174  * @return :string A description of the encountered error, if any.
175  **/
176  virtual std::string getError() = 0;
177 
178  /**
179  * @brief Sets the message describing the error encountered during the process.
180  *
181  * @param error The description of the encountered error.
182  * @return void
183  **/
184  virtual void setError(const std::string &error) = 0;
185 
186  /**
187  * @brief Changes the comment about the process progression.
188  *
189  * @param comment A description of what the plugin is currently doing, displayed to inform the
190  *user.
191  * @return void
192  **/
193  virtual void setComment(const std::string &comment) = 0;
194 
195  /**
196  * @brief Changes the title of that plugin progress
197  *
198  * @param title the title to set
199  * @return void
200  **/
201  virtual void setTitle(const std::string &title) = 0;
202 };
203 } // namespace tlp
204 #endif
PluginProcess subclasses are meant to notify about the progress state of some process (typically a pl...
virtual std::string getError()=0
Returns a message describing the error encountered during the process. If no error has been encounter...
virtual void showPreview(bool showPreview)=0
This tells the progress if it can allow the user to decide if the algorithm should draw a preview or ...
virtual void setPreviewMode(bool drawPreview)=0
The preview mode redraws the graph while applying the algorithm, making it slower.
virtual void showText(bool)
This tells the progress if it has to show text indicating execution progression.
virtual ProgressState progress(int step, int max_step)
Notifies the progression of the process.
virtual void setComment(const std::string &comment)=0
Changes the comment about the process progression.
virtual void setTitle(const std::string &title)=0
Changes the title of that plugin progress.
virtual void stop()=0
Sets the state flag to stop, notifying to the process that the user wants to stop it....
virtual ProgressState state() const =0
Gets the current internal state of the PluginProgress.
virtual void setError(const std::string &error)=0
Sets the message describing the error encountered during the process.
virtual bool isPreviewMode() const =0
The preview mode redraws the graph while applying the algorithm, making it slower.
virtual void cancel()=0
Sets the state flag to cancel, notifying to the process that the user wants to cancel it....
virtual void showStops(bool show)=0
This tells the progress if it can allow the user to decide to stop or cancel the plugin execution.
The ProgressPreviewHandler class handles the way a process handled by a PluginProgress is handled.
virtual void progressStateChanged(int step, int max_step)=0
Called back after PluginProgress::progress has been invoked.
ProgressState
This enum describes callback actions for the underlying system when calling tlp::PluginProgress::prog...
@ TLP_CONTINUE
@ TLP_CANCEL
@ TLP_STOP