How to: Set the Value Displayed by the Windows Forms ProgressBar Control

The .NET Framework gives you several different ways to display a given value within the ProgressBar control. Which approach you choose will depend on the task at hand or the problem you are solving. The following table shows the approaches you can choose.

The most direct way to set the value displayed by a progress bar is by setting the Value property. This can be done either at design time or at run time.

To set the ProgressBar value directly

1. Set the ProgressBar control's Minimum and Maximum values.

2. In code, set the control's Value property to an integer value between the minimum and maximum values you have established.

   Note

   If you set the Value property outside the boundaries established by the Minimum and Maximum properties, the control throws an ArgumentException exception.

   The following code example illustrates how to set the ProgressBar value directly. The code reads records from a data source and updates the progress bar and label every time a data record is read. This example requires that your form has a Label control, a ProgressBar control, and a data table with a row called CustomerRow with FirstName and LastName fields.

   Public Sub CreateNewRecords()  
      ' Sets the progress bar's Maximum property to  
      ' the total number of records to be created.  
      ProgressBar1.Maximum = 20  
   
      ' Creates a new record in the dataset.  
      ' NOTE: The code below will not compile, it merely  
      ' illustrates how the progress bar would be used.  
      Dim anyRow As CustomerRow = DatasetName.ExistingTable.NewRow  
      anyRow.FirstName = "Stephen"  
      anyRow.LastName = "James"  
      ExistingTable.Rows.Add(anyRow)  
   
      ' Increases the value displayed by the progress bar.  
      ProgressBar1.Value += 1  
      ' Updates the label to show that a record was read.  
      Label1.Text = "Records Read = " & ProgressBar1.Value.ToString()  
   End Sub  
   

   public void createNewRecords()  
   {  
      // Sets the progress bar's Maximum property to  
      // the total number of records to be created.  
      progressBar1.Maximum = 20;  
   
      // Creates a new record in the dataset.  
      // NOTE: The code below will not compile, it merely  
      // illustrates how the progress bar would be used.  
      CustomerRow anyRow = DatasetName.ExistingTable.NewRow();  
      anyRow.FirstName = "Stephen";  
      anyRow.LastName = "James";  
      ExistingTable.Rows.Add(anyRow);  
   
      // Increases the value displayed by the progress bar.  
      progressBar1.Value += 1;  
      // Updates the label to show that a record was read.  
      label1.Text = "Records Read = " + progressBar1.Value.ToString();  
   }  
   

   If you are displaying progress that proceeds by a fixed interval, you can set the value and then call a method that increases the ProgressBar control's value by that interval. This is useful for timers and other scenarios where you are not measuring progress as a percentage of the whole.

To increase the progress bar by a fixed value

1. Set the ProgressBar control's Minimum and Maximum values.

2. Set the control's Step property to an integer representing the amount to increase the progress bar's displayed value.

3. Call the PerformStep method to change the value displayed by the amount set in the Step property.

   The following code example illustrates how a progress bar can maintain a count of the files in a copy operation.

   In the following example, as each file is read into memory, the progress bar and label are updated to reflect the total files read. This example requires that your form has a Label control and a ProgressBar control.

   Public Sub LoadFiles()  
      ' Sets the progress bar's minimum value to a number representing  
      ' no operations complete -- in this case, no files read.  
      ProgressBar1.Minimum = 0  
      ' Sets the progress bar's maximum value to a number representing  
      ' all operations complete -- in this case, all five files read.  
      ProgressBar1.Maximum = 5  
      ' Sets the Step property to amount to increase with each iteration.  
      ' In this case, it will increase by one with every file read.  
      ProgressBar1.Step = 1  
   
      ' Dimensions a counter variable.  
      Dim i As Integer  
      ' Uses a For...Next loop to iterate through the operations to be  
      ' completed. In this case, five files are to be copied into memory,  
      ' so the loop will execute 5 times.  
      For i = 0 To 4  
         ' Insert code to copy a file  
         ProgressBar1.PerformStep()  
         ' Update the label to show that a file was read.  
         Label1.Text = "# of Files Read = " & ProgressBar1.Value.ToString  
      Next i  
   End Sub  
   

   public void loadFiles()  
   {  
      // Sets the progress bar's minimum value to a number representing  
      // no operations complete -- in this case, no files read.  
      progressBar1.Minimum = 0;  
      // Sets the progress bar's maximum value to a number representing  
      // all operations complete -- in this case, all five files read.  
      progressBar1.Maximum = 5;  
      // Sets the Step property to amount to increase with each iteration.  
      // In this case, it will increase by one with every file read.  
      progressBar1.Step = 1;  
   
      // Uses a for loop to iterate through the operations to be  
      // completed. In this case, five files are to be copied into memory,  
      // so the loop will execute 5 times.  
      for (int i = 0; i <= 4; i++)  
      {  
         // Inserts code to copy a file  
         progressBar1.PerformStep();  
         // Updates the label to show that a file was read.  
         label1.Text = "# of Files Read = " + progressBar1.Value.ToString();  
      }  
   }  
   

   Finally, you can increase the value displayed by a progress bar so that each increase is a unique amount. This is useful when you are keeping track of a series of unique operations, such as writing files of different sizes to a hard disk, or measuring progress as a percentage of the whole.

To increase the progress bar by a dynamic value

1. Set the ProgressBar control's Minimum and Maximum values.

2. Call the Increment method to change the value displayed by an integer you specify.

   The following code example illustrates how a progress bar can calculate how much disk space has been used during a copy operation.

   In the following example, as each file is written to the hard disk, the progress bar and label are updated to reflect the amount of hard-disk space available. This example requires that your form has a Label control and a ProgressBar control.

   Public Sub ReadFiles()  
      ' Sets the progress bar's minimum value to a number
      ' representing the hard disk space before the files are read in.  
      ' You will most likely have to set this using a system call.  
      ' NOTE: The code below is meant to be an example and  
      ' will not compile.  
      ProgressBar1.Minimum = AvailableDiskSpace()  
      ' Sets the progress bar's maximum value to a number
      ' representing the total hard disk space.  
      ' You will most likely have to set this using a system call.  
      ' NOTE: The code below is meant to be an example
      ' and will not compile.  
      ProgressBar1.Maximum = TotalDiskSpace()  
   
      ' Dimension a counter variable.  
      Dim i As Integer  
      ' Uses a For...Next loop to iterate through the operations to be  
      ' completed. In this case, five files are to be written to the disk,  
      ' so it will execute the loop 5 times.  
      For i = 1 To 5  
         ' Insert code to read a file into memory and update file size.  
         ' Increases the progress bar's value based on the size of
         ' the file currently being written.  
         ProgressBar1.Increment(FileSize)  
         ' Updates the label to show available drive space.  
         Label1.Text = "Current Disk Space Used = " &_
         ProgressBar1.Value.ToString()  
      Next i  
   End Sub  
   

   public void readFiles()  
   {  
      // Sets the progress bar's minimum value to a number
      // representing the hard disk space before the files are read in.  
      // You will most likely have to set this using a system call.  
      // NOTE: The code below is meant to be an example and
      // will not compile.  
      progressBar1.Minimum = AvailableDiskSpace();  
      // Sets the progress bar's maximum value to a number
      // representing the total hard disk space.  
      // You will most likely have to set this using a system call.  
      // NOTE: The code below is meant to be an example
      // and will not compile.  
      progressBar1.Maximum = TotalDiskSpace();  
   
      // Uses a for loop to iterate through the operations to be  
      // completed. In this case, five files are to be written  
      // to the disk, so it will execute the loop 5 times.  
      for (int i = 1; i<= 5; i++)  
      {  
         // Insert code to read a file into memory and update file size.  
         // Increases the progress bar's value based on the size of
         // the file currently being written.  
         progressBar1.Increment(FileSize);  
         // Updates the label to show available drive space.  
         label1.Text = "Current Disk Space Used = " + progressBar1.Value.ToString();  
      }  
   }  
   

See also

• ProgressBar
• ToolStripProgressBar
• ProgressBar Control Overview
• ProgressBar Control