This file documents the [progressBar] command introduced in version 8.1 of AlphaX.

Introduction
Synopsis
- The [configure] subcommand
- The [hide] subcommand
- The [show] subcommand
Examples

Introduction

The [progressBar] command lets you interact with the progress bar located at the right of the global 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 global status bar. Version 8.1 of AlphaX also introduces a per-window small asynchronous progress indicator located in the bottom right corner of the message bar (see the [setWinInfo] command 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 additionnally 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 to have 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 simply:

 
     progressBar hide

The [show] subcommand

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

 
     progressBar show

Examples

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

 progressBar show

 progressBar hide

 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 -value 25

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 some action here
 }
 progressBar hide

(add your comments here...)

bd In some cases, it may be sufficient to display an asynchronous progress indicator at the document level. The ProgressIndicators page explains how to do that.