casacore
ProgressMeter.h
Go to the documentation of this file.
1 //# ProgressMeter.h: Visual indication of a tasks progress.
2 //# Copyright (C) 1997,2000
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //#
27 //# $Id$
28 
29 #ifndef CASA_PROGRESSMETER_H
30 #define CASA_PROGRESSMETER_H
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <time.h>
35 
36 namespace casacore { //# NAMESPACE CASACORE - BEGIN
37 
38 //# Forward Declarations
39 class String;
40 
41 // <summary>
42 // Visual indication of a tasks progress.
43 // </summary>
44 
45 // <use visibility=export>
46 
47 // <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="">
48 // </reviewed>
49 
50 // <synopsis>
51 // This class is used to provide a visual indication to the user of the progress
52 // of his task. If the process is not connected to the DO system, calls to the
53 // progress meter are NO-OP's, so you can safely use this class in general
54 // library code and it won't cause problems for processes which are not
55 // attached to the distributed object system. It also won't cause any extra
56 // stuff to be linked in to your executable in this case.
57 //
58 // The progress meter will usually be removed from the screen once the maximum
59 // value is set, so you should not reuse the ProgressMeter after that has
60 // happened. It is harmless, but it will not result in any visual feedback for
61 // the user.
62 //
63 // While the "min" is usually less than "max", if in fact it is greater than
64 // "max" the progress meter will count down correctly.
65 // </synopsis>
66 //
67 // <example>
68 // <srcblock>
69 // void calculate(uInt n) {
70 // Int skip = n / 200;
71 // ProgressMeter meter(0, n, "Title", "Subtitle", "", "", True, skip);
72 // for (uInt i=0; i<n; i++) {
73 // ... calculate ...
74 // meter.update(i);
75 // }
76 // }
77 // </srcblock>
78 // </example>
79 //
80 // <motivation>
81 // Give the user visual indication of a long-running tasks progress.
82 // </motivation>
83 //
84 // <todo asof="1997/03/03">
85 // <li> When the upper bound isn't known, it might be useful to have a busy
86 // bar that just moves back and forth to show that activity is happening.
87 // <li> We should probably have some way to suppress progress bars for tasks
88 // that are only going to take a few seconds.
89 // </todo>
90 
92 {
93 public:
94  // Makes a null progress meter, i.e. no updates to the screen are
95  // generated.
97 
98  // Create a progress meter with the given min and max values and labels.
99  // if <src>estimateTime</src> is <src>True</src>, an estimate of the
100  // time remaining will be made for the user. This estimate assumes that
101  // the remaining portion will compute at the same rate as the portion
102  // completed so far, so the time should not be estimated for processes
103  // which are non-linear.
104  //
105  // Any labels which are set to the empty string will have sensible defaults
106  // supplied. In particular, <src>minlabel</src> and <src>maxlabel</src>
107  // will be set to the display the minimum and maximum values.
108  //
109  // Normally the progress bar will be updated with every call to
110  // <src>update()</src>. If however you will be sending many events
111  // then you might want to update the GUI every <src>updateEvery</src>'th
112  // event for efficiency. Generally there's no point updating more than
113  // a couple of hundred times since the eye can't distinguish differences
114  // in the progress bar position at that level. If updateEvery is <=0, it
115  // is set to 1 for you.
117  const String &title, const String &subtitle,
118  const String &minlabel, const String &maxlabel,
119  Bool estimateTime = True, Int updateEvery=1);
120 
122  // The destruction of the meter will cause an update to be sent with the
123  // maximum value. This will usually cause the GUI window to be removed
124  // from the screen. Thus the progress meter should generally live as long
125  // as the calculation it is tracking.
127 
128  void update(Double value, Bool force=False);
129  void _update(Double value, Bool force=False);
130  void busy();
131  void done();
132 
133  // Display the min and max values of the progress meter.
134  // <group>
135  Double min() const;
136  Double max() const;
137  // </group>
138 
139  friend class ObjectController;
140  static const char* PROGRESSFILE;
141 private:
145  // Time the progress meter began
146  time_t startTime;
148 
149  // These are set by ObjectController for executables that have the tasking
150  // system in them, otherwise they are null and this class just does no-ops.
152  const String &, const String &,
153  const String &, const String &,
154  Bool);
155  static void (*update_function_p)(Int, Double);
156  static void (*show_function_p)(Int, Double);
157  static void (*busy_function_p)(Int);
158  static void (*done_function_p)(Int);
159 
160  // Undefined and inaccessible
163 };
164 
165 
166 } //# NAMESPACE CASACORE - END
167 
168 #endif
169 
170 
ProgressMeter()
Makes a null progress meter, i.e.
friend class ObjectController
ProgressMeter(Double min, Double max, const String &title)
static Int(* creation_function_p)(Double, Double, const String &, const String &, const String &, const String &, Bool)
These are set by ObjectController for executables that have the tasking system in them,...
ProgressMeter(const ProgressMeter &)
Undefined and inaccessible.
ProgressMeter(Double min, Double max, const String &title, const String &subtitle, const String &minlabel, const String &maxlabel, Bool estimateTime=True, Int updateEvery=1)
Create a progress meter with the given min and max values and labels.
static void(* done_function_p)(Int)
Double min() const
Display the min and max values of the progress meter.
void update(Double value, Bool force=False)
static void(* show_function_p)(Int, Double)
~ProgressMeter()
The destruction of the meter will cause an update to be sent with the maximum value.
ProgressMeter & operator=(const ProgressMeter &)
static void(* update_function_p)(Int, Double)
void _update(Double value, Bool force=False)
time_t startTime
Time the progress meter began.
static const char * PROGRESSFILE
static void(* busy_function_p)(Int)
String: the storage and methods of handling collections of characters.
Definition: String.h:225
this file contains all the compiler specific defines
Definition: mainpage.dox:28
const Bool False
Definition: aipstype.h:44
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
const Bool True
Definition: aipstype.h:43
double Double
Definition: aipstype.h:55