casacore
Loading...
Searching...
No Matches
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
36namespace casacore { //# NAMESPACE CASACORE - BEGIN
37
38//# Forward Declarations
39class 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{
93public:
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
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;
141private:
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 & operator=(const ProgressMeter &)
~ProgressMeter()
The destruction of the meter will cause an update to be sent with the maximum value.
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