Vicon Shogun banner

Description

Controls the progress bar displayed on Shogun Post's status bar.

To accommodate multiple, nested, and both user and internally created progress bars, Shogun Post uses the concept of an "operation stack". An operation is any arbitrary script section whose progress needs to be displayed as feedback to the user during script execution.

An operation is started by calling the command with the -push flag, which will create a new operation, and "push" it to the top of the stack. All subsequent calls to progressBar will act on this operation.

If the -push flag is not specified at the start of an operation, the command will error, because there will be no operation to act on. Conversely, to finish an operation, call the command with the -pop flag, which will remove the operation at the top of the stack. If -pop is called without a preceding and matching -push, the command will fail.

The concept of a stack allows multiple operations to be nested by pushing another operation onto the stack before popping the first one off. For example:

progressBar -push -text "Operation A";// Pushes Operation A 
progressBar -push -text "Operation B";// Pushes Operation B
progressBar -pop; // Pops Operation B
progressBar -pop; // Pops Operation A

Besides giving feedback to the user during lengthy operations, adding progressBar commands to your script also enables the user to cancel execution of the script using the Cancel button on the status bar. The Cancel button is disabled otherwise.

Functional area

Interface

Command syntax

Syntax

progressBar [-push] [-pop] [-range integer integer] [-pos integer] [-step] [-text string] [-noCancel]

Arguments

None

Flags

NameFlag argumentsArgument typeExclusive toComments
push0popPushes a new operation onto the operation stack. The first call of an operation must use this flag.
pop0push, range, pos, step, textPops an operation off of the operation stack.
range2integerpopSets the range of the operation at the top of the operation stack. The two integers specify the start and end of the range. If the operation stack is empty, the command fails.
pos1integerpop, stepSets the position of the operation at the top of the operation stack. If the operation stack is empty, the command fails.
step0pop, posIncrements the position of the operation at the top of the operation stack by one. If the stack is empty, the command fails.
text1stringpopSets the text of the operation at the top of the operation stack. If the operation stack is empty, the command fails.
noCancel0Disables the Cancel button so that the operation at the top of the operation stack cannot be canceled by the user.

Return value

void

Examples

// Demonstrate range setting, stepping, and nesting of operations
int $i, $j, $timeKiller, $maxI = 20, $maxJ = 2000;

// Push a new operation onto the stack.
progressBar -push -range 1 $maxI -text "Outer";

for( $i = 0;
$i < $maxI;
$i += 1 )
{
// This increments the "Outer" operation
progressBar -step;
// Kill some time so the stepping effect is visible.
$timeKiller = 0;
while( $timeKiller < 5000 )
{
$timeKiller += 1;
}
// Push another operation onto the stack, which nests
// this operation in the "Outer" one.
progressBar -push -range 1 $maxJ -text "Inner";
for( $j = 0;
$j < $maxJ;
$j += 1 )
{
// This increments the "Inner" operation
progressBar -step -text string( $j );
}
// This pops the "Inner" operation off the stack.
progressBar -pop;
}
// Finally, this pops the "Outer" operation off the stack.
progressBar -pop;

Additional information

Related commands