WinForms: Setting the accessible name on a tree

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 into a tree and is configured to announce both the tree item and the name of the tree containing the item, its announcement does not include the name of the tree. The fact that my customer is not made aware of exactly which tree they've encountered, can disrupt the flow of 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 WinForms controls, the controls' Text property is repurposed as the UIA Name property. This is not the case for a TreeView.

If the tree has an associated Label control which describes the purpose of the tree, consider having the tree'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 tree. To have the UIA Name set in this way, set the tree's TabIndex property value such that it follows the Label's TabIndex property.

Note

The use of the label to set an accessible name on the tree works even if the Label has a Visible property of False. In that case, WinForms will not expose the label visually or programmatically through UIA, yet still leverage it as the accessible name of the edit control that follows it. Note that typically the label is shown visually in order to provide the best possible experience for your sighted customers.

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 tree has no associated Label control, consider adding a Label in order for your sighted customers to efficiently learn of the purpose of the tree. If that is not practical, explicitly set an accessible name on the tree through its AccessibleName property. This could be set through the tree'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

// The accessible name can be set using Visual Studio's Properties pane, and can be
// localized in the same manner as that for Labels which are presented visually.

// This example has a tree which presents a tree of server machines, and its accessible name is
// set in C# from the localized string resource whose name is "ServerTreeAccessibleName".

// Note: The name should not include the control type, and so the name would not 
// include the text "tree" in this case.

this.serverTree.AccessibleName = Resources.ResourceManager.GetString("ServerTreeAccessibleName");