Source: fun/Progress.h

//  Progress - a wrapper around QProgressDialog
//  Copyright (C) 2000-2003 bozo & sgbeal @users.sourceforge.net
//
//  This program is free software; you can redistribute it and/or
//  modify it under the terms of the GNU General Public License
//  as published by the Free Software Foundation; either version 2
//  of the License, or (at your option) any later version.
//
//  This program is distributed in the hope that it will be useful,
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//  GNU General Public License for more details.
//
//  You should have received a copy of the GNU General Public License
//  along with this program; if not, write to the Free Software
//  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

#ifndef _FUN_PROGRESS_H
#define _FUN_PROGRESS_H

#include 
#include   //  for timeval

namespace fun {

/**
*  This is a wrapper around QProgressDialog for classes which want to report
*  progress information, but don't want to know whether there's a QApplication
*  which needs to have processEvents() called, or whether other chunks of code
*  already have a progress dialog up, etc.
*
*  If there are places where you notice multiple progress dialogs popping
*  up in series, you can fix that by nesting them in an outer start()/finish()
*  pair.  For example, when loubetomy loads a map, it performs three steps:
*  

*  
creates a SerialTree from the given file.
*  
deserializes the HexMap from the resulting SerialTree.
*  
gives the resulting HexMap to HexMapView so that the necessary graphic
*      bits can be created.
*  
*  All of those steps are performed by chunks of library code which don't
*  know about each other--and loubetomy doesn't want to know which of them,
*  if any, report progress information--so loubetomy calls Progress::start(),
*  does the first step, calls Progress::update() (which tells it whether the
*  user hit the cancel button while SerialTree was doing its thing), then
*  deserializes the HexMap, then calls Progress::update() again (which,
*  again, tells it whether the user hit the cancel button while the HexMap
*  was deserializing itself), then gives the map to its HexMapView, & finally
*  calls Progress::finish() to make the dialog go away (if one was displayed).
*
*  (If the library code was responsible for fondling the progress dialog
*  itself, it would be more complicated, and either there would be gaps when
*  the program was busy but no dialog was up, or there would be points when
*  two progress dialogs were up, & in either case it would be messier for
*  loubetomy to know whether the user had hit "cancel" in the dialog displayed
*  by the library.)
*/
class Progress
{
	public:
	/**
	*  Indicates that some operation is starting for which progress will be
	*  reported.  Whether this does anything depends on a couple of things:
	*  

	*  
If no QApplication has been passed to setQApplication(),
	*      this just notes the start time.  (It might not even do that.)
	*      Keeping this fast for non-interactive programs which don't care
	*      about popping up progress dialogs is important!
	*  
Otherwise, if this call is nested inside another start/finish
	*      pair, then it updates the existing QProgressDialog, if any.
	*  
Otherwise, this creates a QProgressDialog.  (Whether or not the
	*      dialog shows itself is up to the dialog.)
	*  
	*
	*  @param operation   A description of the operation being performed.  This
	*                     will be displayed in the progress dialog, if any.
	*  @param steps       The number of steps in this operation.
	*  @param canCancel   Whether or not this operation can be cancelled by the
	*                     user.
	* 
	*/
	static void start(const QString &operation, int steps, bool canCancel = true);

	/**
	*  Same as start(), so that you don't have to remember whether it's
	*  "start" or "begin".
	*/
	static void begin(const QString &operation, int steps, bool canCancel = true) { return start(operation, steps, canCancel); }

	/**
	*  This updates the existing progress dialog, if any.  If a progress
	*  dialog is up, and the user has hit cancel (or if the user hit cancel
	*  during some nested operation), this returns true; otherwise it returns
	*  false.
	*
	*  If the user has inidicated that they want to cancel the operation, you
	*  still need to call finish().
	*
	*  If no QApplication has been passed to setQApplication(), then update()
	*  doesn't do anything, and just returns false.
	*
	*  @param step   which step has been completed.
	*/
	static bool update(int step);

	/**
	*  Indicates that the operation is done (even if it's "done" because it
	*  was cancelled by the user).  What this does depends on several things:
	*
	*  

	*  
If no QApplication has been passed to setQApplication(),
	*      this might print the elapsed time, or do nothing.
	*  
Otherwise, if this call is nested inside another start/finish
	*      pair, then it restores the existing QProgressDialog with the
	*      "outer" ("anti-nested"?) operation's values.
	*  
Otherwise, this cleans up the progress dialog.
	*  
	*/
	static void finish();

	/**
	*  Same as finish(), so that you don't have to remember whether it's
	*  "finish" or "end".
	*/
	static void end() { finish(); }

	/**
	*  Causes the progress dialog, if any, to become hidden.  You want to
	*  do this if you need to pop up a confirmation dialog in the middle of
	*  some operation; otherwise the progress dialog is probably going to
	*  be rather rude about popping up in front of the confirmation dialog &
	*  demanding attention.  Regardless of subsequent calls to update(), the
	*  progress dialog will not be shown again until resume() or finish() is
	*  called.  (In the case of finish(), the dialog won't be shown again
	*  until the start of the next non-nested operation.)
	*
	*  suspend()/resume() pairs can be nested.  Calling suspend() before
	*  start() has no effect.
	*/
	static void suspend();

	/**
	*  Prints a randomly-selected QUB developer's resumé on stdout.
	*  Err, wait, apparently it causes the progress dialog, if any, to resume
	*  being shown after a call to suspend().  (It may not actually show
	*  itself until the next call to update().)
	*
	*  Note that suspend()/resume() calls may be nested; the dialog will not
	*  actually be displayed until after the outermost resume() call.
	*/
	static void resume();

	/**
	*  Returns true if this operation (or a nested one) has been cancelled.
	*  (The other way to find this out is from the return value from update().)
	*/
	static bool cancelled();

	/**
	*  Sets the QApplication whose processEvents() will be called during
	*  update().  If you create a QApplication, just call this in your
	*  main() and forget about it.
	*
	*  If this is never called (or is called with a NULL QApplication), the
	*  other progress methods don't really do anything.
	*/
	static void setQApplication(QApplication *);

	~Progress();

	private:
	Progress(int, const QString &, bool);

	int steps;
	int step;
	bool canCancel;
	QString msg;
	timeval startTime;
};

}  //  namespace fun

#endif  //  _FUN_PROGRESS_H