Providing Accessibility Information in a .NET Windows Forms application

Windows Forms applications provide two mechanisms for providing accessibility information.

In many cases the required accessibility information can be provided using the following properties of the Control Class in the System.Windows.Forms Namespace: the Control.AccessibleDefaultActionDescription Property, the Control.AccessibleDescription Property, the Control.AccessibleName Property, and the Control.AccessibleRole Property. This feature is almost enough to meet WCAG Success Criterion 4.1.2: Name, Role, Value. WCAG Success Criterion 4.1.2: Name, Role, Value requires that state information be provided as well. Unfortunately, there is not a property in the Control Class for state information.

In many cases, the built in Windows Forms support is sufficient and therefore there is no need to specifically provide state information.

If you do need to provide state information, it will take a bit more effort. In this case, you will need to use the AccessibleObject Class and the Control.CreateAccessibilityInstance Method.

Using the Accessible* Properties of the Control Class

The following code demonstrates the use of the Control.AccessibleDescription Property and the Control.AccessibleName Property of the Control Class.

public MyForm()
{
   // Create a 'MyCheckBox' control and 
   // display an image on it.
   MyCustomControls.MyCheckBox myCheckBox = new MyCustomControls.MyCheckBox();
   myCheckBox.Location = new Point(5,5);
   myCheckBox.Image = Image.FromFile(
     Application.CommonAppDataPath + "\\Preview.jpg");

   // Set the AccessibleName property
   // since there is no Text displayed.
   myCheckBox.AccessibleName = "Preview";
   myCheckBox.AccessibleDescription = "A toggle button used to show the document preview.";
   this.Controls.Add(myCheckBox);
}

In this case, the checkbox object provides the state. However, since an image is used instead of text, it does not provide the name. Therefore the Control.AccessibleDescription Property and the Control.AccessibleName Property of the Control Class are used. In addition, these properties suffice to meet WCAG Success Criterion 4.1.2: Name, Role, Value.

References

Using Direct Annotation in C++

Sometimes you will encounter a situation in which the existing accessibility support for an user interface element is almost good enough and you need to just make small changes to the existing support. For example, perhaps you just need to override the Name or Role properties. In these cases, fully implementing the IAccessible interface as described in Implementing a Microsoft Active Accessibility (MSAA) Server Using the Windows API and C++ may seem like a great deal of effort to achieve these improvements.

Fortunately, starting with Windows 7 there is an easier alternative, the Direct Annotation feature of the Dynamic Annotation API. The Dynamic Annotation API is extension to Microsoft Active Accessibility that makes it possible to customize existing IAccessible support without using subclassing or wrapping techniques. Direct Annotation is one of several features provided by the Dynamic Annotation API; it is the simplest of the features provided.

Direct Annotation makes it possible to customize the following properties.

Since Name, Role, Value, and State are included in the list of properties supported by the Direct Annotation feature, this feature is sufficient to meet WCAG Success Criterion 4.1.2: Name, Role, Value.

Implementation Details

The first step to using the Direct Annotation feature of the Dynamic Annotation API is to create an [IAccPropServices][] object using either the CoCreateInstance function or CoCreateInstanceEx function. Then you can use either the IAccPropServices::SetHwndProp method or the IAccPropServices::SetHwndPropStr method.

The following sample from Using Direct Annotation demonstrates the technique.

HRESULT CMyTextControl::SetAccessibleProperties()
{
    // COM is assumed to be initialized...
    IAccPropServices* pAccPropServices = NULL;
    HRESULT hr = CoCreateInstance(
        CLSID_AccPropServices, nullptr,
        CLSCTX_SERVER, IID_IAccPropServices, 
        reinterpret_cast<void**>(&pAccPropServices));
    if (SUCCEEDED(hr))
    {
        // Annotating the Role of this object to be STATICTEXT
        VARIANT var;
        var.vt = VT_I4;
        var.lVal = ROLE_SYSTEM_STATICTEXT;
        hr = pAccPropServices->SetHwndProp(
            _hwnd, OBJID_CLIENT, CHILDID_SELF,
            PROPID_ACC_ROLE, var);
        pAccPropServices->Release();
    }
    return hr;
}

More complete examples can be found in the following locations.

WndWithCustomizedAccessibleInfo.cpp and WndWithCustomizedAccessibleInfo.h
Implements the CWndWithCustomizedAccessibleInfo class, a ATL/MFC class that uses Direct Annotation to customize the accessible info of a window.
DirectAnnotation.cpp and DirectAnnotation.h
Implements the DirectAnnotation class, a Window API class that uses Direct Annotation to customize the accessible info of a window.

Note that using the IAccPropServices::SetHwndProp method or the IAccPropServices::SetHwndPropStr method will not send WinEvents. It is your responsibility to send appropriate events by calling the NotifyWinEvent function after the IAccPropServices::SetHwndProp method or the IAccPropServices::SetHwndPropStr method has been called.

For example, if you use IAccPropServices::SetHwndPropStr method to set the Name property of an element, send an EVENT_OBJECT_NAMECHANGE event for that object after SetHwndPropStr returns.

The CWndWithCustomizedAccessibleInfo class and DirectAnnotation class both make the necessary calls to the NotifyWinEvent function for you.

Implementing a Microsoft Active Accessibility (MSAA) Server Using the Windows API and C++

The oldest and simplest of the Accessibility APIs used in Microsoft Windows is Microsoft Active Accessibility or MSAA. This article provides a brief introduction on how to implement a MSAA Server using the Windows API and the C++ programming language.

The IAccessible interface

The heart of MSAA is the IAccessible interface. This interface exposes methods and properties that allow an accessibility server to make a user interface element and its children accessible to accessibility client applications. The methods and properties of the IAccessible interface allow a Windows API application to meet WCAG Success Criterion 4.1.2: Name, Role, Value, which requires that an accessibility client be able to programmatically determine the Name, Role, Value, and States of all user interface components (including but not limited to: form elements, links and components generated by scripts).

The following table provides information the methods of the IAccessible interface that are used to expose each of these properties.

Property	Method
Name	IAccessible::get_accName
Role	IAccessible::get_accRole
State	IAccessible::get_accState
Value	IAccessible::get_accValue

See the IAccessible interface page for a complete list of the members of the interface and a detailed description of each method. The Content of Descriptive Properties page provides information on the expected value of these properties.

The Name, Role, and State properties are required for all user interface components that can gain focus. The Value property may be required for some user interface components but not for others. More information on which members of the IAccessible interface should be implemented for a given user interface component can be found in the Choosing Which Properties to Support page.

How an accessibility client obtains an IAccessible object

An accessibility client use one of the following functions to obtain an IAccessible object.

See the Getting an Accessible Object Interface Pointer page for more information on these functions.

What happens when an accessibility client requests an IAccessible object?

When an accessibility client requests an IAccessible object using the AccessibleObjectFromEvent, AccessibleObjectFromPoint, and AccessibleObjectFromWindow functions Microsoft Active Accessibility sends the WM_GETOBJECT message to the appropriate window procedure within the appropriate server application with the lParam parameter set to OBJID_CLIENT. Your Microsoft Active Accessibility (MSAA) server needs to handle this message.

Handling the WM_GETOBJECT Message

When your Microsoft Active Accessibility (MSAA) Server receives the WM_GETOBJECT message it should return the value obtained by passing the IAccessible interface of the object to the LresultFromObject function as follows.

LRESULT OnGetObject(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam)
{
    if (static_cast<LONG>(lParam) != OBJID_CLIENT)
    {
        return DefWindowProcW(hWnd, message, wParam, lParam);
    }
    // Retrieve the control.
    ContactListControl* pCustomList = GetControl(hWnd);
    if (pCustomList == nullptr)
    {
        return 0;
    }
    // Create the accessible object.
    ContactListControlAccServer* pAccServer = pCustomList->GetAccServer();
    if (pAccServer == nullptr)
    {
        pAccServer = new (std::nothrow) ContactListControlAccServer(hWnd, pCustomList);
        pCustomList->SetAccServer(pAccServer);
        pAccServer->SetControlIsAlive(true);
    }
    if (pAccServer == nullptr)
    {
        return 0;
    }
    LRESULT Lresult = LresultFromObject(
        IID_IAccessible, wParam,
        static_cast<IAccessible*>(pAccServer));
    return Lresult;
}

The above code is from the Windows API Accessibility Server sample application.

For more information on handling the WM_GETOBJECT message see the following.

Events

Implementing the IAccessible interface is just one part of the puzzle. You also need to notify fire event notifications. This is done using the NotifyWinEvent function. See Event Constants, System-Level and Object-Level Events, and What Are WinEvents? for more information.

Additional Resources

Additional information can be found in the following locations.