Using the WP7 progress bar objects

Justin James looks at the methods and properties of Windows Phone 7 progress bar controls, and explores how to use the objects.

One feature that I touched on briefly in last month's Windows Phone 7 tip about making a countdown timer was the use of a ProgressBar control in my Lifter Calculator app. Typically, progress bars measure a "0% - 100%" range, but there is no reason why they have to; in fact, the progress bar controls in WP7 are very full featured.

Methods, properties, and usage

The WP7 progress bar is actually two controls: the ProgressBar control and the ProgressIndicator object (in this tip, progress bar will mean both objects as a group). The ProgressBar is a true control that you can put in your XAML to be displayed on the screen as you see fit, like a traditional progress bar. The ProgressIndicator is an object that you can work with programmatically, but you cannot put it in your XAML, because it gets displayed by the WP7 shell to put a progress bar in the system tray.

To create a ProgressIndicator object, you need to instantiate the object, and then call SystemTray.SetProgressIndicator and pass it your XAML codebehind class and the ProgressIndicator object:

var indicator = new ProgressIndicator
IsVisible = true,
IsIndeterminate = true,
Text = "Testing!"
SystemTray.SetProgressIndicator(this, indicator);

Make sure you have a "using Microsoft.Phone.Shell;" statement at the top.

ProgressIndicator has a property that ProgressBar doesn't -- the "Text" property, which displays text underneath the ProgressIndicator (Figure A). Figure A

An indeterminate ProgressIndicator with text set to "Testing!"
ProgressBar and ProgressIndicator support two modes controlled by the IsIndeterminate property. If IsIndeterminate is true, the progress bar does not change from one value to another, but displays the generic "something is happening" WP7 animation -- that is, the small dots moving across the screen (Figure B). If the property is false, the progress bar will allow a value to be set, and as the value is set, the progress bar will fill to be the right amount. As soon as you set IsIndeterminate to true, the bar starts its animation, and stops it as soon as you set it to false. Figure B

An indeterminate ProgressBar

A determinate progress bar has a value that can be set. With a ProgressIndicator, the Value property must be between 0 and 1, with 1 being "completely full." With a ProgressBar, you can set the Minimum and Maximum properties, and the Value that you set must be between those two numbers. As you change Value, the progress bar will fill to an appropriate amount. Speaking of "filling," you can set the "FlowDirection" property to either "LeftToRight" (the default) or "RightToLeft"; in LifterCalculator, I combined "RightToLeft" with a Value that went from Maximum to Minimum to provide the appearance of a bar counting down to zero, but moving from left to right at the same time.

And that is all there is to it! The two progress bar controls are very simple, but provide you with exactly what you need. The only drawback is the lack of a vertical mode, in the cases that one would make sense.