MSAA_v2.docx

Microsoft Active Accessibility Version 2.0
Legal Information
Information in this document, including URL and other Internet Web site references, is subject to
change without notice. Unless otherwise noted, the example companies, organizations, products,
domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious,
and no association with any real company, organization, product, domain name, e-mail address,
logo, person, place or event is intended or should be inferred. Complying with all applicable
copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part
of this document may be reproduced, stored in or introduced into a retrieval system, or
transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or
otherwise), or for any purpose, without the express written permission of Microsoft Corporation.
Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual
property rights covering subject matter in this document. Except as expressly provided in any
written license agreement from Microsoft, the furnishing of this document does not give you any
license to these patents, trademarks, copyrights, or other intellectual property.
©1997-2001 Microsoft Corporation. All rights reserved.
Microsoft, MS-DOS, Windows, Windows NT, Active Accessibility, ActiveX, Microsoft Press,
MSDN, Visual Basic, Visual C++, and Win 32 are either registered trademarks or trademarks of
Microsoft Corporation in the U.S.A. and/or other countries.
The names of actual companies and products mentioned herein may be the trademarks of their
respective owners.
Legal Information .....................................................................................................................................i
CHAPTER 1: GETTING STARTED .......................................................................................................... 1
SDK COMPONENTS ...................................................................................................................................... 1
Header and Lib Files ............................................................................................................................... 1
Tools ........................................................................................................................................................ 2
SUPPORTED PLATFORMS .............................................................................................................................. 2
Which Version of Active Accessibility Is Currently Installed? ................................................................ 3
CHAPTER 2: RELEASE INFORMATION ............................................................................................... 5
NEW FEATURES IN ACTIVE ACCESSIBILITY 2.0 ............................................................................................ 5
RELEASE NOTES ........................................................................................................................................... 5
Known Issues ........................................................................................................................................... 6
Unsupported IAccPropServices Methods ............................................................................................................ 6
Operating Systems Currently Not Supported by Active Accessibility 2.0 ........................................................... 6
Operating Systems Supported by the Active Accessibility 2.0 Redistribution Kit .............................................. 6
Text Services Supported by RichEdit 3.0 Only ................................................................................................... 6
Active Accessibility 2.0 Tools Currently Not Available for 64-Bit Operating Systems ...................................... 6
Clients Using Word XP Implementation of ITextStore Must Be Rebooted ......................................................... 7
IAccPropServices::SetPropServer Does Not Manage the Callback Server Properly When Invalid Parameters
Are Used .............................................................................................................................................................. 7
Oleacc Caret Location Inaccurate on Systems without Right-to-Left Support Enabled ...................................... 7
Changes in Behavior ............................................................................................................................... 7
Multiple Document Interface Support for IAccessible ........................................................................................ 7
IAccessible::accSelect Now Fully Implemented .................................................................................................. 7
New State: STATE_SYSTEM_HASPOPUP....................................................................................................... 7
IAccessible::accLocation Returns Accurate Information for Vertical Slider Bar Coordinates ............................ 7
New Role: ROLE_SYSTEM_SPLITBUTTON................................................................................................... 7
Oleacc Now Supports SysIPAddress32 ............................................................................................................... 7

Microsoft Active Accessibility ii

CHAPTER 3: TECHNICAL OVERVIEW ................................................................................................. 9
HOW ACTIVE ACCESSIBILITY WORKS .......................................................................................................... 9
Client Applications and Active Accessibility ......................................................................................... 10
ACTIVE ACCESSIBILITY BASICS ................................................................................................................. 10
Active Accessibility Objects ................................................................................................................... 11
Accessible Objects ..............................................................................................................................................11
Simple Elements .................................................................................................................................................11
How Child IDs Are Used in Parameters .............................................................................................................12
Input Parameters .............................................................................................................................................12
Output Parameters ..........................................................................................................................................12
Special Cases ..................................................................................................................................................13
Custom User Interface Elements ........................................................................................................................13
Dual Interfaces: IAccessible and IDispatch ........................................................................................................13
System-Provided User Interface Elements..........................................................................................................14
Types of IAccessible Support ................................................................................................................. 14
Native Active Accessibility Implementation ......................................................................................................14
IAccessible Proxies.............................................................................................................................................15
Creating a Proxy .............................................................................................................................................15
What Information Is Exposed .........................................................................................................................15
Generic Proxy Objects ....................................................................................................................................15
Client-Server Communication ............................................................................................................... 15
WinEvents ..........................................................................................................................................................16
Event-Driven Communication........................................................................................................................17
How WM_GETOBJECT Works ........................................................................................................................17
Retrieving an IAccessible Object ........................................................................................................................17
SERVER GUIDELINES .................................................................................................................................. 18
How Servers Implement Child IDs .....................................................................................................................18
CLIENT GUIDELINES ................................................................................................................................... 19
How Clients Obtain Child IDs ............................................................................................................... 19
COM AND UNICODE GUIDELINES .............................................................................................................. 19
VARIANT Structure ............................................................................................................................... 20
IDispatch Interface ................................................................................................................................ 21
Converting Unicode and ANSI Strings .................................................................................................. 21
CHAPTER 4: C/C++ DEVELOPER'S GUIDE ........................................................................................ 22
ACTIVE ACCESSIBILITY USER INTERFACE SERVICES.................................................................................. 22
User Interface APIs ............................................................................................................................... 22
IAccessible Interface ..........................................................................................................................................22
Content of Descriptive Properties...................................................................................................................23
Selection and Focus Properties and Methods .................................................................................................26
Object Navigation Properties and Methods ....................................................................................................27
Dynamic Annotation API ...................................................................................................................................30
Background Information ................................................................................................................................31
Alternatives to Dynamic Annotation ..............................................................................................................31
Types of Dynamic Annotation .......................................................................................................................32
Direct Annotation ...........................................................................................................................................33
Value Map Annotation ...................................................................................................................................34
Server Annotation ..........................................................................................................................................37
Issues and Limitations ....................................................................................................................................43
Calling Active Accessibility APIs .......................................................................................................... 44
WinEvents .............................................................................................................................................. 44
What Are WinEvents? ........................................................................................................................................45
System-Level and Object-Level Events ..............................................................................................................45
Registering a Hook Function ..............................................................................................................................46
In-Context and Out-of-Context Hook Functions ................................................................................................46
In-Context Hook Functions ............................................................................................................................46
In-Context Hook Function Precautions ..........................................................................................................47
Out-of-Context Hook Functions .....................................................................................................................47
Guarding Against Reentrancy in Hook Functions ..............................................................................................48

Microsoft Active Accessibility iii

Alerts ..................................................................................................................................................................48
Developer's Guide for Active Accessibility Clients ............................................................................... 49
Getting an Accessible Object Interface Pointer ..................................................................................................49
Using AccessibleObjectFromEvent ................................................................................................................50
Using AccessibleObjectFromPoint.................................................................................................................50
Checking IAccessible Return Values ..................................................................................................................51
Receiving Errors for IAccessible Interface Pointers ...........................................................................................51
Setting a WinEvent Hook ...................................................................................................................................52
Developer's Guide for Active Accessibility Servers ............................................................................... 52
Creating Proxy Objects .......................................................................................................................................52
What Are Proxy Objects? ...............................................................................................................................53
Why Proxy Objects Are Needed ....................................................................................................................53
Design Considerations for Proxy Objects .......................................................................................................53
IAccessible Design Considerations .....................................................................................................................54
Choosing When to Create Accessible Objects................................................................................................54
Choosing Which Properties to Support ..........................................................................................................54
Choosing the Content for Descriptive Properties ...........................................................................................55
Setting Properties for Animated or Moving Objects ......................................................................................55
How to Handle WM_GETOBJECT ...................................................................................................................56
Create New Accessible Objects ......................................................................................................................56
Reuse Existing Pointers to Objects .................................................................................................................56
Create New Interfaces to the Same Object .....................................................................................................57
Shortcuts for Exposing Custom User Interface Elements ...................................................................................57
Exposing Controls Based on System Controls ...............................................................................................58
Exposing Owner-Drawn Menu Items .............................................................................................................59
Labeling Owner-Drawn Controls ...................................................................................................................60
Exposing Owner-Drawn List Box Items ........................................................................................................60
Exposing Owner-Drawn Combo Box Items ...................................................................................................61
Testing Tools ......................................................................................................................................... 62
Accessible Event Watcher ..................................................................................................................................62
Accessible Explorer ............................................................................................................................................62
Inspect Objects ...................................................................................................................................................62
ACTIVE ACCESSIBILITY TEXT SERVICES .................................................................................................... 64
Text Services APIs ................................................................................................................................. 64
Text Services Supporting Material ........................................................................................................ 64
CHAPTER 5: C/C++ REFERENCE ......................................................................................................... 65
ACTIVE ACCESSIBILITY USER INTERFACE SERVICES.................................................................................. 65
User Interface APIs ............................................................................................................................... 65
IACCESSIBLE .............................................................................................................................................. 65
Definitions of Parameter Attributes....................................................................................................... 66
IAccessible Interface Quick Reference .................................................................................................. 67
Navigation and Hierarchy...............................................................................................................................67
Descriptive Properties and Methods ...............................................................................................................67
Selection and Focus ........................................................................................................................................67
Spatial Mapping .............................................................................................................................................67
IAccessible::accDoDefaultAction.......................................................................................................... 67
IAccessible::accHitTest ......................................................................................................................... 69
IAccessible::accLocation....................................................................................................................... 70
IAccessible::accNavigate ...................................................................................................................... 72
IAccessible::accSelect ........................................................................................................................... 74
IAccessible::get_accChild ..................................................................................................................... 75
IAccessible::get_accChildCount ........................................................................................................... 77
IAccessible::get_accDefaultAction........................................................................................................ 77
IAccessible::get_accDescription ........................................................................................................... 78
IAccessible::get_accFocus .................................................................................................................... 80
IAccessible::get_accHelp ...................................................................................................................... 81
IAccessible::get_accHelpTopic ............................................................................................................. 82
IAccessible::get_accKeyboardShortcut ................................................................................................. 84

Microsoft Active Accessibility iv

IAccessible::get_accName..................................................................................................................... 85
IAccessible::get_accParent ................................................................................................................... 86
IAccessible::get_accRole....................................................................................................................... 87
IAccessible::get_accSelection ............................................................................................................... 88
IAccessible::get_accState ...................................................................................................................... 89
IAccessible::get_accValue..................................................................................................................... 90
IAccessible::put_accName .................................................................................................................... 91
IAccessible::put_accValue .................................................................................................................... 91
DYNAMIC ANNOTATION ............................................................................................................................. 92
IAccIdentity::GetIdentityString ............................................................................................................. 92
IAccPropServer::GetPropValue ............................................................................................................ 93
IAccPropServices::SetPropValue .......................................................................................................... 94
IAccPropServices::SetPropServer ......................................................................................................... 95
IAccPropServices::ClearProps ............................................................................................................. 96
IAccPropServices::SetHwndProp.......................................................................................................... 97
IAccPropServices::SetHwndPropStr ..................................................................................................... 98
IAccPropServices::SetHwndPropServer ............................................................................................... 99
IAccPropServices::ClearHwndProps .................................................................................................. 100
IAccPropServices::ComposeHwndIdentityString ................................................................................ 101
IAccPropServices::DecomposeHwndIdentityString ............................................................................ 102
Active Accessibility Client Functions .................................................................................................. 103
AccessibleChildren .............................................................................................................................. 103
AccessibleObjectFromEvent ................................................................................................................ 105
AccessibleObjectFromPoint ................................................................................................................ 106
AccessibleObjectFromWindow ............................................................................................................ 107
GetOleaccVersionInfo ......................................................................................................................... 109
GetRoleText ......................................................................................................................................... 110
GetStateText ........................................................................................................................................ 111
SetWinEventHook ................................................................................................................................ 112
UnhookWinEvent ................................................................................................................................. 114
IsWinEventHookInstalled .................................................................................................................... 115
WindowFromAccessibleObject ............................................................................................................ 116
WinEventProc Callback Function ....................................................................................................... 116
IVersionInfo::GetSubComponentCount .............................................................................................. 117
IVersionInfo::GetImplementationID ................................................................................................... 118
IVersionInfo::GetBuildVersion ........................................................................................................... 119
IVersionInfo::GetComponentDescription ........................................................................................... 119
IVersionInfo::GetInstanceDescription ................................................................................................ 120
ICoCreateLocally::CoCreateLocally .................................................................................................. 120
ICoCreatedLocally::LocalInit ............................................................................................................. 121
Active Accessibility Server Functions .................................................................................................. 122
CreateStdAccessibleObject .................................................................................................................. 122
CreateStdAccessibleProxy ................................................................................................................... 123
LresultFromObject .............................................................................................................................. 125
ObjectFromLresult .............................................................................................................................. 127
NotifyWinEvent .................................................................................................................................... 128
Structures and Data Types .................................................................................................................. 129
MSAAMENUINFO .............................................................................................................................. 129
HWINEVENTHOOK ........................................................................................................................... 130
WINEVENTPROC ............................................................................................................................... 131
WM_GETOBJECT Window Message.................................................................................................. 131
WM_GETOBJECT .............................................................................................................................. 131
Constants and Enumerated Types ....................................................................................................... 132
Event Constants ................................................................................................................................... 133
Navigation Constants .......................................................................................................................... 139
Object Identifiers ................................................................................................................................. 139

Microsoft Active Accessibility v

Object Roles ........................................................................................................................................ 140
Object State Constants ........................................................................................................................ 145
SELFLAG ............................................................................................................................................ 148
Return Values ...................................................................................................................................... 150
ACTIVE ACCESSIBILITY TEXT SERVICES .................................................................................................. 151
Text Services APIs ............................................................................................................................... 151
IAccClientDocMgr ...........................................................................................................................................151
IAccDictionary .................................................................................................................................................151
IAccServerDocMgr...........................................................................................................................................152
IAccServerDocMgr::NewDocument .................................................................................................... 152
IAccServerDocMgr::RevokeDocument ............................................................................................... 152
IAccServerDocMgr::OnDocumentFocus ............................................................................................ 153
IAccClientDocMgr::LookupByHWND ................................................................................................ 153
IAccClientDocMgr::LookupByPoint ................................................................................................... 154
IAccClientDocMgr::GetDocuments .................................................................................................... 155
IAccClientDocMgr::GetFocused ......................................................................................................... 155
IAccDictionary::GetLocalizedString ................................................................................................... 156
IAccDictionary::GetParentTerm ......................................................................................................... 157
IAccDictionary::GetMnemonicString .................................................................................................. 157
IAccDictionary::LookupMnemonicTerm ............................................................................................. 158
IAccDictionary::ConvertValueToString .............................................................................................. 158
APPENDIXES ........................................................................................................................................... 160
APPENDIX A: SUPPORTED USER INTERFACE ELEMENTS REFERENCE ....................................................... 160
Supported User Interface Elements ..............................................................................................................160
How Active Accessibility Exposes User Interface Elements ................................................................ 161
Screening Out Unnecessary Objects .................................................................................................................161
Providing the Name Property .............................................................................................................. 162
Support Provided on Windows NT 4.0 ................................................................................................ 162
Unsupported User Interface Elements................................................................................................. 162
Animation Control ............................................................................................................................... 163
Calendar Control................................................................................................................................. 164
Caret .................................................................................................................................................... 165
Check Box ............................................................................................................................................ 166
Client Object........................................................................................................................................ 167
Combo Box .......................................................................................................................................... 167
Cursor .................................................................................................................................................. 171
Desktop Window .................................................................................................................................. 172
Dialog Box ........................................................................................................................................... 173
Edit Control ......................................................................................................................................... 174
Group Box ........................................................................................................................................... 175
Header Control.................................................................................................................................... 176
Hot Key Control .................................................................................................................................. 177
List Box ................................................................................................................................................ 178
List View Control ................................................................................................................................. 179
MDI Client Window ............................................................................................................................. 181
Menu Bar ............................................................................................................................................. 182
Menu Item ............................................................................................................................................ 184
Pop-Up Menu ...................................................................................................................................... 185
Progress Bar Control .......................................................................................................................... 186
Push Button ......................................................................................................................................... 187
Radio Button ........................................................................................................................................ 188
Scroll Bar ............................................................................................................................................ 189
Size Grip .............................................................................................................................................. 192
Slider Control ...................................................................................................................................... 193
Static Text ............................................................................................................................................ 195

Microsoft Active Accessibility vi

Status Bar Control ............................................................................................................................... 196
Switch Window .................................................................................................................................... 197
Tab Control ......................................................................................................................................... 198
Title Bar ............................................................................................................................................... 199
Toolbar Control ................................................................................................................................... 200
ToolTip Control ................................................................................................................................... 202
Tree View Control ............................................................................................................................... 202
Up-Down Control ................................................................................................................................ 204
Window ................................................................................................................................................ 205
APPENDIX B: STANDARD DIALOG MANAGER SUPPORT ........................................................................... 207
APPENDIX C: IACCESSIBLE DISPIDS ....................................................................................................... 208
APPENDIX D: NOTES FOR VISUAL BASIC DEVELOPERS ............................................................................ 209
Visual Basic Method Notes: accName ................................................................................................. 209
Visual Basic Method Notes: accValue ................................................................................................. 209
Visual Basic Sample Programs ........................................................................................................... 209
APPENDIX E: TEXT ATTRIBUTES FOR ACTIVE ACCESSIBILITY TEXT SERVICES DICTIONARY................... 210
Font ..............................................................................................................................................................210
Font_Style ....................................................................................................................................................210
Font_Style_Animation .................................................................................................................................212
Font_Style_Underline ..................................................................................................................................212
Font_Style_Strikethrough.............................................................................................................................213
Font_Style_Overline ....................................................................................................................................213
Text ..............................................................................................................................................................213
Text_Alignment ...........................................................................................................................................214
Text_Para .....................................................................................................................................................214
Text_Para_lineSpacing .................................................................................................................................215
Text_List ......................................................................................................................................................215
Text_List_Type ............................................................................................................................................216
App ...............................................................................................................................................................216
APPENDIX F: FOR MORE INFORMATION ................................................................................................... 216
GLOSSARY ............................................................................................................................................... 219

Chapter 1

Getting Started
Microsoft® Active Accessibility® 2.0 is a set of COM interfaces and APIs that provides a reliable
way to expose and collect information about Microsoft Windows-based user interface (UI)
elements and Web content. Using this information, Assistive Technology Vendors can represent
the UI in alternative formats, such as speech or Braille, and voice command and control
applications can remotely manipulate the interface. Active Accessibility relies on Windows ®
technology and can be used in conjunction only with Windows-based controls and other Windows
applications.
This documentation is organized to meet the needs of developers new to, as well as those
familiar with, Active Accessibility. The major sections of the documentation are described below:
Getting Started
Introduction to the Active Accessibility SDK and information about the SDK components and
supported platforms.
Release Information
Notes about new features, known issues, and changes in behavior for this release.
Technical Overview
Overview of Active Accessibility and general guidelines for Active Accessibility client and
server developers.
C/C++ Developer's Guide
In-depth information about the key Active Accessibility application programming interface
(API) elements and concepts. Uses terms and examples familiar to C or C++ developers.
C/C++ Reference
A comprehensive reference for all the Active Accessibility APIs, data types, data structures,
and messages.
Appendixes
Additional reference material for Active Accessibility client and server developers and Visual
Basic developers.
For More Information
A list of references for more information about programming concepts, technologies, and
resources.
Glossary
A reference for new or unfamiliar terminology used in Active Accessibility.

SDK Components
The Active Accessibility SDK contains the following components:
Header and lib files
Tools

Header and Lib Files

Microsoft Active Accessibility 2

The Active Accessibility SDK contains the following header and lib files.
File Description
Winable.h C and C++ header file for using WinEvents
Winuser.h C and C++ header file for using Windows controls
Oleacc.h C and C++ header file containing definitions needed
by Active Accessibility clients and servers
Textstor.h C and C++ header file containing definitions for
ITextStore interface needed by implementers and
clients
MSAAtext.h C and C++ header file containing definitions for
support servers provided by Document Services that
allow clients to find documents and servers to notify
Document Services of their existence
Winver.h C and C++ header file for version information
Oleacc.lib Import library for Oleacc.dll
Oleacc.dll Dynamic-link library that provides the Active
Accessibility run time, manages requests from Active
Accessibility clients, and proxies common UI
elements
Oleaccrc.dll Multilingual resource dynamic-link library used by
Oleacc.dll
Msaatext.dll Dynamic-link library for Active Accessibility document
support

Tools
The Active Accessibility SDK includes the following tools for testing. For more information about
the testing tools, see Testing Tools.
Tool Description
Accessible Event Watcher Logs WinEvents as they occur within
the system
Accessible Explorer Examines and tests for the
IAccessible properties of objects and
their hierarchical relationships to each
other
Inspect Objects Identifies problems with IAccessible
interface implementations in
properties and methods

Supported Platforms
Active Accessibility 2.0 supports most Microsoft platforms and is included as part of the Windows
XP operating system. If you do not know which version of Active Accessibility you are running,
see Which Version of Active Accessibility Is Currently Installed?
If you do not have the latest version of Active Accessibility, use the Microsoft Active Accessibility
2.0 Redistribution Kit (RDK) to upgrade. This RDK contains all of the core system files needed to


incorporate Active Accessibility 2.0 technology into client and server applications. It supports
Microsoft Windows® 98, Microsoft Windows NT® version 4.0 with Service Pack 6 or later, and
Microsoft Windows XP.

Note
The Active Accessibility 2.0 RDK is not currently available for Microsoft Windows 2000 or
Microsoft Windows Me. Therefore, the new features introduced with Active Accessibility 2.0—
Dynamic Annotation and Text Services—are currently not supported on these operating
systems.

To install the Active Accessibility RDK, see the Accessibility home page on MSDN.
The following table lists each Windows operating system and the Active Accessibility version that
supports it. Note that Windows CE and Windows 3.1 are not supported by any Active
Accessibility version.
Platform Active Comments
Accessibility
Version
Windows XP 2.0 Full support for version 2.0 is built into
in the operating system; this platform
does not support Active Accessibility
1.3.
Windows 2000 1.3 Full support for version 1.3 is built into
the operating system. Currently this
platform does not support 2.0 so you
are not able to upgrade; therefore you
are not able to use Dynamic
Annotation and Text Services.
Windows Me 1.3 Full support for version 1.3 is built into
the operating system. Currently this
platform does not support version 2.0
so you are not able to upgrade;
therefore you are not able to use
Dynamic Annotation and Text
Services.
Windows NT 4.0 2.0 Full support for version 1.3 is built into
the operating system beginning with
Service Pack 6; use the Active
Accessibility 2.0 RDK to upgrade
Active Accessibility on earlier versions
of Windows NT.
Windows 98 2.0 Initial release included version 1.1;
use the Active Accessibility 2.0 RDK
to upgrade.
Windows 95 1.3 This operating system does not
include Active Accessibility and will
not support version 2.0. Use the
Active Accessibility 1.3 RDK to install.

Which Version of Active Accessibility Is Currently Installed?


To find out which version of Active Accessibility is installed on your system, you should check the
version of the Oleacc.dll file in the system32 folder on your hard drive. The following table maps
the Active Accessibility version to the Oleacc.dll version.
Active Accessibility version Oleacc.dll version
1.0 4.01.0970.0
1.2 4.02.2900.0
1.3 4.02.3100.0
2.0 5.0.0.0


Chapter 2

Release Information
This section provides release information about Microsoft® Active Accessibility® 2.0.
New Features in Active Accessibility 2.0
Release Notes

New Features in Active Accessibility 2.0
Microsoft® Active Accessibility® 2.0 has several updates and changes reflected in the SDK
documentation.
Active Accessibility now fully supports Unicode and all 27 languages for Windows.
The new features in Active Accessibility 2.0 are described in detail within their appropriate
sections in the documentation and are summarized in the following table.
Feature Change
Dynamic Annotation The Dynamic Annotation Application
Programming Interface (API) is an
extension to Active Accessibility that
allows developers to customize existing
IAccessible support without having to
use error-prone subclassing or wrapping
techniques. This mechanism also allows
developers to pass hints or other useful
information to the OLEACC proxies. For
more information, see Dynamic
Annotation API.
Text Services Active Accessibility Text Services
provides a way to navigate large bodies
of text programmatically using a COM
interface. Text Services APIs
communicate text style information, such
as whether the text is bold, italic, or part
of a bulleted list. Text Services provides
these features in applications such as
Microsoft Word.

Release Notes
The following section describes known issues identified in Microsoft® Active Accessibility® 2.0 as
well as changes in behavior that have occurred since Active Accessibility 1.3. This information is
current as of July 2001. For updated information, please see the Accessibility home page on
MSDN.
Known Issues
Changes in Behavior


Known Issues
The following section contains known issues that have been identified in Microsoft ® Active
Accessibility® 2.0. These issues are current as of July 2001. For updated information, please see
the Accessibility home page on MSDN.

Unsupported IAccPropServices Methods
The IAccPropServices interface contains several methods designed for annotating menus that
are not currently implemented. For this reason, the following methods are not currently
documented in the platform SDK:
SetHmenuProp
SetHmenuPropStr
ClearHmenuProps
SetHmenuPropServer
DecomposeHmenuIdentityString
ComposeHmenuIdentityString

Another approach exists for developers who are interested in customizing the information
exposed through Active Accessibility. For more information about annotating menus, see the
following two articles on MSDN:
Microsoft Active Accessibility Architecture (Part 1)
Microsoft Active Accessibility Architecture (Part 2)

Operating Systems Currently Not Supported by Active Accessibility 2.0
Active Accessibility 2.0 does not currently support Microsoft Windows ® 95, Microsoft Windows
2000, or Microsoft Windows Me.

Operating Systems Supported by the Active Accessibility 2.0
Redistribution Kit
The Active Accessibility 2.0 RDK supports Microsoft Windows NT ® 4 Service Pack 6 and
Microsoft Windows 98. If you upgrade your operating system or apply a service pack, you must
reinstall the RDK.
If you wish to repair or remove Active Accessibility 2.0, from Control Panel, double-click
Add/Remove Programs, select Microsoft Active Accessibility 2.0, and then click
Change/Remove. Note that this method completely removes Active Accessibility and does not
revert to a previous version.

Text Services Supported by RichEdit 3.0 Only
The Active Accessibility 2.0 Text Services APIs are supported only by RichEdit 3.0, which ships
with Microsoft Office XP.

Active Accessibility 2.0 Tools Currently Not Available for 64-Bit
Operating Systems


Currently 64-bit versions of the Inspect Object, Accessible Event Watcher, and Accessible
Explorer tools do not exist for the IA64 version of Windows XP. You should use the 32-bit version
of these tools on this operating system.

Clients Using Word XP Implementation of ITextStore Must Be Rebooted
For Text Services to work properly with Microsoft Word XP, you must restart your system after
installing Active Accessibility 2.0.

IAccPropServices::SetPropServer Does Not Manage the Callback
Server Properly When Invalid Parameters Are Used
In Active Accessibility 2.0, the IAccPropServices::SetPropserver method increments the
reference count and does not release the callback server when invalid parameters are used.

Oleacc Caret Location Inaccurate on Systems without Right-to-Left
Support Enabled
The x coordinate for the caret proxy is inaccurate by three pixels. Use the rcCaret value returned
by the GetGUIThreadInf function to determine the correct location of the caret.

Changes in Behavior
The following issues have been resolved with Microsoft ® Active Accessibility® 2.0.

Multiple Document Interface Support for IAccessible
In Active Accessibility 2.0, Oleacc fully supports the IAccessible interface for the Minimize,
Maximize, and Close icons that appear on the top right corner of a document's toolbar. These
icons are used on multiple document interfaces.

IAccessible::accSelect Now Fully Implemented
The accSelect method has been fully implemented for all proxies and can be used to
programmatically switch focus between applications in Windows.

New State: STATE_SYSTEM_HASPOPUP
The STATE_SYSTEM_HASPOPUP state indicates whether an object has a pop-up menu
associated with it. Controls such as the Start menu use the flag to report this capability to
vendors.

IAccessible::accLocation Returns Accurate Information for Vertical
Slider Bar Coordinates
In previous versions of Oleacc, the x and y coordinates were reversed for vertical slide bars. This
issue has been resolved for Active Accessibility 2.0.

New Role: ROLE_SYSTEM_SPLITBUTTON
The ROLE_SYSTEM_SPLITBUTTON role identifies controls that contain a both a button and a
list. For more information, see ROLE_SYSTEM_SPLITBUTTON in the Object Roles section in
the C/C++ Reference.

Oleacc Now Supports SysIPAddress32


Oleacc now supports the SysIPAddress32 control.


Chapter 3

Technical Overview
Microsoft® Active Accessibility® improves the way accessibility aids (specialized programs that
help people with disabilities use computers more effectively) work with applications running on
Microsoft Windows®.
Active Accessibility is based on the Component Object Model (COM), which was developed by
Microsoft and is an industry standard that defines a common way for applications and operating
systems to communicate. Active Accessibility consists of the following components:
The COM interface IAccessible, which exposes information about user interface (UI)
elements. IAccessible also has properties and methods for obtaining information about and
manipulating that UI element.
WinEvents, an event system that allows servers to notify clients when an accessible object
changes.
Oleacc.dll, a support or run-time dynamic-link library.

The Active Accessibility dynamic-link library, Oleacc.dll, consists of the following components:
APIs that allow clients to request an IAccessible interface pointer(for example,
AccessibleObjectFrom.X).
APIs that allow servers to return an IAccessible interface pointer to a client (for example,
LresultFromObject).
APIs for getting localized text for the role and state codes (for example, GetRoleText and
GetStateText).
Some helper APIs (AccessibleChildren).
Code that provides the default implementation of IAccessible for standard USER and
COMCTL controls. Since these implement IAccessible on behalf of the system controls, they
are known as proxies.

The following topics introduce key Active Accessibility components and describe how to use
them:
How Active Accessibility Works
Active Accessibility Basics
Server Guidelines
Client Guidelines
COM and Unicode Guidelines

How Active Accessibility Works
Microsoft® Active Accessibility® is designed to help accessibility aids, called clients, interact with
standard and custom user interface (UI) elements of other applications and the operating system.
An Active Accessibility client is any program that uses Active Accessibility to access, identify, or
manipulate the UI elements of an application. Clients include accessibility aids, automated testing
tools, and some computer-based training applications.
Using Active Accessibility, a client application can:


Query for information—for example, about a UI element at a particular location.
Receive notifications when information changes—for example, when a control becomes
grayed or when a text string changes.
Carry out actions that affect user interface or document contents—for example, click a push
button, drop down a menu, and choose a menu command.

The applications that interact with and provide information for clients are called servers. A server
uses Active Accessibility to provide information about its UI elements to clients. Any control,
module, or application that uses Active Accessibility to expose information about its user interface
is considered an Active Accessibility server. Servers communicate with clients by sending event
notifications (such as calling NotifyWinEvent) and responding to client requests for access to UI
elements (such as handling WM_GETOBJECT messages sent from OLEACC). Servers expose
information through the IAccessible interface.
Using Active Accessibility, a server application can:
Provide information about its custom user interface objects and the contents of its client
windows.
Send notifications when its user interface changes.

For example, to enable a user to select commands verbally from a word processor's custom
toolbar, a speech recognition program must have information about that toolbar. The word
processor would therefore need to make that information available. Active Accessibility provides
the means for the word processor to expose information about its custom toolbar and for the
speech recognition program to get that information.

Client Applications and Active Accessibility
An Active Accessibility client must be notified when the server's UI has changed so that it can
convey that information to the user. To ensure that the client is informed about UI changes, ituses
a mechanism called Window Events, or WinEvents, to register to receive notifications. For more
information, see WinEvents .
To learn about and manipulate a particular UI element, clients use the Active Accessibility COM
interface, IAccessible.
A client can retrieve an IAccessible object for a UI element in the following four ways:
Call AccessibleObjectFromWindow and pass the UI element’s window handle.
Call AccessibleObjectFromPoint and pass a screen location that lies within the UI
element’s bounding rectangle.
Set a WinEvent hook, receive a notification, and call AccessibleObjectFromEvent to
retrieve an IAccessible interface pointer for the UI element that generated the event.
Call an IAccessible method such as accNavigate or get_accParent to move to a different
IAccessible object.

Active Accessibility Basics
This section addresses the main feature areas of Microsoft® Active Accessibility®. This includes
the following topics:
Active Accessibility Objects
Types of IAccessible Support


Client-Server Communication

Active Accessibility Objects
In Active Accessibility terminology, there are accessible objects and simple elements. Although
most applications contain both, accessible objects are more common than simple elements. This
section defines and discusses accessible objects and simple elements and provides appropriate
UI examples. For more information, see the following topics:
Accessible Objects
Simple Elements
How Child IDs Are Used in Parameters
Custom User Interface Elements
Dual Interfaces: IAccessible and IDispatch
System-Provided User Interface Elements

Accessible Objects
With Microsoft Active Accessibility, user interface (UI) elements are exposed to clients as COM
objects. These accessible objects maintain pieces of information, called properties, which
describe the object's name, screen location, and other information needed by accessibility aids.
Accessible objects also provide methods that clients call to cause the object to perform some
action. Accessible objects that have simple elements associated with them are also called
parents, or containers.
Accessible objects are implemented using Active Accessibility's COM-based IAccessible
interface. The IAccessible methods and properties enable client applications to get information
about UI elements needed by users. For example, IAccessible::get_accParent returns an
interface pointer to an accessible object's parent, and IAccessible::accNavigate provides a
means for clients to get information about other objects within a container.
For more information about how accessible objects and simple elements are related, see Simple
Elements.

Simple Elements
A simple element is a UI element that shares an IAccessible object with other elements and
relies on that IAccessible object (typically its parent) to expose its properties. To differentiate
between the elements sharing an IAccessible object, the server assigns a unique, positive child
identifier to each simple element. This assignment is done on a per-instance-of-interface basis,
so the IDs must be unique within that context. Many implementations assign these IDs
sequentially, beginning with 1. This scheme does not allow simple elements to have children of
their own. Simple elements are also known as children.
To be uniquely identified and exposed, a simple element requires an IAccessible object and
child ID. Therefore, when communicating with an IAccessible object, the clients must supply the
appropriate child ID. A special identifier, CHILDID_SELF, can be used to refer to the accessible
object itself, instead of one of its children.
The IAccessible object shared among simple elements often corresponds to a common parent
object in the user interface. For example, system list boxes expose an accessible object for the
overall list box and simple elements for each list box item. In this case, the IAccessible object for
the list box is also the parent or container of the list items.
For more information about accessible objects, see Accessible Objects.


How Child IDs Are Used in Parameters
This topic describes input parameters, output parameters, and special cases for interpreting child
IDs returned from IAccessible methods.

Input Parameters
Many of the Active Accessibility functions and most of the IAccessible properties take a
VARIANT input parameter. For most of the IAccessible properties, this parameter allows client
developers to specify whether they want information about the object itself or about one of the
object's simple elements.
Active Accessibility provides the constant CHILDID_SELF to indicate that information is needed
about the object itself. To obtain information about a simple element, client developers specify its
child ID in the VARIANT parameter.
When initializing a VARIANT parameter, be sure to specify VT_I4 in the vt member in addition to
specifying the child ID value (or CHILDID_SELF) in the lVal member.
For example, to get the name of an object, and not one of the object's child elements, initialize
the variant for the first parameter of IAccessible::get_accName ( CHILDID_SELF in the lVal
member and VT_I4 in the vt member), and then call IAccessible::get_accName.

Output Parameters
Several IAccessible functions and methods have a VARIANT* output parameter that contains a
child ID or an IDispatch interface pointer to a child object. There are different steps that a client
must take depending on whether they receive a VT_I4 child ID (simple element) or an IDispatch
interface pointer with CHILDID_SELF (full object). Following these steps will provide an
IAccessible interface pointer and child ID that together allow clients to use the IAccessible
methods and properties. These steps apply to the IAccessible accHitTest, get_accFocus, and
get_accSelection methods. They also apply to the AccessibleObjectFromEvent,
AccessibleObjectFromPoint, and AccessibleObjectFromWindow client functions.
The following table lists the possible result returned and the required post-processing steps so
that clients will have an IAccessible interface pointer and child ID.
Result returned Post-processing for the return
value
IDispatch interface pointer This is a full object.
Call QueryInterface to access the
IAccessible interface pointer.
Use the IAccessible interface pointer
with CHILDID_SELF to access
IAccessible methods and properties.
VT_I4 childID Call IAccessible::get_accChild
using the childID to see if you have
an IDispatch interface pointer.
If you get an IDispatch interface
pointer, use it with CHILDID_SELF to
access IAccessible interface
methods and properties.
If the call to get_accChild fails, you
have a simple element. Use the
original IAccessible interface pointer
(the one you used in your call to the


method or function mentioned above)
with the VT_I4 childID that the call
returned.

Before you can use a VARIANT parameter, you must initialize it by calling the VariantInit COM
function. When finished with the structure, call VariantClear to free the memory reserved for that
VARIANT.

Special Cases
There are exceptions to the guidelines in the above table, such as when a child ID is returned by
the IAccessible::accHitTest method. Servers must return an IDispatch interface if the child is
an accessible object. If a child ID is returned by IAccessible::accHitTest, the child is a simple
element.
In addition, there are special cases for accNavigate. For more information, see
IAccessible::accNavigate and Spatial and Logical Navigation.

Custom User Interface Elements
Server developers design accessible objects based on an application's user interface (UI).
Because Active Accessibility implements the IAccessible interface on behalf of system-provided
user interface elements such as list boxes, menus, and trackbar controls, you need to implement
the IAccessible interface only for the following kinds of custom UI elements:
Custom controls created by registering an application-defined window class
Custom controls drawn directly on the screen that do not have an associated HWND
Custom controls such as Microsoft ActiveX® and Java controls
Controls or objects in the application's client window that aren't already exposed

Owner-drawn controls and menus are accessible as long as you follow the guidelines discussed
in Shortcuts for Exposing Custom User Interface Elements. If you follow these guidelines, then
you do not need to implement the IAccessible interface for owner-drawn controls and menus.
In most cases, superclassed and subclassed controls are accessible because the system
handles the basic functionality of the control. However, if a superclassed or subclassed control
significantly modifies the behavior of the system-provided control on which it is based, then you
must implement the IAccessible interface. For more information, see Exposing Controls Based
on System Controls.
If an application uses only system-provided user interface elements, then it does not need to
implement IAccessible, except for its client window. For example, an application that includes a
text editor, not implemented using an edit control, exposes lines of text as accessible objects.
Note that Active Accessibility automatically exposes the text in edit and rich edit controls as a
single string of text in the Value property of the control.

Dual Interfaces: IAccessible and IDispatch
Server developers must provide the standard COM interface IDispatch for their accessible
objects. The IDispatch interface allows client applications written in Microsoft Visual Basic © and
various scripting languages to use the methods and properties exposed by IAccessible. Since an
accessible object provides access to an object either indirectly through IDispatch::Invoke or
directly with IAccessible, it is said to have a dual interface.
When C/C++ clients get back an IDispatch interface pointer, clients can call QueryInterface to
try converting the IDispatch interface pointer to an IAccessible interface pointer. To call the


IAccessible methods indirectly, C/C++ clients call IDispatch::Invoke. For improved
performance, call the IAccessible methods to use the object directly.
For a list of the dispatch IDs (DISPIDs) that IDispatch uses to identify the IAccessible methods
and properties, see Appendix C: IAccessible DISPIDs.

System-Provided User Interface Elements
Active Accessibility provides support for most predefined and common controls. The following
illustration shows a typical window and some of the system-provided user interface elements that
Active Accessibility exposes, such as title bars, menus, combo boxes, toolbar controls, tree view
controls, status bars, size grips, list view controls, and scroll bars.

Active Accessibility exposes system-provided user interface elements to server applications
without requiring the server developer to implement the IAccessible interface. Any application
that contains these elements automatically inherits their accessibility.
For a list of the controls and other system-provided user interface elements that Active
Accessibility supports, see Appendix A: Supported User Interface Elements Reference.

Types of IAccessible Support
Active Accessibility servers have two types of IAccessible support: native and proxied. The UI
elements used in an application determine which type of support is appropriate. Many servers
being written today take full advantage of IAccessible proxies and only implement IAccessible
for those controls that are not proxied by OLEACC, such as windowless controls or controls with
a custom window class name.
Native Active Accessibility Implementation
IAccessible Proxies

Native Active Accessibility Implementation
User interface elements that implement the IAccessible interface are said to provide a native
implementation. Although the development cost for implementing IAccessible (or any other COM
interface) can be high, the benefit is complete control over the information exposed to clients.


If your application uses custom controls or other controls that cannot be proxied by OLEACC, you
will need to provide a native implementation.

IAccessible Proxies
IAccessible proxies provide default accessibility information for standard UI elements: USER
controls, USER menus, and common controls from COMCTL and COMCTL32. This default
support is exposed through IAccessible objects created by OLEACC and delivers Active
Accessibility support without additional server development work. The server can then use
Dynamic Annotation to modify much of the information exposed by OLEACC, but it does not have
complete control.

Creating a Proxy
To determine whether a UI element natively supports the IAccessible interface, OLEACC sends
it a WM_GETOBJECT message. A nonzero return value means the element natively supports
Active Accessibility and provides its own IAccessible support. However, if the return value is
zero, OLEACC provides a proxy object for the UI element and attempts to return meaningful
information on its behalf. For more information about WM_GETOBJECT, see How
WM_GETOBJECT Works.

What Information Is Exposed
OLEACC uses the UI element's windows class name to determine what information should be
exposed for each of its IAccessible properties and how to collect that information. For example,
OLEACC calls the GetWindowText API to retrieve the Name property for a standard push
button, but calls this same API to retrieve the Value property for a standard edit control. In effect,
OLEACC is mapping each IAccessible method to an appropriate Win32® or control-specific
message or API call. By using this class name-based special casing, it can return meaningful
information through IAccessible proxies without any Active Accessibility support in the server.
Applications built with standard UI elements typically get full Active Accessibility support without
additional development work. The exceptions to this rule are controls that have been subclassed,
that do not store their own strings (absence of the HASSTRINGS style), or that are owner-drawn.
In these cases, OLEACC cannot gather the information it needs because the information is stored
outside the control. However in many of these scenarios, established workarounds, or the use of
Dynamic Annotation, allow the server to cooperate with the proxies provided by OLEACC.

Generic Proxy Objects
If OLEACC does not recognize the class name of the UI element, it creates a generic proxy that
exposes as much information as possible. At most, this includes the object's bounding rectangle,
parent object, name (from WM_GETTEXT), and any children in the window hierarchy.

Client-Server Communication
The WinEvent mechanism provides a way for servers to communicate easily with Active
Accessibility clients. Clients often collect information by reacting to WinEvents (for example,
following focus), but they are free to request information from a server at any time.
To request information for an accessible object that generates a WinEvent, a client must process
the event and establish a connection with the relevant accessible object. To do this, the client
performs the following six steps:
1. A server calls NotifyWinEvent to generate a WinEvent notification for each change to its
user interface elements.


2. The WinEvent management code in USER determines if any client applications have
registered a WinEvent hook function using SetWinEventHook and calls the registered
callback procedure.
3. In its callback function, the client requests access to the object that generated the event by
calling AccessibleObjectFromEvent or other accessible object retrieval functions. For
more information, see Retrieving an IAccessible Object.
4. This Active Accessibility API sends the server application a WM_GETOBJECT message to
retrieve the accessible object.
5. In response to WM_GETOBJECT, the server application either returns zero or returns a
value that acts as a one-time reference to the object that generated the event.
6. If the server returns zero, Active Accessibility creates a proxy object and gives its address to
the client. Otherwise, Active Accessibility uses this reference to retrieve the address of an
object interface such as IAccessible or IDispatch, and gives that address to the client.

Once the client has an interface address, it can call the IAccessible properties and methods of
the accessible object to retrieve information.
For more information about the client-server communication, see the following topics:
WinEvents
How WM_GETOBJECT Works
Retrieving an IAccessible Object

WinEvents
Microsoft® Active Accessibility® provides a mechanism called WinEvents that allows the operating
system and servers to notify clients when an accessible object changes. There are numerous
conditions in which a server notifies a client of a change. Each event constant defined by Active
Accessibility describes a condition about which a client is notified.
For example, WinEvents can signal:
When an object is created or destroyed.
When an object receives or loses focus.
When an object's state or location changes.
When any of an object's properties change.

Client applications do not receive event notifications automatically; they must specify which
events they want to receive by calling SetWinEventHook. With SetWinEventHook, a client
registers to receive one or more events and sets a hook function to handle the specified events.
Clients can call SetWinEventHook more than once to register different hook functions. Also,
clients may reuse the same hook function, or use a different hook function for additional event
notifications.
Hook functions are located within the client's code body, in a dynamic-link library (DLL) mapped
into the client's process, or in a DLL mapped into the server's process. Each of these methods
has advantages and disadvantages. For more information, see In-Context and Out-of-Context
Hook Functions.
To notify clients of an event occurrence, servers call NotifyWinEvent. The system checks
whether any client applications have set hook functions for the event and calls the appropriate
hook functions as necessary.


When the client's hook function is called, it receives a number of parameters that describe the
event and the object that generated the event. To gain access to the object that generated the
event, the client hook function calls AccessibleObjectFromEvent.

Note
If no clients have registered to receive WinEvents, the performance impact on a server for
calling NotifyWinEvent is negligible.
Servers call NotifyWinEvent for changes only in their own accessible objects; they do not
call NotifyWinEvent for changes in system-provided user interface elements.

Event-Driven Communication
Clients must register a WinEvent hook before they can receive WinEvent notifications. To avoid
unnecessary callbacks and improve performance, clients are advised to register only for the
events they need to receive.
Inside the hook procedure, the client can call AccessibleObjectFromEvent to retrieve an
IAccessible object for the element to which the event applies. With this object, the client can
begin calling IAccessible methods to retrieve information or interact with the UI element.

How WM_GETOBJECT Works
Active Accessibility sends the WM_GETOBJECT message to the appropriate server application
when a client calls one of the AccessibleObjectFromX APIs. The following list describes the
various scenarios that occur:
If the window or control that receives WM_GETOBJECT implements IAccessible, the
window returns a reference to the IAccessible interface using the API LresultFromObject.
Active Accessibility, in conjunction with the COM library, performs the appropriate marshaling
and passes the interface pointer from the server back to the client.
If the window that receives the message does not implement IAccessible, it should return
zero.
If the window does not handle the WM_GETOBJECT message, the Microsoft Win32 API
DefWindowProc returns zero.

Even if the server returns zero, Active Accessibility still provides the client with information about
the object. For most system-provided objects such as list boxes and buttons, Active Accessibility
provides complete information; for other objects, the information is limited. For example, Active
Accessibility does not provide information for controls that do not have an hwnd. Active
Accessibility returns a proxied IAccessible interface pointer that the client uses to get information
about the object.

Retrieving an IAccessible Object
Microsoft® Active Accessibility® provides application programming interfaces (APIs) such as
AccessibleObjectFromWindow and AccessibleObjectFromPoint that allow clients to retrieve
accessible objects. These functions return either an IDispatch or IAccessible interface pointer
through which clients get information about the accessible object.
When a client calls AccessibleObjectFromWindow or any of the other
AccessibleObjectFromX APIs that retrieve an interface to an object, Active Accessibility sends
the WM_GETOBJECT window message to the applicable window procedure within the
appropriate application. To provide information to clients, servers must respond to the
WM_GETOBJECT message.


To collect specific information about a UI element, clients must first retrieve an IAccessible for
the element. To retrieve an element’s IAccessible object, clients can use one of the
AccessibleObjectFromX APIs:
AccessibleObjectFromPoint
AccessibleObjectFromWindow
AccessibleObjectFromEvent

Û To retrieve an IAccessible Interface Pointer
1. Client calls AccessibleObjectFromX.
2. OLEACC sends a WM_GETOBJECT message to server.
3. The server determines which UI element corresponds to the request.
4. The server either returns zero to request an OLEACC proxy,
– Or –
Returns an IAccessible object (native implementation). To do this, it:
a. Constructs an IAccessible object for the element.
b. Calls Lresult FromObject to marshal the object’s pointer.
c. Returns the LRESULT to OLEACC.
5. OLEACC examines the return value from WM_GETOBJECT.
If it is zero, OLEACC constructs a proxy object and returns it to the client.
– Or –
If it is nonzero, OLEACC calls ObjectFromLresult to unmarshal the native IAccessible
object pointer and returns it to the client.

Server Guidelines
For Microsoft® Active Accessibility® to work as designed, servers must provide accessibility
information to clients. Active Accessibility server developers should make their applications more
accessible by following the guidelines in The Microsoft Windows Guidelines for Accessible
Software Design. This document is available on the Microsoft Accessibility Web site at
www.microsoft.com/enable.
To implement IAccessible, server developers follow this basic process.
1. Create accessible objects by implementing the IAccessible properties and methods for
your custom user interface elements and for your application's client. Be sure to provide a
dual interface that supports both IAccessible and IDispatch so that clients written in
Microsoft Visual Basic® and various scripting languages can get information about the
objects.
2. Call NotifyWinEvent to notify clients of changes to your custom user interface elements.
3. Handle WM_GETOBJECT to provide access to your accessible objects.

To qualify to use the Microsoft Windows logo, the logo program requires that applications support
a number of accessibility features. For more information, see the Microsoft Accessibility Web site
at www.microsoft.com/enable.
For suggestions and guidelines for designing accessible objects, see Developer's Guide for
Active Accessibility Servers.

How Servers Implement Child IDs


Server developers can assign child IDs to both simple elements and accessible objects.
However, the recommended approach is to support the standard COM interface IEnumVARIANT
in every accessible object that has children.
If you implement IEnumVARIANT, you must:
Enumerate all children, both simple elements and accessible objects. Provide child IDs for all
simple elements and provide the IDispatch interface to each accessible object.
Allocate space for each VARIANT structure. Note that it is the responsibility of the client to
free the memory used for each VARIANT structure. Clients should also call
IUnknown::Release on any IDispatch interface that is returned.
For accessible objects, set the vt field of the VARIANT structure to VT_IDISPATCH. The
pdispVal field must contain a pointer to the IDispatch interface.
For simple elements, the child ID is any 32-bit positive integer. Note that zero and negative
integers are reserved by Active Accessibility. Set the VARIANTstructure's vt member to
VT_I4 and the lVal member to the child ID.

If you do not support IEnumVARIANT, you must assign child IDs and number the children in
each object sequentially starting with one.
For more information about IEnumVARIANT, see the Platform SDK documentation.
It is recommended that clients use the Active Accessibility API AccessibleChildren rather than
call the server's IEnumVARIANT interface directly.

Client Guidelines
Client developers should use the following functionality to get information about the user interface
elements:
To get an IAccessible interface to objects, call AccessibleObjectFromWindow,
AccessibleObjectFromPoint, or AccessibleObjectFromEvent.
To examine and manipulate accessible objects, use the IAccessible properties and
methods.
To receive WinEvents, call SetWinEventHook to register a WinEvent callback function for
those events that are relevant to the client application.

How Clients Obtain Child IDs
Client developers can get an object's child ID in the following ways:
Call AccessibleChildren, which passes back an array of VARIANT structures.
Query the object to see if it supports the IEnumVARIANT interface. If it does, enumerate its
children, which is what AccessibleChildren does.
Collect the child IDs by calling the parent object's IAccessible::accNavigate method.

Note
It is the responsibility of the client to free the memory used for the VARIANTs. Clients also
must call IUnknown::Release on any IDispatch interface that is returned.

COM and Unicode Guidelines


Because Microsoft® Active Accessibility® is based on COM, developers need a moderate level of
understanding about COM objects and interfaces and must know how to perform basic tasks (for
example, how to initialize the COM library). Server developers need to understand how to design
classes that implement the IAccessible interface and how to create accessible objects.
You also need a moderate level of understanding about Unicode to use many of the Active
Accessibility functions that return strings.
To use Active Accessibility effectively, you should understand the following COM and Unicode
functions, structures, data types, and interfaces.
Functions OleInitialize
CoInitialize
AddRef and Release
VariantInit and VariantClear
MultiByteToWideChar and
WideCharToMultiByte
SysAllocString and SysFreeString
Structures and data types VARIANT
HRESULT
BSTR
COM interfaces IUnknown
IDispatch
IEnumVARIANT

Limited information about some of these items is provided in this documentation. For a
description of standard COM parameter attributes [in], [out], [in/out], and [out, retval], see
Definitions of Parameter Attributes.

VARIANT Structure
Most of the Active Accessibility functions and the IAccessible properties and methods take a
VARIANT structure as a parameter. Essentially, the VARIANT structure is a container for a large
union that carries many types of data.
The value in the first member of the structure, vt, describes which of the union members is valid.
Although the VARIANT structure supports many different data types, Active Accessibility uses
only the following types.
vt Value Corresponding value member name
VT_I4 lVal
VT_DISPATCH pdispVal
VT_BSTR bstrVal
VT_EMPTY none

When you receive information in a VARIANT structure, check the vt member to find out which
member contains valid data. Similarly, when you send information using a VARIANT structure,
always set vt to reflect the union member that contains the information.
Before using the structure, initialize it by calling the VariantInit COM function. When finished with
the structure, clear it before the memory that contains the VARIANT is freed by calling
VariantClear.


For more information about the VARIANT structure, refer to the Automation documentation in the
Platform SDK.

IDispatch Interface
The IDispatch interface was initially designed to support Automation. It provides a late-binding
mechanism to access and retrieve information about an object's methods and properties.
Previously, server developers had to implement both the IDispatch and IAccessible interfaces
for their accessible objects; that is, they had to provide a dual interface. With Active Accessibility
2.0, servers can return E_NOTIMPL from IDispatch methods and Active Accessibility will
implement the IAccessible interface for them.
In addition to the methods inherited from IUnknown, server developers must implement the
following methods within the class definition of each object that is exposed:
GetTypeInfoCount—returns the number of type descriptions for the object. For objects that
support IDispatch, the type information count is always one.
GetTypeInfo—retrieves a description of the object's programmable interface.
GetIDsOfNames—maps the name of a method or property to a DISPID, which is later used
to invoke the method or property.
Invoke—calls one of the object's methods, or gets or sets one of its properties.

Converting Unicode and ANSI Strings
Active Accessibility uses Unicode strings as defined by the BSTR data type. If your application
does not use Unicode strings, or if you want to convert strings for certain API calls, use the
MultiByteToWideChar and WideCharToMultiByte Microsoft® Win32® functions to perform the
necessary conversion.
Use WideCharToMultiByte to convert a Unicode string to an ANSI string. The
MultiByteToWideChar function converts an ANSI string to a Unicode string.
Use SysAllocString and SysFreeString to allocate and free BSTR data types.
For more information about these string functions, see their references in the Platform SDK.

MSAA_v2.docx

Empfohlen

Empfohlen

Weitere ähnliche Inhalte

Was ist angesagt?

Was ist angesagt? (19)

Andere mochten auch

Andere mochten auch (20)

Ähnlich wie MSAA_v2.docx

Ähnlich wie MSAA_v2.docx (20)

Kürzlich hochgeladen

Kürzlich hochgeladen (20)

MSAA_v2.docx