1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
|
#ifndef mbl_progress_h_
#define mbl_progress_h_
#ifdef VCL_NEEDS_PRAGMA_INTERFACE
#pragma interface
#endif
//:
// \file
// \brief A base for classes which wish to take some action during a lengthy operation.
// \author Graham Vincent and Kevin de Souza
// \date 25 Feb 2005
#include <vcl_string.h>
#include <vcl_map.h>
//========================================================================
//: An exception that can be thrown by an operation when cancelled.
class mbl_progress_cancel_exception
{
public:
mbl_progress_cancel_exception() {}
~mbl_progress_cancel_exception() {}
};
//========================================================================
//: An API for reporting progress.
//
// An mbl_progress object can be used to keep track of multiple operations.
// Each one is identified by a unique string.
//
// A function implementing an algorithm may accept a mbl_progress object.
// Before entering a processing loop, the function passes the progress
// object an identifying string together with an estimate of how many
// iterations the loop is expected to take. During the subsequent
// processing, the process informs the progress object when each iteration
// has completed. It is up to the derived classes to act on this information.
//
// For example: derive a class containing a graphical progress bar,
// which is updated when a particular identifier indicates that an
// iteration has completed.
//
// The algorithm may also query the progress object to check if it has
// been cancelled (e.g. by a user pressing a cancel button in a
// derived GUI class) and take appropriate action.
//
// Algorithms could have the identifier associated with various tasks in
// their public interface.
class mbl_progress
{
public:
//: Constructor
mbl_progress(): throw_exception_on_cancel_(false) {}
//: Destructor
virtual ~mbl_progress() {}
//: Estimated number of iterations for the given identifier.
void set_estimated_iterations(const vcl_string& identifier,
const int iterations,
const vcl_string& display_text);
//: If true set_progress() will throw an exception if cancel has been set
void set_throw_exception_on_cancel(bool t)
{ throw_exception_on_cancel_=t; }
//: Sets progress for the given identifier.
// Checks whether cancel has been set; if so calls end_progress(),
// and throws an exception if "throw_exception_on_cancel" is true.
void set_progress(const vcl_string& identifier,
const int progress);
//: Increments progress for the given identifier by n.
void increment_progress(const vcl_string& identifier,
const int n=1);
//: Explicitly marks the end of loop for the given identifier.
void end_progress(const vcl_string& identifier);
//: Gets progress for given identifier.
// \param identifier to query.
// \return progress (-i if identifier is not known by this object).
int progress(const vcl_string& identifier) const;
//: Gets display text for given identifier.
// \param identifier to query.
vcl_string display_text(const vcl_string& identifier) const;
//: Gets estimated total iterations for given identifier.
// \param identifier to query.
// \return progress (-1 if identifier is not known by this object).
int estimated_iterations(const vcl_string& identifier) const;
//: Modify the flag to cancel the current process.
// \param identifier Progress object to cancel.
void set_cancelled(const vcl_string& identifier,
const bool cancel);
//: Check whether progress object is marked as cancelled.
// \param identifier Progress object to check.
// \return True if a cancel flag is set for this progress object.
bool is_cancelled(const vcl_string& identifier) const;
protected:
//: Called when set_estimated_iterations() is called for a given identifier.
// Derived classes may take some action here.
// \param identifier The operation being monitored.
virtual void on_set_estimated_iterations(const vcl_string& identifier,
const int total_iterations) = 0;
//: Called when set_progress() is called for a given identifier.
// Derived classes may take some action here.
// \param identifier The operation being monitored.
// \param progress The new progress status.
virtual void on_set_progress(const vcl_string& identifier,
const int progress) = 0;
//: Called when end_progress() is called for a given identifier.
// Derived classes may take some action here.
// \param identifier The operation being monitored.
virtual void on_end_progress(const vcl_string& identifier) = 0;
private:
//: Stores display text for each identifier
vcl_map<vcl_string, vcl_string> identifier2displaytext_;
//: Stores estimated iterations for each identifier
vcl_map<vcl_string, int> identifier2estimatediterations_;
//: Stores current progress for each identifier
vcl_map<vcl_string, int> identifier2progress_;
//: Flags to indicate whether a request to cancel has been registered for each identifier
vcl_map<vcl_string, bool> identifier2cancel_;
//: If true set_progress() will throw an exception if cancel has been set.
bool throw_exception_on_cancel_;
};
//========================================================================
#endif // mbl_progress_h_
|
