WinForms: Setting the accessible name on a control

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 control, its announcement does not include the purpose of the control. 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. For some types of controls, the controls' Text property is repurposed as its UIA Name property. If this is not the case with your control, (for example, the control type is one of ComboBox, ListBox, ListView, PictureBox, ProgressBar, TabControl, TextBox, or TreeView,) special attention must be paid to ensure an appropriate UIA Name property is exposed by the control.

Note

If the control has an associated Label which describes the purpose of the control, consider having the control's UIA Name property set automatically from the Label's text. This approach avoids the need to add a localized string specifically for the accessible name of the control. To have the UIA Name set in this way, set the control's TabIndex property value such that it follows the Label's TabIndex property.

Important

In addition to providing a logical path for keyboard focus as your customer tabs through your UI, also provide a logical path for customers using a screen reader which follows the order of the elements exposed through the UIA tree. This may require a manual edit of the designer file to re-order the controls as they're added to the form.

If the control has no associated Label, consider explicitly setting an accessible name on the control through its AccessibleName property. This could be set through the control's Properties pane in Visual Studio or explicitly in code-behind. Either way, the AccessibleName text must be localized.

Note

If an AccessibleName property is set on a control through Visual Studio's Properties pane and later removed to allow a default accessible name to be set by WinForms, this can leave the designer file explicitly setting AccessibleName to an empty string. To prevent this, edit the designer file and remove the line which sets the AccessibleName to an empty string.

Code Sample: Setting the control's accessible name explicitly because it has no associated Label.

Important: Be sure that your sighted customers can also efficiently learn of the purpose of a control that has no associated text label.

this.myControl.AccessibleName = Resources.ResourceManager.GetString("MyControlAccessibleName");