Microsoft KB Archive/819351

Knowledge Base

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

Article ID: 819351

Article Last Modified on 12/3/2007

---

APPLIES TO

• Microsoft Visual Basic 2005
• Microsoft Visual Basic .NET 2003 Standard Edition
• Microsoft Visual Basic .NET 2002 Standard Edition
• Microsoft .NET Framework 2.0
• Microsoft .NET Framework 1.1
• Microsoft .NET Framework 1.0

---

IN THIS TASK

• SUMMARY
  • Requirements
  • Background information
  • Create a sample control
  • Test the sample control
• REFERENCES

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://msdn2.microsoft.com/en-us/library/ms971310.aspx

Microsoft Active Accessibility Architecture: Part 2
http://msdn2.microsoft.com/en-us/library/ms971352.aspx

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://msdn2.microsoft.com/en-us/library/ms695716.aspx

back to the top

Additional query words: aacc aid usercontrol

Keywords: kbhowto kbhowtomaster kbwindowsforms kbaacc kbcode kbvs2005applies kbvs2005swept KB819351

---

Send feedback to Microsoft

© Microsoft Corporation. All rights reserved.