Tulip  5.6.3
Large graphs analysis and drawing
PluginProgress.h
1 /*
2  *
3  * This file is part of Tulip (http://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  * underlaying 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 underlaying 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. */
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 underlaying 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
tlp::ProgressState
ProgressState
This enum describes callback actions for the underlaying system when calling tlp::PluginProgress::pro...
Definition: PluginProgress.h:62
tlp::TLP_CANCEL
@ TLP_CANCEL
Definition: PluginProgress.h:66
tlp::ProgressPreviewHandler
The ProgressPreviewHandler class handles the way a process handled by a PluginProgress is handled.
Definition: PluginProgress.h:39
tlp::TLP_CONTINUE
@ TLP_CONTINUE
Definition: PluginProgress.h:64
tlp
Definition: AbstractProperty.h:34
tlp::PluginProgress::showText
virtual void showText(bool)
This tells the progress if it has to show text indicating execution progression.
Definition: PluginProgress.h:161
tlp::PluginProgress
PluginProcess subclasses are meant to notify about the progress state of some process (typically a pl...
Definition: PluginProgress.h:83
tlp::TLP_STOP
@ TLP_STOP
Definition: PluginProgress.h:68