Tulip  5.2.0
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.
78  * Every plugin in tulip got a pluginProgress member they can call to give progress feedbacks. When
79  *running, the plugin should make a call to tlp::PluginProgress::progress() indicating the current
80  *state of the compuation.
81  * The tlp::PluginProgress returns a tlp::ProgressState indicating what behavior the underlaying
82  *system should have (see tlp::ProgressState for details)
83  **/
84 class TLP_SCOPE PluginProgress {
85  ProgressPreviewHandler *_previewHandler;
86 
87 public:
89  virtual ~PluginProgress();
90  void setPreviewHandler(ProgressPreviewHandler *);
91 
92  /**
93  * @brief Notifies the progression of the process.
94  *
95  * @param step The current step number.
96  * @param max_step The total number of steps.
97  *
98  * * @warning For default previsualisation handling to work, be sure to call
99  *PluginProgress::progress in this method (the return value can be ignored)
100  *
101  * @return tlp::ProgressState a value indicating whether the progress has been stopped, cancelled,
102  *or will continue.
103  * @see tlp::ProgressState
104  **/
105  virtual ProgressState progress(int step, int max_step);
106 
107  /**
108  * @brief Sets the state flag to cancel, notifying to the process that the user wants to cancel
109  *it.
110  * Canceling a process must stop it and revert all the changes performed since its start.
111  *
112  * @return void
113  **/
114  virtual void cancel() = 0;
115 
116  /**
117  * @brief Sets the state flag to stop, notifying to the process that the user wants to stop it.
118  * Stopping a process does not revert changes.
119  * @return void
120  **/
121  virtual void stop() = 0;
122 
123  /**
124  * @brief The preview mode redraws the graph while applying the algorithm, making it slower.
125  *
126  * @return bool Whether the preview mode is activated.
127  **/
128  virtual bool isPreviewMode() const = 0;
129 
130  /**
131  * @brief The preview mode redraws the graph while applying the algorithm, making it slower.
132  *
133  * @param drawPreview Whether the preview should be drawn.
134  * @return void
135  **/
136  virtual void setPreviewMode(bool drawPreview) = 0;
137 
138  /**
139  * @brief This tells the widget if it should show a preview checkbox, allowing the user to decide
140  *if the algorithm should draw a preview or not.
141  *
142  * @param showPreview Whether the progress widget should contain a preview checkbox or not.
143  * @return void
144  **/
145  virtual void showPreview(bool showPreview) = 0;
146 
147  /**
148  * @brief Gets the current internal state of the PluginProgress.
149  *
150  * @return tlp::ProgressState The current state.
151  **/
152  virtual ProgressState state() const = 0;
153 
154  /**
155  * @brief Returns a message describing the error encountered during the process. If no error has
156  *been encountered, an empty string is returned.
157  *
158  * @return :string A description of the encountered error, if any.
159  **/
160  virtual std::string getError() = 0;
161 
162  /**
163  * @brief Sets the message describing the error encountered during the process.
164  *
165  * @param error The description of the encountered error.
166  * @return void
167  **/
168  virtual void setError(const std::string &error) = 0;
169 
170  /**
171  * @brief Changes the comment about the process progression.
172  *
173  * @param comment A description of what the plugin is currently doing, displayed to inform the
174  *user.
175  * @return void
176  **/
177  virtual void setComment(const std::string &comment) = 0;
178 
179  /**
180  * @brief Changes the title of that plugin progress
181  *
182  * @param title the title to set
183  * @return void
184  **/
185  virtual void setTitle(const std::string &title) = 0;
186 };
187 }
188 #endif
ProgressState
This enum describes callback actions for the underlaying system when calling tlp::PluginProgress::pro...
The ProgressPreviewHandler class handles the way a process handled by a PluginProgress is handled...
PluginProcess subclasses are meant to notify about the progress state of some process (typically a pl...