An API for reporting progress. More...

#include <mbl_progress.h>

Inheritance diagram for mbl_progress:

Public Member Functions
	mbl_progress ()
	Constructor.
virtual	~mbl_progress ()
	Destructor.
void	set_estimated_iterations (const vcl_string &identifier, const int iterations, const vcl_string &display_text)
	Estimated number of iterations for the given identifier.
void	set_throw_exception_on_cancel (bool t)
	If true set_progress() will throw an exception if cancel has been set.
void	set_progress (const vcl_string &identifier, const int progress)
	Sets progress for the given identifier.
void	increment_progress (const vcl_string &identifier, const int n=1)
	Increments progress for the given identifier by n.
void	end_progress (const vcl_string &identifier)
	Explicitly marks the end of loop for the given identifier.
int	progress (const vcl_string &identifier) const
	Gets progress for given identifier.
vcl_string	display_text (const vcl_string &identifier) const
	Gets display text for given identifier.
int	estimated_iterations (const vcl_string &identifier) const
	Gets estimated total iterations for given identifier.
void	set_cancelled (const vcl_string &identifier, const bool cancel)
	Modify the flag to cancel the current process.
bool	is_cancelled (const vcl_string &identifier) const
	Check whether progress object is marked as cancelled.
Protected Member Functions
virtual void	on_set_estimated_iterations (const vcl_string &identifier, const int total_iterations)=0
	Called when set_estimated_iterations() is called for a given identifier.
virtual void	on_set_progress (const vcl_string &identifier, const int progress)=0
	Called when set_progress() is called for a given identifier.
virtual void	on_end_progress (const vcl_string &identifier)=0
	Called when end_progress() is called for a given identifier.
Private Attributes
vcl_map< vcl_string, vcl_string >	identifier2displaytext_
	Stores display text for each identifier.
vcl_map< vcl_string, int >	identifier2estimatediterations_
	Stores estimated iterations for each identifier.
vcl_map< vcl_string, int >	identifier2progress_
	Stores current progress for each identifier.
vcl_map< vcl_string, bool >	identifier2cancel_
	Flags to indicate whether a request to cancel has been registered for each identifier.
bool	throw_exception_on_cancel_
	If true set_progress() will throw an exception if cancel has been set.

Detailed Description

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.

Definition at line 48 of file mbl_progress.h.

Constructor & Destructor Documentation

mbl_progress::mbl_progress ( ) [inline]

Constructor.

Definition at line 53 of file mbl_progress.h.

virtual mbl_progress::~mbl_progress ( ) [inline, virtual]

Destructor.

Definition at line 56 of file mbl_progress.h.

Member Function Documentation

vcl_string mbl_progress::display_text ( const vcl_string & identifier ) const

Gets display text for given identifier.

Parameters:

identifier to query.

Definition at line 83 of file mbl_progress.cxx.

void mbl_progress::end_progress ( const vcl_string & identifier )

Explicitly marks the end of loop for the given identifier.

Definition at line 62 of file mbl_progress.cxx.

int mbl_progress::estimated_iterations ( const vcl_string & identifier ) const

Gets estimated total iterations for given identifier.

Parameters:

identifier to query.

Returns:: progress (-1 if identifier is not known by this object).

Definition at line 97 of file mbl_progress.cxx.

void mbl_progress::increment_progress	(	const vcl_string &	identifier,
		const int	n = `1`
	)

Increments progress for the given identifier by n.

Definition at line 48 of file mbl_progress.cxx.

bool mbl_progress::is_cancelled ( const vcl_string & identifier ) const

Check whether progress object is marked as cancelled.

Parameters:

identifier Progress object to check.

Returns:: True if a cancel flag is set for this progress object.

Definition at line 130 of file mbl_progress.cxx.

virtual void mbl_progress::on_end_progress ( const vcl_string & identifier ) [protected, pure virtual]

Called when end_progress() is called for a given identifier.

Derived classes may take some action here.

Parameters:

identifier The operation being monitored.

Implemented in mbl_progress_composite, mbl_progress_time, mbl_progress_text, mbl_progress_hierarchy, and mbl_progress_null.

virtual void mbl_progress::on_set_estimated_iterations	(	const vcl_string &	identifier,
		const int	total_iterations
	)		`[protected, pure virtual]`

Called when set_estimated_iterations() is called for a given identifier.

Derived classes may take some action here.

Parameters:

identifier The operation being monitored.

Implemented in mbl_progress_composite, mbl_progress_time, mbl_progress_text, mbl_progress_null, and mbl_progress_hierarchy.

virtual void mbl_progress::on_set_progress	(	const vcl_string &	identifier,
		const int	progress
	)		`[protected, pure virtual]`

Called when set_progress() is called for a given identifier.

Derived classes may take some action here.

Parameters:

identifier	The operation being monitored.
progress	The new progress status.

Implemented in mbl_progress_composite, mbl_progress_time, mbl_progress_text, mbl_progress_hierarchy, and mbl_progress_null.

int mbl_progress::progress ( const vcl_string & identifier ) const

Gets progress for given identifier.

Parameters:

identifier to query.

Returns:: progress (-i if identifier is not known by this object).

Definition at line 69 of file mbl_progress.cxx.

void mbl_progress::set_cancelled	(	const vcl_string &	identifier,
		const bool	cancel
	)

Modify the flag to cancel the current process.

Parameters:

identifier Progress object to cancel.

Definition at line 114 of file mbl_progress.cxx.

void mbl_progress::set_estimated_iterations	(	const vcl_string &	identifier,
		const int	iterations,
		const vcl_string &	display_text
	)

Estimated number of iterations for the given identifier.

Definition at line 11 of file mbl_progress.cxx.

void mbl_progress::set_progress	(	const vcl_string &	identifier,
		const int	progress
	)

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.

Definition at line 24 of file mbl_progress.cxx.

void mbl_progress::set_throw_exception_on_cancel ( bool t ) [inline]

If true set_progress() will throw an exception if cancel has been set.

Definition at line 64 of file mbl_progress.h.

Member Data Documentation

vcl_map<vcl_string, bool> mbl_progress::identifier2cancel_ [private]

Flags to indicate whether a request to cancel has been registered for each identifier.

Definition at line 137 of file mbl_progress.h.

vcl_map<vcl_string, vcl_string> mbl_progress::identifier2displaytext_ [private]

Stores display text for each identifier.

Definition at line 128 of file mbl_progress.h.

vcl_map<vcl_string, int> mbl_progress::identifier2estimatediterations_ [private]

Stores estimated iterations for each identifier.

Definition at line 131 of file mbl_progress.h.

vcl_map<vcl_string, int> mbl_progress::identifier2progress_ [private]

Stores current progress for each identifier.

Definition at line 134 of file mbl_progress.h.

bool mbl_progress::throw_exception_on_cancel_ [private]

If true set_progress() will throw an exception if cancel has been set.

Definition at line 140 of file mbl_progress.h.

The documentation for this class was generated from the following files:

contrib/mul/mbl/mbl_progress.h
contrib/mul/mbl/mbl_progress.cxx

Public Member Functions

Protected Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation