Tulip  4.0.0
Better Visualization Through Research
 All Classes 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  *
31  * @brief This enum describes callback actions for the underleying system when calling tlp::PluginProgress::progress();
32  * @list
33  * @li TLP_CONTINUE: tells that the process monitored by the the progress should continue.
34  * @li TLP_CANCEL: The process should be cancelled, reverting all changes since it was started.
35  * @li TLP_STOP: The process should stop, leaving all the changes made since the beginning
36  * @endlist
37  *
38  * @see tlp::PluginProgress
39  **/
41  /** The plugin should continue its execution. */
43  /** The plugin should cancel, reverting all performed changes since the plugin was called. */
45  /** The plugin should stop, leaving the graph in its current state. */
47 };
48 
49 /**
50  * @ingroup Plugins
51  * @brief PluginProcess subclasses are meant to notify about the progress state of some process (typically a plugin)
52  *
53  * PluginProgress are mainly used alongside with tlp::Plugin instances to give user a visual feedback about the progress of the plugin.
54  * 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.
55  * The tlp::PluginProgress returns a tlp::ProgressState indicating what behavior the underleying system should have (see tlp::ProgressState for details)
56  **/
57 class TLP_SCOPE PluginProgress {
58 public:
59  virtual ~PluginProgress() {}
60 
61  /**
62  * @brief Notifies the progression of the process.
63  *
64  * @param step The current step number.
65  * @param max_step The total number of steps.
66  * @return tlp::ProgressState a value indicating whether the progress has been stopped, cancelled, or will continue.
67  * @see tlp::ProgressState
68  **/
69  virtual ProgressState progress(int step, int max_step)=0;
70 
71  /**
72  * @brief Sets the state flag to cancel, notifying to the process that the user wants to cancel it.
73  * Canceling a process must stop it and revert all the changes performed since its start.
74  *
75  * @return void
76  **/
77  virtual void cancel()=0;
78 
79  /**
80  * @brief Sets the state flag to stop, notifying to the process that the user wants to stop it.
81  * Stopping a process does not revert changes.
82  * @return void
83  **/
84  virtual void stop()=0;
85 
86  /**
87  * @brief The preview mode redraws the graph while applying the algorithm, making it slower.
88  *
89  * @return bool Whether the preview mode is activated.
90  **/
91  virtual bool isPreviewMode() const =0;
92 
93 
94  /**
95  * @brief The preview mode redraws the graph while applying the algorithm, making it slower.
96  *
97  * @param drawPreview Whether the preview should be drawn.
98  * @return void
99  **/
100  virtual void setPreviewMode(bool drawPreview)=0;
101 
102  /**
103  * @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.
104  *
105  * @param showPreview Whether the progress widget should contain a preview checkbox or not.
106  * @return void
107  **/
108  virtual void showPreview(bool showPreview)=0;
109 
110  /**
111  * @brief Gets the current internal state of the PluginProgress.
112  *
113  * @return tlp::ProgressState The current state.
114  **/
115  virtual ProgressState state() const=0;
116 
117  /**
118  * @brief Returns a message describing the error encountered during the process. If no error has been encountered, an empty string is returned.
119  *
120  * @return :string A description of the encountered error, if any.
121  **/
122  virtual std::string getError()=0;
123 
124  /**
125  * @brief Sets the message describing the error encountered during the process.
126  *
127  * @param error The description of the encountered error.
128  * @return void
129  **/
130  virtual void setError(const std::string& error)=0;
131 
132  /**
133  * @brief Changes the comment about the process progression.
134  *
135  * @param comment A description of what the plugin is currently doing, displayed to inform the user.
136  * @return void
137  **/
138  virtual void setComment(const std::string& comment)=0;
139 
140 };
141 
142 }
143 #endif