BlackWaspTM

This web site uses cookies. By using the site you accept the cookie policy.This message is for compliance with the UK ICO law.

Windows Presentation Foundation
.NET 4.0+

WPF Information Controls - ProgressBar

The fortieth part of the Windows Presentation Foundation Fundamentals tutorial continues the examination of the WPF user information controls, which are non-interactive controls that provide user feedback. This article looks at progress bars.

Defining the Range

The default ProgressBar range of zero to one hundred is ideal if you are working with percentages. In other cases it may be useful to change the range, perhaps setting the maximum value to match the number of tasks that need to be completed for a process to finish. You can set the range using the Maximum and Minimum properties.

For example, update the ProgressBar's XAML element using the code below. This sets the minimum value to -10 and the maximum to 10.

<ProgressBar Name="Progress"
             Grid.Row="1"
             Grid.ColumnSpan="3"
             Height="25"
             Minimum="-10"
             Maximum="10"/>

To make sure that the Buttons still operate correctly, we need to change the code for the two events. The updated methods, shown below, use the Maximum and Minimum properties when deciding if the Value can be modified.

private void Decrement_Click(object sender, RoutedEventArgs e)
{
    if (Progress.Value > Progress.Minimum)
    {
        Progress.Value--;
    }
    SetProgressText();
}

private void Increment_Click(object sender, RoutedEventArgs e)
{
    if (Progress.Value < Progress.Maximum)
    {
        Progress.Value++;
    }
    SetProgressText();
}

Showing an Indeterminate Value

If a long-running process can vary in length, preventing the progress from being accurately indicated, you can set the ProgressBar to be indeterminate. In this state, the bar is continuously animated but does not give any indication of the amount of work completed or remaining. It can give users confidence that the program has not crashed during a very long process. To change to this mode, set the Boolean IsIndeterminate property to true.

To demonstrate we'll make the third button switch to the indeterminate mode. Start by modifying the Button's XAML, as follows:

<Button Click="Indeterminate_Click" Width="25" Height="25" Grid.Column="2">?</Button>

Next, add the code for the Click event behind the window.

private void Indeterminate_Click(object sender, RoutedEventArgs e)
{
    Progress.IsIndeterminate = !Progress.IsIndeterminate;

    if (Progress.IsIndeterminate)
        ProgressText.Content = "";
    else
        SetProgressText();
}

Finally, to make sure that the ProgressBar switches back to the standard view if the Value property is changed, update the private SetProgressText method:

private void SetProgressText()
{
    ProgressText.Content = Progress.Value;
    Progress.IsIndeterminate = false;
}

Run the program and click the "?" button to see the result. The window will appear as shown below, with the ProgressBar animating.

Indeterminate ProgressBar

ProgressBar Orientation

Most progress bars use horizontal strips of screen. However, it is possible to change the orientation of a ProgressBar control to vertical. When using this orientation the bar fills with colour from the bottom upwards. To change the orientation you can set the Orientation property. In XAML, simply change this to either "Horizontal" or "Vertical". If you need to set the property from code, you can use a value from the Orientation enumeration, which is found in the System.Windows.Controls namespace.

To demonstrate, replace all of the XAML for the window with the code below. This aligns the Buttons vertically, rather than horizontally, and places a vertical ProgressBar to the right.

<Window x:Class="ProgressBarDemo.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        Title="ProgressBar Demo"
        Width="80"
        Height="200">
    <Grid>
        <Grid.RowDefinitions>
            <RowDefinition/>
            <RowDefinition/>
            <RowDefinition/>
        </Grid.RowDefinitions>
        <Grid.ColumnDefinitions>
            <ColumnDefinition/>
            <ColumnDefinition Width="Auto"/>
        </Grid.ColumnDefinitions>

    <RepeatButton Click="Decrement_Click" Width="25" Height="25">-</RepeatButton>
    <RepeatButton Click="Increment_Click" Width="25" Height="25" Grid.Row="1">+</RepeatButton>
    <Button Click="Indeterminate_Click" Width="25" Height="25" Grid.Row="2">?</Button>

    <ProgressBar Name="Progress"
                 Orientation="Vertical"
                 Grid.Column="1"
                 Grid.RowSpan="3"
                 Width="25"
                 Minimum="-10"
                 Maximum="10"/>
    <Label Name="ProgressText"
           Content="0"
           HorizontalAlignment="Center"
           VerticalAlignment="Center"
           Grid.Row="1"
           Grid.Column="1"/>
    </Grid>
</Window>

The new layout will appear similar to that shown below:

Vertical ProgressBar

18 December 2013