UWP XAML: Setting the localized control type on a custom 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 my custom control, its announcement includes the localized form of "custom", rather than the type of control. For my particular control, this is not helpful to my customer given that it doesn't convey the true nature of the data associated with the custom control.​​​​​

Suggested Fix

The localized text which is used to convey a control's type is conveyed through the control's LocalizedControlType property as exposed through the UI Automation (UIA) API. Standard UWP XAML controls have a LocalizedControlProperty which is appropriate to their UIA ControlType property. If your custom control is of a type unknown to UIA, your customer needs you to supply an appropriate LocalizedControlType string.

Consider providing a helpful LocalizedControlType property through the AutomationProperties.LocalizedControlType property.

Note

If your custom control's meaning is the same as a standard control, (for example, a Button,) consider replacing the custom control with the related standard control. If that is not practical, then if a custom AutomationPeer for the custom control has its GetControlTypeCore() method overridden to return a standard control type, then the LocalizedControlType will be automatically updated to match.

Important

If a custom control is exposed through UIA as having a standard control type, then it must support the associated UIA control patterns. For example, if a custom control exposes a control type of Button, than some action must be available programmatically. For example, it might be invokable, toggleable or expandable.

Note

The AutomationProperties.LocalizedControlType property is not available on versions of Windows 10 earlier than 14393. An app running on such a version of Windows can provide a helpful UIA LocalizedControlType property through use of a custom AutomationPeer for the control, and overriding the GetLocalizedControlTypeCore() method.

Code Sample

The localization steps for strings exposed through UIA are the same as that used for strings shown visually in the UWP XAML app. In this example the strings are associated through use of x:Uid.

<!-- This example shows a custom control using a custom class called "HeatMapControl". -->

<local:HeatMapControl x:Uid="MyControl" ... />

<!-- In the above example, the associated localized resource string might 
     be as follows:
  <data name="MyControl.AutomationProperties.LocalizedControlType" xml:space="preserve">
    <value>Heat Map</value>
  </data>
-->