CLI_Progress implements a command line progress bar in the IDL Workbench console or when running IDL in a terminal.

Note: Because CLI_Progress takes over the IDL standard output, you should not do any other output (using print for example) while the progress bar is in effect. In addition, only one command-line progress bar can be running at a time.

Example

Initialize a CLI_Progress bar with a title and maximum length. Then run the progress bar in a loop.

length = 1000 ; for example, file length in bytes

cli_progress.initialize, title = 'Download', maximum = length

for i=0,length do begin & $

  cli_progress.update, i & $

  wait,0.01 & $

endfor

IDL prints:

Download 100% [########################################]

For more examples see CLI_Progress Examples.

Methods

CLI_Progress:Initialize

The CLI_Progress::Initialize static method sets up a new progress bar and allows you to set multiple properties.

Syntax

CLI_Progress.Initialize, AUTO_FINISH=0|1, COMPLETE_CHAR=string, INCOMPLETE_CHAR=string, MAXIMUM=value, PERCENT=0|1, /PING_PONG, PRESET=string, /REMAINING, /REVERSE, SPINNER=integer, TEXT=string, TITLE=string, WIDTH=integer

Arguments

None

Properties

For an example of setting properties see Setting and Using Properties.

AUTO_FINISH

By default, when the progress bar reaches its maximum, the progress bar will automatically "complete", sending the cursor to the next line and returning control to the user. If this property is set to false (0), then when the progress bar reaches its maximum, the bar will not send the cursor to the next line but will instead keep the cursor captured and wait for a CLI_Progress::Finish call. The default is true (1).

COMPLETE_CHAR

Set this property to a string containing the character (or characters) to use for the "completed" portion of the progress bar. The default is a single hash, "#".

Tip: When using a PING_PONG bar this property will be used for the string that gets bounced back and forth.

Note: COMPLETE_CHAR, INCOMPLETE_CHAR, and WIDTH are unaware of each other. For example, if you want to use a two-character COMPLETE_CHAR you should also use a two-character INCOMPLETE_CHAR or else the progress bar will grow in length with each call to CLI_Progress::Update. In this example, the progress bar will also have a width that is twice the value of the WIDTH property.

INCOMPLETE_CHAR

Set this property to a string containing the character (or characters) to use for the "incomplete" portion (the background) of the progress bar. The default is a single dash, "–".

Note: COMPLETE_CHAR, INCOMPLETE_CHAR, and WIDTH are unaware of each other. For example, if you want to use a two-character COMPLETE_CHAR you should also use a two-character INCOMPLETE_CHAR or else the progress bar will grow in length with each call to CLI_Progress::Update. In this example, the progress bar will also have a width that is twice the value of the WIDTH property.

MAXIMUM

Set this property to an integer giving the maximum value for the progress bar. Once the progress bar reaches this maximum then the bar will "complete", sending the cursor to the next line and returning control to the user. To disable this auto complete see AUTO_FINISH. It also factors into how CLI_Progress determines the completeness of your bar and how the PERCENT keyword is calculated. The default is 100.

Note: A ping pong bar defines its Maximum to INF by default. This can be changed.

PERCENT

By default the progress bar automatically displays the percent completed at the front of the progress bar. Set to false (0) to suppress the percentage. The default is true (1) for normal progress bars and false for ping pong bars.

PERCENT will add decimal places depending on the size of MAXIMUM.
For maximum values: 100-999 it will use 1 decimal place (e.g., 0.8%), 1000-9999 it will use 2 decimal places (e.g., 0.75%), 10000 it will use 3 decimal places (e.g., 0.750%).

Note: Because a ping pong bar has no inherent maximum the percent property does not work on ping pong bars unless you also define a MAXIMUM.

PING_PONG

By default, the progress bar displays a normal progress from incomplete to complete, along with a percentage. Instead you can set the PING_PONG property to true (1) to convert the progress bar to a "ping pong" bar (also known as a marquee loading bar). The ping pong bar shows progress through bouncing a character (or set of characters) back and forth from one end of the bar to the other. The ping pong bar will not end until the CLI_Progress::Finish method is called.

Note: Because a ping pong bar has no inherent maximum the PERCENT property will not work on ping pong bars unless you also define a MAXIMUM.

PRESET

Set this property to a string to specify a pre-canned property bar. Using one of these presets will automatically set multiple properties. You can also combine one of the preset values with additional properties or even override one of the preset properties. Possible values are:

[|]  30% [============----------------------------]						

30% [◆◆◆◆◆◆◆◆◆◆◆◆◇◇◇◇◇◇◇◇◇◇◇◇◇◇◇◇◇◇◇◇]

30% [████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░]

30% [■■■■■■■■■■■■                            ]

[------------------------------<>----------]					

REVERSE

Reverse is a PING_PONG only keyword.
Normally, for ping pong bars the ping pong string (set via the COMPLETE_CHAR property) will simply bounce back and forth unchanged. Set REVERSE to true (1) to force the ping pong string to be reversed when traveling from right to left. This is useful for ping pong strings that have a definite "head" and "tail".

SPINNER

Set this property to an integer giving the default "spinner value". The spinner is displayed to the left of the progress bar. Each call to CLI_Progress::Update will automatically cycle through the spinner characters, giving the illusion of a "busy" indicator. Possible values are:

TEXT

Set this property to a string containing the text description for the progress bar. The text is displayed to the right of the progress bar. The default is an empty string.

TITLE

Set this property to a string containing the title for the progress bar. The title is displayed to the left of the progress bar. The default is an empty string.

WIDTH

Set this property to an integer giving the width of the progress bar in characters. This width is just for the characters within the square brackets, and does not include the title or percentage. The default is 40.

REMAINING

Set this property to display the remaining time at the end of your progress bar, positioned before your TEXT. The approximate remaining time is automatically computed after each update. See example.

Tip: For a more precise estimation, space your updates evenly throughout the execution of your code.

CLI_Progress::Update

The CLI_Progress::Update static method updates the progress bar.

Syntax

CLI_Progress.Update [, Progress, OUTPUT=variable] [, TEXT=string]

Arguments

PROGRESS

The optional progress argument specifies the current completeness of the progress bar. This progress value should be relative to the value of the MAXIMUM property. If Progress is not specified then CLI_Progress will be incremented by 1.

Keywords

OUTPUT

Set this keyword to a named variable to skip printing. If OUTPUT is present then the intended output will be written to this variable instead. See example

TEXT

Set this keyword to a string giving the new value for the TEXT property, which is output to the right of the progress bar.

CLI_Progress::Finish

The CLI_Progress::Finish static method updates the progress bar to the "complete" state, sending the cursor to the next line and returning control to the user. If the progress bar is already finished then calling CLI_Progress::Finish will have no effect.

Syntax

CLI_Progress.Finish [, OUTPUT=variable] [, TEXT=string]

Arguments

None

Keywords

OUTPUT

Set this keyword to a named variable to skip printing. If OUTPUT is present then the intended output will be written to this variable instead. See example.

TEXT

Set this keyword to a string giving the new value for the TEXT property, which is output to the right of the progress bar.

CLI_Progress::NewLine

The CLI_Progress::NewLine static method outputs a newline to the console.

Tip: While the progress bar is active, the cursor is temporarily frozen until the bar finishes. You can use this method to output a newline, perhaps before outputting some additional information.

Note: If you resume using the progress bar, the progress bar will continue on the next line; it will not return to the original progress bar line.

Syntax

CLI_Progress.Newline

Arguments

None

Keywords

None

CLI_Progress::Erase

The CLI_Progress::Erase static method will erase the progress bar and return the cursor to the start of the line.

Syntax

CLI_Progress.Erase

Arguments

None

Keywords

None

Version History

See Also

CLI_Progress Examples