How to create accessible controls by using Visual Basic .NET or Visual Basic 2005 (819351)


The information in this article applies to:

  • Microsoft Visual Basic 2005
  • Microsoft Visual Basic .NET (2003)
  • Microsoft Visual Basic .NET (2002)
  • Microsoft .NET Framework 2.0
  • Microsoft .NET Framework 1.1
  • Microsoft .NET Framework 1.0

IN THIS TASK

SUMMARY

This step-by-step article describes how to create an accessible control that is derived from the Control.ControlAccessibleObject class in Microsoft Visual Basic .NET or in Microsoft Visual Basic 2005.

back to the top

Requirements

This article assumes that you are familiar with the following topics:
  • Microsoft Visual Basic .NET or Microsoft Visual Basic 2005
  • Microsoft Active Accessibility
The following list outlines the recommended hardware, software, network infrastructure, and service packs that you need:
  • Microsoft Windows 2000, Microsoft Windows XP, or Microsoft Windows Server 2003
  • Microsoft Visual Basic .NET or Microsoft Visual Basic 2005
back to the top

Background information

Microsoft Active Accessibility is a developer technology that may help to improve the way that programs and operating systems work with assistive technology products. This technology was first integrated in the Microsoft Windows operating system in Microsoft Windows 98. Microsoft continues to update this technology with each new Windows release.

Microsoft Windows Forms has built-in Active Accessibility support. Windows Forms provides information about your application that permits your application to work with assistive technology products. You can use the following property values of a control to provide additional information to assistive technology products:
  • AccessibleName
  • AccessibleDescription
  • AccessibleDefaultActionDescription
  • AccessibleRole
Alternatively, if you require more Active Accessibility information to be included with your control, you can write your own class that is derived from the AccessibleObject class or from the Control.ControlAccessibleObject class.

The Control.ControlAccessibleObject class inherits from the AccessibleObject class. AccessibleObject enables you to provide information about a control to an assistive technology product. Control.ControlAccessibleObject enables you to provide information about a control to an assistive technology product by exposing a set of standard properties. For example, Control.ControlAccessibleObject may expose the Role property, the Location property, and others. Active Accessibility uses these properties to expose information to assistive technology products.

Active Accessibility uses Windows Events (WinEvents) to notify assistive technology products of user interface changes in a control, such as a change in the name, in the state, or in the value of a user interface element.

For more information about Microsoft Active Accessibility architecture, visit the following Microsoft Web sites:

Microsoft Active Accessibility: Architecture
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnacc/html/actvaccess.asp

Microsoft Active Accessibility Architecture: Part 2
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnacc/html/msaa_sa.asp

back to the top

Create a sample control

To create a custom CheckBox control (MyCheckBox) and to create a custom Control.ControlAccessibleObject class (MyCheckBoxAccessibleObject) that the custom CheckBox control uses to provide accessibility information to Active Accessibility applications, follow these steps:
  1. Open Microsoft Visual Studio .NET or Microsoft Visual Studio 2005.
  2. On the File menu, click New, and then click Project to display the New Project dialog box.
  3. In the Project Type window, click Visual Basic Projects.

    Note In Visual Studio 2005, click Visual Basic under Project Types.
  4. In the Templates window, click Windows Control Library.
  5. In the Name box, type MyCheckBox, and then click OK to create the project.
  6. Add a reference to the Active Accessibility assembly that is installed with the Microsoft .NET Framework. To do this, follow these steps:
    1. On the Project menu, click Add Reference.
    2. On the .NET tab, double-click Accessibility.dll.
    3. Click OK to close the Add Reference dialog box.
    Note The AccessibleObject class implements the IAccessible interface. The IAccessible interface is defined by the Active Accessibility assembly. Therefore, you must add a reference to the Active Accessibility assembly that is installed with the .NET Framework.
  7. Replace the content of UserControl1.vb with the following code:
    Imports System
Imports System.Windows.Forms
Imports Accessibility
Imports System.Drawing

Namespace MyCustomControls
    Public Class MyCheckBox
        Inherits CheckBox

        Public Sub New()
            ' Make the check box look similar to a toggle button.
            Me.Appearance = Appearance.Button
            ' Center the text on the button.
            Me.TextAlign = ContentAlignment.MiddleCenter
        End Sub

        ' Create an instance of the AccessibleObject that is 
        ' defined for the 'MyCheckBox' control. 
        Protected Overrides Function CreateAccessibilityInstance() _
          As AccessibleObject
            Return New MyCheckBoxAccessibleObject(Me)
        End Function
    End Class

    ' Accessible object for use with the 'MyCheckBox' control.
    Friend Class MyCheckBoxAccessibleObject
        Inherits Control.ControlAccessibleObject

        Public Sub New(ByVal owner As MyCheckBox)
            MyBase.New(owner)
        End Sub

        Public Overrides ReadOnly Property DefaultAction() As String
            Get
                ' Return the DefaultAction based on 
                ' the state of the control. 
                If CType(Owner, MyCheckBox).Checked Then
                    Return "Toggle button up"
                Else
                    Return "Toggle button down"
                End If
            End Get
        End Property

        Public Overrides Property Name() As String
            Get
                ' Return the Text property of the control 
                ' if the AccessibleName is null. 
                Dim accessibleName As String = Owner.AccessibleName
                If Not (accessibleName Is Nothing) Then
                    Return accessibleName
                End If
                Return CType(Owner, MyCheckBox).Text
            End Get

            Set(ByVal Value As String)
                MyBase.Name = value
            End Set
        End Property

        Public Overrides ReadOnly Property Role() As AccessibleRole
            Get
                ' Because the check box looks similar to a button and functions like a button,
                ' make the Role the same as a button. 
                Return AccessibleRole.PushButton
            End Get
        End Property
    End Class
End Namespace
  8. On the Build menu, click Build Solution to build the control.
back to the top

Test the sample control

  1. Create a new Visual Basic .NET or Visual Basic 2005 Windows Application project in Visual Studio .NET or in Visual Basic 2005.
  2. On the View menu, click Toolbox.
  3. Right-click the toolbox.
  4. If you are using Microsoft Visual Studio .NET 2002, click Customize Toolbox.

    If you are using Microsoft Visual Studio .NET 2003, click Add/Remove Items.

    If you are using Microsoft Visual Studio 2005, click Choose Items.
  5. In the Customize Toolbox dialog box, click the .NET Framework Components tab, and then click the Browse button to locate the control assembly that you created in the "Create a sample control" section of this article.

    Note The control assembly is MyCheckBox.dll in the code sample.
  6. Click OK to close the Customize Toolbox dialog box.
  7. Add the MyCheckBox control to the form.
  8. Add a Button control to the form.

    By default, button1 is added to the form.

    Add the following code in the Click event handler of the button:
    MsgBox("Role: " + MyCheckBox1.AccessibilityObject.Role.ToString() + vbCrLf _
       + "Name: " + MyCheckBox1.AccessibilityObject.Name.ToString() + vbCrLf _
       + "DefaultAction:" + MyCheckBox1.AccessibilityObject.DefaultAction.ToString())
  9. Press the F5 key to build the application and to run the application.
  10. When the application starts, press button1 on the form.

    You receive the following message:Role: PushButton
    Name: MyCheckBox1
    DefaultAction: Toggle button dow
back to the top

REFERENCES

The Microsoft Active Accessibility Software Development Kit provides several utilities that you can use to test your accessible controls or applications. To download these utilities, visit the following Microsoft Web site:

http://msdn.microsoft.com/library/en-us/msaa/msaaccgd_30fn.asp

back to the top
Modification Type:MinorLast Reviewed:10/3/2006
Keywords:kbvs2005swept kbvs2005applies kbWindowsForms kbAAcc kbHOWTOmaster kbhowto kbcode KB819351 kbAudDeveloper
©2004 Microsoft Corporation. All rights reserved.