The [progressBar] command.

Introduction

The progressBar command lets you interact with the progress bar located in the right part of the main status bar. It is possible to show or hide this progress bar, and modify some of its attributes. By default, the progress bar is invisible.
Progress indicators inform users about the status of lengthy operations. There are three types of progress indicators:

Determinate progress bar: Used when the full length of an operation can be determined and you can tell the user how much of the process has been completed. You could use a determinate progress indicator to show the progress of a file conversion, for example.
Indeterminate progress bar: Used when the duration of a process can't be determined. You might use an indeterminate progress indicator to let the user know that the application is attempting a dial-up communication connection, for example, when there's no way to accurately determine how long it will take to complete.
Asynchronous progress indicator: Used when space is very constrained. These indicators are best used for asynchronous events that take place in the background, such as retrieving messages from a server.

The [progressBar] command implements the first two types of indicators by displaying a progress bar in the main status bar. There is also a small per-window asynchronous progress indicator located in the bottom right corner of the message bar of the document windows: this indicator is not handled by the present command, see instead the command [setWinInfo] with the busy property.
Note that if an indeterminate process reaches a point where its duration can be determined, one can easily switch to a determinate progress indicator.

Synopsis

The formal syntax of the [progressBar] command is:

progressBar subcommand ?options?

The possible subcommands are described below. Depending on the subcommand, various options can be additionally specified.

The [configure] subcommand

There are two forms for the syntax of this subcommand:

progressBar configure option
progressBar configure option value ?option value...?

The first form returns the value of the option specified as the third argument. The second form lets you set the value of different options.
Here is the description of the currently available options:

the -determinate option lets you specify the type of the progress bar (determinate or indeterminate). In a determinate progress bar, the "fill" moves from left to right and should fill in completely before it is dismissed. An indeterminate progress bar displays a spinning striped cylinder to indicate an ongoing process. The possible values for the -determinate option are 0 or 1. The default initial value is 0 (indeterminate).
the -label option concerns determinate progress bars only. It lets you specify whether the value of the progress bar should be displayed or not. If it is set to 1, the value (followed by a percent sign) is displayed on the right hand side. The possible values for this option are 0 or 1. The default initial value is 0. In the case of an indeterminate progress bar, there is no label.
the -value option concerns determinate progress bars only. It lets you specify the value of the progress bar. The value should be an integer between 0 and 100. If the progress bar is of type indeterminate, this option is ignored.

Caution: swtiching to indeterminate automatically resets the value of the -label option to 0. So, the following two instructions are not equivalent:

progressBar configure -determinate 1 -label 1
progressBar configure -label 1 -determinate 1

Actually, the second one will result in the -label option having value 0 since the arguments are parsed from left to right.

The [hide] subcommand

This command lets you hide the progress bar. The syntax is:

    progressBar hide

The [show] subcommand

This subcommand is the opposite of the [progressBar hide] subcommand. It lets you display the progress bar if it is hidden. The syntax is:

    progressBar show

The [visible] subcommand

This command tells whether the progress bar is currently visible or not. The syntax is:

    progressBar visible

Examples

Here are a few basic examples which can be executed from the Tcl shell in Alpha:

progressBar show

progressBar configure -determinate

progressBar configure -determinate 0
progressBar configure -determinate 1

progressBar configure -label

progressBar configure -label 0
progressBar configure -label 1

progressBar configure -value

progressBar configure -determinate 1 -value 25 -label 1

progressBar hide

Here is a small code snippet demonstrating how to use the progress bar during a lengthy operation;

progressBar configure -determinate 1 -label 1
progressBar show
for {set i 0} {$i <= 100} {incr i} {
	progressBar configure -value $i
	# do something here
}
progressBar hide

Last updated 2019-11-27 14:13:08