WPF: Setting the accessible name on a button

2022-05-31

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 Content property is repurposed as the UIA Name property. If in your case, your Button does not have a helpful UIA Name property by default, special attention must be paid to ensure an appropriate UIA Name property is exposed by the control.

If the Button has an associated TextBlock control which describes the purpose of the Button, consider having the Button'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 Button. To have the UIA Name set in this way, set the Button's AutomationProperties.LabeledBy property to reference the labelling TextBlock.

If the Button has no associated TextBlock control, consider explicitly setting an accessible name on the Button through its AutomationProperties.Name property. This might be done for buttons which show an image or icon, or a specific unicode character whose font glyph has some visual meaning.

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 Button's accessible name from a contained TextBlock.

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

<Button AutomationProperties.LabeledBy="{Binding ElementName=StartPrimaryServerButtonLabel}"
    Margin="0 20 0 0">
    <StackPanel Orientation="Horizontal">
        <TextBlock>:)</TextBlock>
        <TextBlock Name="StartPrimaryServerButtonLabel" Text="{x:Static local:Resources.startprimaryserverbuttonlabel}" />
    </StackPanel>
</Button>

Code Sample 2: Setting the Button's accessible name from a nearby TextBlock.

<TextBlock Name="StartSecondaryServerButtonLabel" Text="{x:Static local:Resources.startsecondaryserverbuttonlabel}" />
<Button AutomationProperties.LabeledBy="{Binding ElementName=StartSecondaryServerButtonLabel}" ... />

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

Important: Be sure that your sighted customers can also efficiently learn of the purpose of a button that has no associated text label. For example, through use of a tooltip.

<Button AutomationProperties.Name="{x:Static local:Resources.startserverbutton}" ... />

Share via