WinForms: Setting the accessible name on a button

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 Button control, its announcement does not include the purpose of the Button. 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, a Button's Text property is repurposed as the UIA Name property. If your Button has an empty Text property, special attention must be paid to ensure an appropriate UIA Name property is exposed by the control.

If the Button has an associated Label control which describes the purpose of the Button, consider having the Button'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 Button. To have the UIA Name set in this way, set the Button'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 Button has no associated Label control, consider explicitly setting an accessible name on the Button through its AccessibleName property. This could be set through the Button'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 Button'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 button that has no associated text label.

this.buttonSearch.AccessibleName = Resources.ResourceManager.GetString("SearchButtonAccessibleName");