WPF: Setting the accessible name on a progress bar

This article is referenced directly by Microsoft Accessibility Insights for Windows. Microsoft Accessibility Insights for Windows can help spotlight many accessibility issues in UI, and guide you to the relevant UI framework-specific code sample to help you resolve the issue. Learn more about Microsoft Accessibility Insights for Windows.

Problem

When a screen reader moves to the ProgressBar control, its announcement does not include the purpose of the ProgressBar. As such, my customer may be blocked from completing their task.

Suggested Fix

The purpose of a control is conveyed through the control's Name property as exposed through the UI Automation (UIA) API. The Name property must be accurate, concise, unambiguous and localized. By default for some types of WPF controls, the controls' Text or Content property is repurposed as the UIA Name property. These properties are not available for a ProgressBar control, and so special attention must be paid to ensure an appropriate UIA Name property is exposed by the control.

If the ProgressBar has an associated TextBlock control which describes the purpose of the ProgressBar, consider having the ProgressBar's UIA Name property set from the TextBlock's text. This approach avoids the need to add a localized string specifically for the accessible name of the ProgressBar.

If the ProgressBar has no associated TextBlock control, consider adding a TextBlock in order for your sighted customers to efficiently learn of the purpose of the ProgressBar, and then reference the TextBlock as described above. If that is not practical, explicitly set an accessible name on the ProgressBar through its AutomationProperties.Name property.

Note

While setting the accessible properties of a control is typically achieved through markup, in some situations it could be achieved through code-behind. Setting the accessible properties of a control in code-behind

Code Sample 1: Setting the ProgressBar's accessible name from a nearby TextBlock.

The localization steps for strings exposed through UIA are the same as that used for strings shown visually in the WPF app.

<TextBlock Name="DownloadProgressBarLabel" Text="{x:Static local:Resources.downloadprogressbarlabel}" />
<ProgressBar AutomationProperties.LabeledBy="{Binding ElementName=DownloadProgressBarLabel}" ... />

Code Sample 2: Setting the ProgressBar's accessible name explicitly because it has no associated TextBlock.

<ProgressBar AutomationProperties.Name="{x:Static local:Resources.downloadprogressbar}" ... />