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

Name	Flag arguments	Argument type	Exclusive to	Comments
`push`	0	—	pop	Pushes a new operation onto the operation stack. The first call of an operation must use this flag.
`pop`	0	—	push, range, pos, step, text	Pops an operation off of the operation stack.
`range`	2	integer	pop	Sets 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.
`pos`	1	integer	pop, step	Sets the position of the operation at the top of the operation stack. If the operation stack is empty, the command fails.
`step`	0	—	pop, pos	Increments the position of the operation at the top of the operation stack by one. If the stack is empty, the command fails.
`text`	1	string	pop	Sets the text of the operation at the top of the operation stack. If the operation stack is empty, the command fails.
`noCancel`	0	—	—	Disables 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

createWindow