cgul_progress_bar.h File Reference

progress bar More...

#include "cgul_common.h"
#include "cgul_exception.h"

Include dependency graph for cgul_progress_bar.h:

This graph shows which files directly or indirectly include this file:

Typedefs
typedef typedefCGUL_BEGIN_C struct cgul_progress_bar *	cgul_progress_bar_t

Enumerations
enum	cgul_progress_bar__style_t { CGUL_PROGRESS_BAR__SIMPLE, CGUL_PROGRESS_BAR__COMMON, CGUL_PROGRESS_BAR__INVALID }

Functions
CGUL_EXPORT cgul_progress_bar_t	cgul_progress_bar__new (cgul_exception_t *cex)
CGUL_EXPORT void	cgul_progress_bar__delete (cgul_progress_bar_t bar)
CGUL_EXPORT void	cgul_progress_bar__reset (cgul_exception_t *cex, cgul_progress_bar_t bar)
CGUL_EXPORT cgul_progress_bar__style_t	cgul_progress_bar__get_style (cgul_exception_t *cex, cgul_progress_bar_t bar)
CGUL_EXPORT void	cgul_progress_bar__set_style (cgul_exception_t *cex, cgul_progress_bar_t bar, cgul_progress_bar__style_t style)
CGUL_EXPORT double	cgul_progress_bar__get_min (cgul_exception_t *cex, cgul_progress_bar_t bar)
CGUL_EXPORT void	cgul_progress_bar__set_min (cgul_exception_t *cex, cgul_progress_bar_t bar, double min)
CGUL_EXPORT double	cgul_progress_bar__get_max (cgul_exception_t *cex, cgul_progress_bar_t bar)
CGUL_EXPORT void	cgul_progress_bar__set_max (cgul_exception_t *cex, cgul_progress_bar_t bar, double max)
CGUL_EXPORT FILE *	cgul_progress_bar__get_file (cgul_exception_t *cex, cgul_progress_bar_t bar)
CGUL_EXPORT void	cgul_progress_bar__set_file (cgul_exception_t *cex, cgul_progress_bar_t bar, FILE *f)
CGUL_EXPORT void	cgul_progress_bar__update (cgul_exception_t *cex, cgul_progress_bar_t bar, double progress, const char *before, const char *after)

Detailed Description

This is a class for drawing text-based progress bars. The different styles of progress bar are defined by the cgul_progress_bar__style_t typedef.

Author

Paul Serice

Typedef Documentation

cgul_progress_bar_t

typedef typedefCGUL_BEGIN_C struct cgul_progress_bar* cgul_progress_bar_t

Opaque pointer to a cgul_progress_bar instance.

Enumeration Type Documentation

cgul_progress_bar__style_t

enum cgul_progress_bar__style_t

The style of progress bar to draw.

Enumerator
CGUL_PROGRESS_BAR__SIMPLE	Simple style of progress bar. It looks as shown below when drawn at 100%. This progress bar does not use any special characters to draw. Instead, it is just a steady progression of characters until the entire bar is drawn. The main advantage of this progress bar is that it works over connections with very low bandwidth. It also means that when the output from the progress bar is saved to a log file, what you see is what you get. 0...10...20...30...40...50...60...70...80...90...100%
CGUL_PROGRESS_BAR__COMMON	Common style of progress bar. This is the default progress bar. You will see similar progress bars in wget and BSD's ftp client. It looks as shown below when drawn at 100%. This bar requires a dedicated line so that it can overwrite itself for each update. Each update will change the numeric percentage indicator, and the client can supply optional custom before and after text that will also be updated. This bar can run in reverse if necessary. before 100% [####################################] after
CGUL_PROGRESS_BAR__INVALID	Invalid style.

Function Documentation

cgul_progress_bar__new()

CGUL_EXPORT cgul_progress_bar_t cgul_progress_bar__new

(

cgul_exception_t *

cex

)

Create a new cgul_progress_bar instance with a default minimum value of 0 and a default maximum value of 100. Also by default, new instances of this class draw their progress indicator to stdout. If memory allocation fails, NULL is returned, and an exception is thrown.

Parameters

[in,out]

cex

c-style exception

Returns

new cgul_progress_bar instance

Referenced by cgul_progress_bar_cxx::cgul_progress_bar_cxx().

cgul_progress_bar__delete()

CGUL_EXPORT void cgul_progress_bar__delete

(

cgul_progress_bar_t

bar

)

Delete the bar instance. All internally allocated resources will be freed. The client must not use bar after calling this method.

Parameters

[in]

bar

cgul_progress_bar instance

Referenced by cgul_progress_bar_cxx::set_obj(), and cgul_progress_bar_cxx::~cgul_progress_bar_cxx().

cgul_progress_bar__reset()

CGUL_EXPORT void cgul_progress_bar__reset	(	cgul_exception_t *	cex,
		cgul_progress_bar_t	bar
	)

Reset bar so it can be reused. This method does not change the minimum or maximum values back to their default values. It also does not change the current file where the progress indicator will be drawn. Calling this method is necessary only when using CGUL_PROGRESS_BAR__SIMPLE.

Parameters

[in]	cex	c-style exception
[in]	bar	cgul_progress_bar instance

Referenced by cgul_progress_bar_cxx::reset().

cgul_progress_bar__get_style()

CGUL_EXPORT cgul_progress_bar__style_t cgul_progress_bar__get_style	(	cgul_exception_t *	cex,
		cgul_progress_bar_t	bar
	)

Get the style of the progress bar.

Parameters

[in]	cex	c-style exception
[in]	bar	cgul_progress_bar instance

Returns

progress bar style

Referenced by cgul_progress_bar_cxx::get_style().

cgul_progress_bar__set_style()

CGUL_EXPORT void cgul_progress_bar__set_style	(	cgul_exception_t *	cex,
		cgul_progress_bar_t	bar,
		cgul_progress_bar__style_t	style
	)

Set the style of the progress bar. The default style is CGUL_PROGRESS_BAR__SIMPLE. If an invalid style is specified, an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	bar	cgul_progress_bar instance
[in]	style	progress bar style

Referenced by cgul_progress_bar_cxx::set_style().

cgul_progress_bar__get_min()

CGUL_EXPORT double cgul_progress_bar__get_min	(	cgul_exception_t *	cex,
		cgul_progress_bar_t	bar
	)

Get the minimum value for the range of progress.

Parameters

[in]	cex	c-style exception
[in]	bar	cgul_progress_bar instance

Returns

minimum value

Referenced by cgul_progress_bar_cxx::get_min().

cgul_progress_bar__set_min()

CGUL_EXPORT void cgul_progress_bar__set_min	(	cgul_exception_t *	cex,
		cgul_progress_bar_t	bar,
		double	min
	)

Set the minimum value for the range of progress. By default, the minimum value is 0.

Parameters

[in]	cex	c-style exception
[in]	bar	cgul_progress_bar instance
[in]	min	minimum value

Referenced by cgul_progress_bar_cxx::set_min().

cgul_progress_bar__get_max()

CGUL_EXPORT double cgul_progress_bar__get_max	(	cgul_exception_t *	cex,
		cgul_progress_bar_t	bar
	)

Get the maximum value for the range of progress.

Parameters

[in]	cex	c-style exception
[in]	bar	cgul_progress_bar instance

Returns

maximum value

Referenced by cgul_progress_bar_cxx::get_max().

cgul_progress_bar__set_max()

CGUL_EXPORT void cgul_progress_bar__set_max	(	cgul_exception_t *	cex,
		cgul_progress_bar_t	bar,
		double	max
	)

Set the maximum value for the range of progress. By default, the maximum value is 100.

Parameters

[in]	cex	c-style exception
[in]	bar	cgul_progress_bar instance
[in]	max	maximum value

Referenced by cgul_progress_bar_cxx::set_max().

cgul_progress_bar__get_file()

CGUL_EXPORT FILE* cgul_progress_bar__get_file	(	cgul_exception_t *	cex,
		cgul_progress_bar_t	bar
	)

Get the file where the progress indicator will be drawn.

Parameters

[in]	cex	c-style exception
[in]	bar	cgul_progress_bar instance

Returns

file

Referenced by cgul_progress_bar_cxx::get_file().

cgul_progress_bar__set_file()

CGUL_EXPORT void cgul_progress_bar__set_file	(	cgul_exception_t *	cex,
		cgul_progress_bar_t	bar,
		FILE *	f
	)

Set the file where the progress indicator will be drawn. By default, the progress indicator is drawn to stdout.

Parameters

[in]	cex	c-style exception
[in]	bar	cgul_progress_bar instance
[in]	f	file

Referenced by cgul_progress_bar_cxx::set_file().

cgul_progress_bar__update()

CGUL_EXPORT void cgul_progress_bar__update	(	cgul_exception_t *	cex,
		cgul_progress_bar_t	bar,
		double	progress,
		const char *	before,
		const char *	after
	)

Set the value used to indicated current progress. This is the method that makes the progress bar grow. The value of progress should be between the minimum and maximum values set by cgul_progress_bar__set_min() and cgul_progress_bar__set_max() respectively.

The actual percentage used when drawing the progress bar is rounded to the nearest percentage with the exception that 100% is not used until progress is greater than or equal to the maximum value.

If progress is less than the minimum value for the range, the minimum value will be used instead. If progress is greater than the maximum value for the range, the maximum value will be used instead.

If before or after is not NULL, the value or values that are not NULL will drawn in the correct location provided the style of the progress bar allows it. It is the responsibility of the client to make sure that before and after never get shorter; however, they can get longer.

If an error occurs while drawing the progress bar, an exception is throw. If the minimum value is set greater than or equal to the maximum value when this method is called, an exception is also thrown.

Parameters

[in,out]	cex	c-style exception
[in]	bar	cgul_progress_bar instance
[in]	progress	progress
[in]	before	custom text to draw before the progress bar
[in]	after	custom text to draw after the progress bar

Referenced by cgul_progress_bar_cxx::update().