Quickstart: adding progress controls (XAML)

[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]

Progress controls provide a way for you to indicate that your app is performing work, such as downloading images, loading files, or processing data. Here are the different progress control styles and how to add them to a Windows Runtime app using C++, C#, or Visual Basic.

Roadmap: How does this topic relate to others? See:

• Roadmap for Windows Runtime apps using C# or Visual Basic
• Roadmap for Windows Runtime apps using C++

Objective: To use progress controls to a Windows Runtime app using C++, C#, or Visual Basic.

Prerequisites

We assume that you can add controls to a basic Windows Runtime app using C++, C#, or Visual Basic. For instructions on adding a control, see Quickstart: Adding controls and handling events.

Instructions

1. Choosing a progress control style

There are 3 styles of progress controls that indicate to the user when the amount of work to complete is known, when it isn’t, and whether the task is modal: the determinate progress bar style, the indeterminate progress bar style, and the indeterminate ring style.

Determinate progress bar: Shows how much progress the app has made. As work progresses, a fill color expands from left to right until it fills the progress bar. It doesn't indicate whether the user can interact with the app like the indeterminate styles do.
Indeterminate progress bar: Indicates that users can interact with the UI while the task continues. In the animation, dots appear on the left and move to the right along a track until they reach the end of the track and disappear.
Indeterminate progress ring : Indicates that user activity is blocked until the app completes the task, that is, the activity is modal. In the animation, several dots move clockwise in a circle.

2. Adding a determinate progress bar

A determinate progress bar shows how much progress the app has made. As work progresses , the bar fills up. If you can estimate remaining amount of work in time, bytes, files, or some other quantifiable units of measure, use a determinate progress bar.

The progress bar provides 3 properties for setting and determining progress:

To create a determinate progress bar

1. Add a ProgressBar control to your app.
2. Set the IsIndeterminate property to false. This is the default value.
3. If you don't want to use the default completion value of 1.0, you can change it by setting the Maximum property.
4. Set the Value property to show progress.

This example creates a determinate progress bar and sets its Value to 30 and its Maximum to 100. The resulting progress bar shows that progress is 30% complete.

<ProgressBar IsIndeterminate="False" Maximum="100" Value="30" Height="10" Width="200"/>

The previous example showed how to specify the value of a progress bar in markup. In a real app, you use procedural code or data binding to update the value of the progress bar as a response to some indicator of progress. For example, if your progress bar indicates how many files have been downloaded, you update the value each time another file is downloaded.

To update the value of a determinate progress bar

1. To update the Value of the ProgressBar in code, give the ProgressBar a name, and refer to it by name in your code.

   This example updates the value of a the progress bar in code.

   <ProgressBar x:Name="progressBar1" IsIndeterminate="False" Maximum="100" Height="10" Width="200"/>
   

   progressBar1.Value = progressPercent;
   

2. To update the Value through data binding, bind the Value property to a bindable property in your app.

   This example updates the value of a the progress bar though data binding.

   <ProgressBar IsIndeterminate="False" Maximum="100" Value="{Binding ProgressPercent}" Height="10" Width="200"/>
   

3. Adding an indeterminate progress bar

When you can't estimate how much work remains to finish a task and the task doesn't block user interaction, use an indeterminate progress bar. Instead of showing a bar that fills up as progress completes, an indeterminate progress bar shows an animation of dots moving from left to right.

To create an indeterminate progress bar

1. Add a ProgressBar control to your app.
2. Set the IsIndeterminate property to true.

This example creates an indeterminate progress bar.

<ProgressBar IsIndeterminate="True" Height="10" Width="200"/>

4. Adding an indeterminate progress ring

When you can't estimate how much work remains to finish a task and the task does block user interaction, use an indeterminate progress ring. An indeterminate progress ring shows an animate sequence of dots moving in a circle.

To create an indeterminate progress ring

1. Add a ProgressRing control to your app.
2. Set the IsActive property to true.

This example creates an indeterminate progress ring.

<ProgressRing IsActive="True"/>

Summary and next steps

You learned how to create different types of progress controls.

See Guidelines for progress controls for more detail about when and how to use progress controls.

Related topics

Roadmap for Windows Runtime apps using C# or Visual Basic

Roadmap for Windows Runtime apps using C++