SAPIEN Technologies

The “Spotlight on Controls” series focuses on a single WinForms control in PrimalForms 2011 , details the important Properties, Methods, and Events of the control and demonstrates how to utilize the control. Most of the information about the controls is still applicable to previous versions of PrimalForms.

Last time we took a look at the RadioButton control. This time we will look at the ProgressBar control:

ProgressBar Control [System.Windows.Forms.ProgressBar]

Represents a Windows progress bar control.

Default Event: Click

Why use a ProgressBar control?

Use a ProgressBar when you need to show the user that progress is being made in some operation, such as copying files.

Important Properties:

Maximum

The Maximum is the upper bound of the range this ProgressBar is working with.

Why use the Maximum property?

Use the Maximum property when you have a known limit for your ProgressBar. When the Value property is equal to the value of the Maximum property, the progress bar is completely filled.

Example of setting the Maximum property in the Script Editor:

$progressbar1.Maximum = $files.Count

Values (Default: 100):

Any Integer value [Int32]

Minimum

The Minimum is the lower bound of the range this ProgressBar is working with. When the Value property is equal to the value of the Minimum property, the ProgressBar will be empty.

Values (Default: 0):

Any Integer value [Int32]

Step

The Step is the amount to increment the current value of the ProgressBar by when the PerformStep() method is called.

Why use the Step property?

Use the Step property to specify the amount that each completed task in an operation changes the value of the progress bar.  The Step property default value is 10, so you may want to set the step to 1 when necessary.

Values (Default: 10):

Any Integer value [Int32]

Style

This property allows the user to set the style of the ProgressBar.

Why use the Style property?

Use the style property when you want to change the way  ProgressBar is displayed or in cases where you have an unknown amount of increments (See Marquee style).

Values (Default: Blocks ):

Blocks
Indicates progress by increasing the number of segmented blocks in a ProgressBar.

(Windows 7)

(Windows XP)

Continuous
Indicates progress by increasing the size of a smooth, continuous bar in a ProgressBar. Since PrimalForms enables VisualStyles by default, Continuous will resemble Blocks style.

Marquee
Indicates progress by continuously scrolling a block across a ProgressBar in a marquee fashion. Use Marquee when you can’t specify a quantity of progress, but still need to indicate that progress is being made. Use the MarqueeAnimationSpeed property to control the speed of the ProgressBar.

(Windows 7)

(Windows XP)

Value

The current value of the ProgressBar, in the range specified by the Minimum and Maximum properties.

Why use the Value property?

Use the Value property if you want to set the progress at a specific point or to obtain the current position of the ProgressBar .

Values (Default: 0):

Any Integer value [Int32]

MarqueeAnimationSpeed

This property indicates the speed of the marquee animation in milliseconds. The ProgressBar’s Style must be set to Marquee in order to use this property.

Why use the MarqueeAnimationSpeed property?

Use the MarqueeAnimationSpeed property if you want to change the speed of the ProgressBar ’s animation or to pause the marquee by setting the speed to 0.

To clear the Marquee, it is recommended to change the Style property to Block and set the Value property to 0.

Values (Default: 100):

Any Integer value [Int32] (In milliseconds)

Important Methods:

Increment

This method advances the current position of the ProgressBar by the specified amount.

Why use the Increment method?

Use the Increment method when you need to increment the value of the ProgressBar by varying amounts.  This method of incrementing the ProgressBar is similar to using the Step property with the PerformStep method. Setting the Step property is not necessary when using the Increment method.

Example of using Increment method in the script editor:

$progressbar1.Increment(1)

PerformStep

This method advances the current value of the ProgressBar by the amount of the Step property.

Why use the PerformStep method?

Use the PerformStep method when repeatedly incrementing the ProgressBar by the same amount (i.e., the value set in the Step property).

 

Here is a sample script block triggered by a button, that displays its progress as it creates a backup of all the text files located in a folder specified by the user:

$buttonBackupFiles_Click={
    #Back up Text files from a selected directory
    if($folderbrowserdialog1.ShowDialog() -eq 'OK')
    {
        $selectedPath = $folderbrowserdialog1.SelectedPath
        
        #Get all the text files in the folder
        $files = Get-ChildItem $selectedPath -Filter *.txt

        if($files -eq $null -or $files.Count -eq 0)
        {
            #No files to backup
            return    
        }
        
        #Initialize the Progress Bar
        $progressbar1.Maximum = $files.Count
        $progressbar1.Step = 1
        $progressbar1.Value = 0
        
        #Create the Backup Folder
        $destination = ('{0}\\Backup' -f $selectedPath)
        [System.IO.Directory]::CreateDirectory($destination)
        
        #Copy the files and update the progress bar
        foreach ($file in $files){    
            Copy-Item ('{0}\\{1}' -f $selectedPath, $file) -Destination $destination
            $progressbar1.PerformStep()
        }
    }
}