CircularProgressBar
CircularProgressBar displays a ranged progress value using fluent animations. It is similar to a native linear ProgressBar, except that it renders the progress in a ring shape.
Circular progressbars can be an integral part of a dashboard display
Values
The CircularProgressBar control inherits RangeBase, which provides these essential properties:
| Property | Description |
|---|---|
Value |
The progress value between Minimum and Maximum. |
Minimum |
The minimum possible value. |
Maximum |
The maximum possible value. |
The resolved progress complete percentage is calculated with this formula:
Percentage = (Value - Minimum) / (Maximum - Minimum)
As the percentage changes, the progress indicator animates to the new value.
The following example demonstrates creating a CircularProgressBar with a range from 0 to 100 and a current value of 65:
xmlns:shared="http://schemas.actiprosoftware.com/winfx/xaml/shared"
...
<shared:CircularProgressBar Width="50" Height="50" Minimum="0" Maximum="100" Value="65" />
Indeterminate State
The progressbar can be placed in an indeterminate state when no specific progress value can yet be determined. This can be the case when first determining the number of steps that will be executed as part of an overall operation.
Circular progressbar spinning in an indeterminate state
Set the IsIndeterminate property to true to enter indeterminate state, and later back to false to exit it.
While in an indeterminate state, the progressbar will spin a small indicator around the ring, and no progress text will be displayed.
The following example demonstrates creating a CircularProgressBar in the indeterminate state:
xmlns:shared="http://schemas.actiprosoftware.com/winfx/xaml/shared"
...
<shared:CircularProgressBar Width="50" Height="50" IsIndeterminate="True" />
Subtle animations occur when the control transitions in and out of an indeterminate state.
Progress Text
Progress text can be displayed in the center of the ring when not in an indeterminate state. This text will be the percentage complete by default.
Hiding Progress Text
The progress text can be hidden by setting the IsProgressTextAllowed property to false.
Formatting Progress Text
A format string value in the ProgressTextFormat property is used to determinate what is displayed as progress text. This property defaults to the current culture's display format for percentages, resulting in a value such as "85%".
The format string is passed these values, which can be accessed via their zero-based indices:
| Index | Description |
|---|---|
| 0 | Value property value. |
| 1 | Percentage value in the range 0..100. |
| 2 | Minimum property value. |
| 3 | Maximum property value. |
A ProgressTextFormat value of "{0:0} of {3:0}" would result in the progress text "[Value] of [Maximum]", with all decimals rounded.
Warning
When specifying a custom ProgressTextFormat value in XAML, prefix the actual value with {} to ensure the XAML parser doesn't interpret the open curly braces of the format string as a meaningful XAML delimiter.
The following example demonstrates creating a CircularProgressBar with custom progress text:
xmlns:shared="http://schemas.actiprosoftware.com/winfx/xaml/shared"
...
<shared:CircularProgressBar Width="100" Height="100"
Minimum="0" Maximum="10" Value="4" ProgressTextFormat="{}{0:0} of {3:0}" />
Appearance
The appearance of the control can be fully customized.
Brush Properties
The following brush properties are available:
| Property | Description |
|---|---|
Foreground |
The progress text foreground. |
Background |
The background of the ring's interior, which defaults to Transparent. |
| IndicatorBrush | The progressbar's indicator fill. |
| TrackBrush | The progressbar's track fill. |
Line
The following line-related properties are available to adjust the indicator and track appearance:
| Property | Description |
|---|---|
| LineCap | The indicator line's end caps, which defaults to Round. |
| LineDashArray | The optional indicator line's dash array when dotted or dashed lines are desired. |
| LineDashOffset | The optional indicator line's dash offset, when a dash array is used. |
| LineThickness | The thickness of the indicator and track lines, which defaults to 4. |
Note
Implementing dashed lines requires some fine tuning based on the control's size and line thickness. Ideally, the dash array is configured so that a desired number of segments all have the same length. Then the dash offset is used to rotate the start and end gap space, so it aligns to the top of the control.
Font
All the standard font properties (e.g., FontFamily, FontSize, FontWeight) can be used to customize the appearance of the progress text.
Animation
Fluent animation in the control is enabled by default but can be disabled by setting the IsAnimationEnabled property to false.