WinForms: Setting helpful supplemental information 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 my customers using a screen reader encounter the button, the screen reader announces the button's Name and ControlType properties as exposed through the UI Automation (UIA) API, but some additional helpful information also needs to announced if my customer is to efficiently complete their task​.

Suggested Fix

Consider exposing the supplemental information through the Button.QueryAccessibilityHelp event handler.​ The string returned by the event handler is exposed through UIA as the HelpText property.

The second sample below shows how a custom Button class can also be used to have a specific UIA HelpText property exposed by a button, but this approach is not typically taken.

Note

At the time of writing this, attempts to expose supplemental information through the Button.AccessibleDescription property typically do not work. This is because the AccessibleDescription string value does not get exposed through the UIA properties that are commonly used for supplemental information, (for example, the UIA FullDescription or HelpText properties).

Code Sample 1: Exposing helpful supplemental information through the Button's QueryAccessibilityHelp event handler.

Important: Be sure that your sighted customers can also efficiently learn of helpful supplemental information associated with the Button.

public Form1()
{
    InitializeComponent();

    this.buttonSearch.QueryAccessibilityHelp += SearchButton_QueryAccessibilityHelp;
}

private void SearchButton_QueryAccessibilityHelp(object sender, QueryAccessibilityHelpEventArgs e)
{
    e.HelpString = Resources.ResourceManager.GetString("SearchButtonHelpText");
}

Code Sample 2: Override the Help property of a custom Button.

Important: Typically this approach would not be taken given the simplicity of the QueryAccessibilityHelp approach shown above.

// When the UI is created, create an instance of the Button whose Help property is to be overridden.
private void InitializeComponent()
{
    ...
    this.buttonProcess = new ButtonWithHelp();
}

// Create a custom button to have helpful descriptive information programmatically accessible. 
class ButtonWithHelp : Button
{
    public ButtonWithHelp()
    {
    }

    protected override AccessibleObject CreateAccessibilityInstance()
    {
        return new ButtonWithHelpAccessibleObject(this);
    }

    public class ButtonWithHelpAccessibleObject : ButtonBaseAccessibleObject
    {
        public ButtonWithHelpAccessibleObject(ButtonWithHelp owner) : base(owner)
        {
        }

        public override string Help
        {
            get
            {
                return Resources.ResourceManager.GetString("SearchButtonHelpText")
            }
        }
    }
}