MSAA_v2.docx

1. Microsoft Active Accessibility Version 2.0 Legal InformationInformation in this document, including URL and other Internet Web site references, is subject tochange 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 applicablecopyright laws is the responsibility of the user. Without limiting the rights under copyright, no partof this document may be reproduced, stored in or introduced into a retrieval system, ortransmitted in any form or by any means (electronic, mechanical, photocopying, recording, orotherwise), or for any purpose, without the express written permission of Microsoft Corporation.Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectualproperty rights covering subject matter in this document. Except as expressly provided in anywritten license agreement from Microsoft, the furnishing of this document does not give you anylicense 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 ofMicrosoft Corporation in the U.S.A. and/or other countries.The names of actual companies and products mentioned herein may be the trademarks of theirrespective owners. Legal Information .....................................................................................................................................iCHAPTER 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? ................................................................ 3CHAPTER 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 2. Microsoft Active Accessibility iiCHAPTER 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 .................................................................................................. 21CHAPTER 4: C/C++ DEVELOPERS 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 3. Microsoft Active Accessibility iii Alerts ..................................................................................................................................................................48 Developers 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 Developers 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 ........................................................................................................ 64CHAPTER 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 4. 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 .................................................................................................................... 91DYNAMIC 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 5. 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 .............................................................................................. 158APPENDIXES ........................................................................................................................................... 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 6. 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 ................................................................................................... 216GLOSSARY ............................................................................................................................................... 219 7. Chapter 1Getting StartedMicrosoft® Active Accessibility® 2.0 is a set of COM interfaces and APIs that provides a reliableway to expose and collect information about Microsoft Windows-based user interface (UI)elements and Web content. Using this information, Assistive Technology Vendors can representthe UI in alternative formats, such as speech or Braille, and voice command and controlapplications can remotely manipulate the interface. Active Accessibility relies on Windows ®technology and can be used in conjunction only with Windows-based controls and other Windowsapplications.This documentation is organized to meet the needs of developers new to, as well as thosefamiliar 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++ Developers 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 ComponentsThe Active Accessibility SDK contains the following components: Header and lib files Tools Header and Lib Files 8. Microsoft Active Accessibility 2The 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 ToolsThe Active Accessibility SDK includes the following tools for testing. For more information aboutthe 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 PlatformsActive Accessibility 2.0 supports most Microsoft platforms and is included as part of the WindowsXP 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 Accessibility2.0 Redistribution Kit (RDK) to upgrade. This RDK contains all of the core system files needed to 9. Microsoft Active Accessibility 3incorporate Active Accessibility 2.0 technology into client and server applications. It supportsMicrosoft Windows® 98, Microsoft Windows NT® version 4.0 with Service Pack 6 or later, andMicrosoft 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 thatsupports it. Note that Windows CE and Windows 3.1 are not supported by any ActiveAccessibility 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? 10. Microsoft Active Accessibility 4To find out which version of Active Accessibility is installed on your system, you should check theversion of the Oleacc.dll file in the system32 folder on your hard drive. The following table mapsthe 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 11. Microsoft Active Accessibility 5Chapter 2Release InformationThis 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.0Microsoft® Active Accessibility® 2.0 has several updates and changes reflected in the SDKdocumentation.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 appropriatesections in the documentation and are summarized in the following table. Feature ChangeDynamic 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 NotesThe following section describes known issues identified in Microsoft® Active Accessibility® 2.0 aswell as changes in behavior that have occurred since Active Accessibility 1.3. This information iscurrent as of July 2001. For updated information, please see the Accessibility home page onMSDN. Known Issues Changes in Behavior 12. Microsoft Active Accessibility 6 Known IssuesThe following section contains known issues that have been identified in Microsoft ® ActiveAccessibility® 2.0. These issues are current as of July 2001. For updated information, please seethe Accessibility home page on MSDN. Unsupported IAccPropServices MethodsThe IAccPropServices interface contains several methods designed for annotating menus thatare not currently implemented. For this reason, the following methods are not currentlydocumented in the platform SDK: SetHmenuProp SetHmenuPropStr ClearHmenuProps SetHmenuPropServer DecomposeHmenuIdentityString ComposeHmenuIdentityStringAnother approach exists for developers who are interested in customizing the informationexposed through Active Accessibility. For more information about annotating menus, see thefollowing 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.0Active Accessibility 2.0 does not currently support Microsoft Windows ® 95, Microsoft Windows2000, or Microsoft Windows Me. Operating Systems Supported by the Active Accessibility 2.0 Redistribution KitThe Active Accessibility 2.0 RDK supports Microsoft Windows NT ® 4 Service Pack 6 andMicrosoft Windows 98. If you upgrade your operating system or apply a service pack, you mustreinstall the RDK.If you wish to repair or remove Active Accessibility 2.0, from Control Panel, double-clickAdd/Remove Programs, select Microsoft Active Accessibility 2.0, and then clickChange/Remove. Note that this method completely removes Active Accessibility and does notrevert to a previous version. Text Services Supported by RichEdit 3.0 OnlyThe Active Accessibility 2.0 Text Services APIs are supported only by RichEdit 3.0, which shipswith Microsoft Office XP. Active Accessibility 2.0 Tools Currently Not Available for 64-Bit Operating Systems 13. Microsoft Active Accessibility 7Currently 64-bit versions of the Inspect Object, Accessible Event Watcher, and AccessibleExplorer tools do not exist for the IA64 version of Windows XP. You should use the 32-bit versionof these tools on this operating system. Clients Using Word XP Implementation of ITextStore Must Be RebootedFor Text Services to work properly with Microsoft Word XP, you must restart your system afterinstalling Active Accessibility 2.0. IAccPropServices::SetPropServer Does Not Manage the Callback Server Properly When Invalid Parameters Are UsedIn Active Accessibility 2.0, the IAccPropServices::SetPropserver method increments thereference count and does not release the callback server when invalid parameters are used. Oleacc Caret Location Inaccurate on Systems without Right-to-Left Support EnabledThe x coordinate for the caret proxy is inaccurate by three pixels. Use the rcCaret value returnedby the GetGUIThreadInf function to determine the correct location of the caret. Changes in BehaviorThe following issues have been resolved with Microsoft ® Active Accessibility® 2.0. Multiple Document Interface Support for IAccessibleIn 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 documents toolbar. Theseicons are used on multiple document interfaces. IAccessible::accSelect Now Fully ImplementedThe accSelect method has been fully implemented for all proxies and can be used toprogrammatically switch focus between applications in Windows. New State: STATE_SYSTEM_HASPOPUPThe STATE_SYSTEM_HASPOPUP state indicates whether an object has a pop-up menuassociated with it. Controls such as the Start menu use the flag to report this capability tovendors. IAccessible::accLocation Returns Accurate Information for Vertical Slider Bar CoordinatesIn previous versions of Oleacc, the x and y coordinates were reversed for vertical slide bars. Thisissue has been resolved for Active Accessibility 2.0. New Role: ROLE_SYSTEM_SPLITBUTTONThe ROLE_SYSTEM_SPLITBUTTON role identifies controls that contain a both a button and alist. For more information, see ROLE_SYSTEM_SPLITBUTTON in the Object Roles section inthe C/C++ Reference. Oleacc Now Supports SysIPAddress32 14. Microsoft Active Accessibility 8Oleacc now supports the SysIPAddress32 control. 15. Microsoft Active Accessibility 9Chapter 3Technical OverviewMicrosoft® Active Accessibility® improves the way accessibility aids (specialized programs thathelp people with disabilities use computers more effectively) work with applications running onMicrosoft Windows®.Active Accessibility is based on the Component Object Model (COM), which was developed byMicrosoft and is an industry standard that defines a common way for applications and operatingsystems 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 usethem: How Active Accessibility Works Active Accessibility Basics Server Guidelines Client Guidelines COM and Unicode Guidelines How Active Accessibility WorksMicrosoft® Active Accessibility® is designed to help accessibility aids, called clients, interact withstandard 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, ormanipulate the UI elements of an application. Clients include accessibility aids, automated testingtools, and some computer-based training applications.Using Active Accessibility, a client application can: 16. Microsoft Active Accessibility 10 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 serveruses 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 interfaceis considered an Active Accessibility server. Servers communicate with clients by sending eventnotifications (such as calling NotifyWinEvent) and responding to client requests for access to UIelements (such as handling WM_GETOBJECT messages sent from OLEACC). Servers exposeinformation 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 processors customtoolbar, a speech recognition program must have information about that toolbar. The wordprocessor would therefore need to make that information available. Active Accessibility providesthe means for the word processor to expose information about its custom toolbar and for thespeech recognition program to get that information. Client Applications and Active AccessibilityAn Active Accessibility client must be notified when the servers UI has changed so that it canconvey that information to the user. To ensure that the client is informed about UI changes, itusesa mechanism called Window Events, or WinEvents, to register to receive notifications. For moreinformation, see WinEvents .To learn about and manipulate a particular UI element, clients use the Active Accessibility COMinterface, 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 BasicsThis section addresses the main feature areas of Microsoft® Active Accessibility®. This includesthe following topics: Active Accessibility Objects Types of IAccessible Support 17. Microsoft Active Accessibility 11 Client-Server Communication Active Accessibility ObjectsIn Active Accessibility terminology, there are accessible objects and simple elements. Althoughmost applications contain both, accessible objects are more common than simple elements. Thissection defines and discusses accessible objects and simple elements and provides appropriateUI 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 ObjectsWith Microsoft Active Accessibility, user interface (UI) elements are exposed to clients as COMobjects. These accessible objects maintain pieces of information, called properties, whichdescribe the objects name, screen location, and other information needed by accessibility aids.Accessible objects also provide methods that clients call to cause the object to perform someaction. Accessible objects that have simple elements associated with them are also calledparents, or containers.Accessible objects are implemented using Active Accessibilitys COM-based IAccessibleinterface. The IAccessible methods and properties enable client applications to get informationabout UI elements needed by users. For example, IAccessible::get_accParent returns aninterface pointer to an accessible objects parent, and IAccessible::accNavigate provides ameans for clients to get information about other objects within a container.For more information about how accessible objects and simple elements are related, see SimpleElements. Simple ElementsA simple element is a UI element that shares an IAccessible object with other elements andrelies on that IAccessible object (typically its parent) to expose its properties. To differentiatebetween the elements sharing an IAccessible object, the server assigns a unique, positive childidentifier 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 IDssequentially, beginning with 1. This scheme does not allow simple elements to have children oftheir own. Simple elements are also known as children.To be uniquely identified and exposed, a simple element requires an IAccessible object andchild ID. Therefore, when communicating with an IAccessible object, the clients must supply theappropriate child ID. A special identifier, CHILDID_SELF, can be used to refer to the accessibleobject itself, instead of one of its children.The IAccessible object shared among simple elements often corresponds to a common parentobject in the user interface. For example, system list boxes expose an accessible object for theoverall list box and simple elements for each list box item. In this case, the IAccessible object forthe list box is also the parent or container of the list items.For more information about accessible objects, see Accessible Objects. 18. Microsoft Active Accessibility 12 How Child IDs Are Used in ParametersThis topic describes input parameters, output parameters, and special cases for interpreting childIDs returned from IAccessible methods. Input ParametersMany of the Active Accessibility functions and most of the IAccessible properties take aVARIANT input parameter. For most of the IAccessible properties, this parameter allows clientdevelopers to specify whether they want information about the object itself or about one of theobjects simple elements.Active Accessibility provides the constant CHILDID_SELF to indicate that information is neededabout the object itself. To obtain information about a simple element, client developers specify itschild ID in the VARIANT parameter.When initializing a VARIANT parameter, be sure to specify VT_I4 in the vt member in addition tospecifying 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 objects child elements, initializethe variant for the first parameter of IAccessible::get_accName ( CHILDID_SELF in the lValmember and VT_I4 in the vt member), and then call IAccessible::get_accName. Output ParametersSeveral IAccessible functions and methods have a VARIANT* output parameter that contains achild ID or an IDispatch interface pointer to a child object. There are different steps that a clientmust take depending on whether they receive a VT_I4 child ID (simple element) or an IDispatchinterface pointer with CHILDID_SELF (full object). Following these steps will provide anIAccessible interface pointer and child ID that together allow clients to use the IAccessiblemethods and properties. These steps apply to the IAccessible accHitTest, get_accFocus, andget_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 sothat 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 19. Microsoft Active Accessibility 13 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 COMfunction. When finished with the structure, call VariantClear to free the memory reserved for thatVARIANT. Special CasesThere are exceptions to the guidelines in the above table, such as when a child ID is returned bythe IAccessible::accHitTest method. Servers must return an IDispatch interface if the child isan accessible object. If a child ID is returned by IAccessible::accHitTest, the child is a simpleelement.In addition, there are special cases for accNavigate. For more information, seeIAccessible::accNavigate and Spatial and Logical Navigation. Custom User Interface ElementsServer developers design accessible objects based on an applications user interface (UI).Because Active Accessibility implements the IAccessible interface on behalf of system-provideduser interface elements such as list boxes, menus, and trackbar controls, you need to implementthe 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 applications client window that arent already exposedOwner-drawn controls and menus are accessible as long as you follow the guidelines discussedin Shortcuts for Exposing Custom User Interface Elements. If you follow these guidelines, thenyou 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 systemhandles the basic functionality of the control. However, if a superclassed or subclassed controlsignificantly modifies the behavior of the system-provided control on which it is based, then youmust implement the IAccessible interface. For more information, see Exposing Controls Basedon System Controls.If an application uses only system-provided user interface elements, then it does not need toimplement IAccessible, except for its client window. For example, an application that includes atext 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 asingle string of text in the Value property of the control. Dual Interfaces: IAccessible and IDispatchServer developers must provide the standard COM interface IDispatch for their accessibleobjects. The IDispatch interface allows client applications written in Microsoft Visual Basic © andvarious scripting languages to use the methods and properties exposed by IAccessible. Since anaccessible object provides access to an object either indirectly through IDispatch::Invoke ordirectly with IAccessible, it is said to have a dual interface.When C/C++ clients get back an IDispatch interface pointer, clients can call QueryInterface totry converting the IDispatch interface pointer to an IAccessible interface pointer. To call the 20. Microsoft Active Accessibility 14IAccessible methods indirectly, C/C++ clients call IDispatch::Invoke. For improvedperformance, call the IAccessible methods to use the object directly.For a list of the dispatch IDs (DISPIDs) that IDispatch uses to identify the IAccessible methodsand properties, see Appendix C: IAccessible DISPIDs. System-Provided User Interface ElementsActive Accessibility provides support for most predefined and common controls. The followingillustration shows a typical window and some of the system-provided user interface elements thatActive Accessibility exposes, such as title bars, menus, combo boxes, toolbar controls, tree viewcontrols, status bars, size grips, list view controls, and scroll bars.Active Accessibility exposes system-provided user interface elements to server applicationswithout requiring the server developer to implement the IAccessible interface. Any applicationthat contains these elements automatically inherits their accessibility.For a list of the controls and other system-provided user interface elements that ActiveAccessibility supports, see Appendix A: Supported User Interface Elements Reference. Types of IAccessible SupportActive Accessibility servers have two types of IAccessible support: native and proxied. The UIelements used in an application determine which type of support is appropriate. Many serversbeing written today take full advantage of IAccessible proxies and only implement IAccessiblefor those controls that are not proxied by OLEACC, such as windowless controls or controls witha custom window class name. Native Active Accessibility Implementation IAccessible Proxies Native Active Accessibility ImplementationUser interface elements that implement the IAccessible interface are said to provide a nativeimplementation. Although the development cost for implementing IAccessible (or any other COMinterface) can be high, the benefit is complete control over the information exposed to clients. 21. Microsoft Active Accessibility 15If your application uses custom controls or other controls that cannot be proxied by OLEACC, youwill need to provide a native implementation. IAccessible ProxiesIAccessible proxies provide default accessibility information for standard UI elements: USERcontrols, USER menus, and common controls from COMCTL and COMCTL32. This defaultsupport is exposed through IAccessible objects created by OLEACC and delivers ActiveAccessibility support without additional server development work. The server can then useDynamic Annotation to modify much of the information exposed by OLEACC, but it does not havecomplete control. Creating a ProxyTo determine whether a UI element natively supports the IAccessible interface, OLEACC sendsit a WM_GETOBJECT message. A nonzero return value means the element natively supportsActive Accessibility and provides its own IAccessible support. However, if the return value iszero, OLEACC provides a proxy object for the UI element and attempts to return meaningfulinformation on its behalf. For more information about WM_GETOBJECT, see HowWM_GETOBJECT Works. What Information Is ExposedOLEACC uses the UI elements windows class name to determine what information should beexposed 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 pushbutton, 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-specificmessage or API call. By using this class name-based special casing, it can return meaningfulinformation through IAccessible proxies without any Active Accessibility support in the server.Applications built with standard UI elements typically get full Active Accessibility support withoutadditional 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 storedoutside the control. However in many of these scenarios, established workarounds, or the use ofDynamic Annotation, allow the server to cooperate with the proxies provided by OLEACC. Generic Proxy ObjectsIf OLEACC does not recognize the class name of the UI element, it creates a generic proxy thatexposes as much information as possible. At most, this includes the objects bounding rectangle,parent object, name (from WM_GETTEXT), and any children in the window hierarchy. Client-Server CommunicationThe WinEvent mechanism provides a way for servers to communicate easily with ActiveAccessibility 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 processthe event and establish a connection with the relevant accessible object. To do this, the clientperforms the following six steps: 1. A server calls NotifyWinEvent to generate a WinEvent notification for each change to its user interface elements. 22. Microsoft Active Accessibility 16 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 ofthe 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 WinEventsMicrosoft® Active Accessibility® provides a mechanism called WinEvents that allows the operatingsystem and servers to notify clients when an accessible object changes. There are numerousconditions in which a server notifies a client of a change. Each event constant defined by ActiveAccessibility 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 objects state or location changes. When any of an objects properties change.Client applications do not receive event notifications automatically; they must specify whichevents they want to receive by calling SetWinEventHook. With SetWinEventHook, a clientregisters 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 eventnotifications.Hook functions are located within the clients code body, in a dynamic-link library (DLL) mappedinto the clients process, or in a DLL mapped into the servers process. Each of these methodshas advantages and disadvantages. For more information, see In-Context and Out-of-ContextHook Functions.To notify clients of an event occurrence, servers call NotifyWinEvent. The system checkswhether any client applications have set hook functions for the event and calls the appropriatehook functions as necessary. 23. Microsoft Active Accessibility 17When the clients hook function is called, it receives a number of parameters that describe theevent and the object that generated the event. To gain access to the object that generated theevent, 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 CommunicationClients must register a WinEvent hook before they can receive WinEvent notifications. To avoidunnecessary callbacks and improve performance, clients are advised to register only for theevents they need to receive.Inside the hook procedure, the client can call AccessibleObjectFromEvent to retrieve anIAccessible object for the element to which the event applies. With this object, the client canbegin calling IAccessible methods to retrieve information or interact with the UI element. How WM_GETOBJECT WorksActive Accessibility sends the WM_GETOBJECT message to the appropriate server applicationwhen a client calls one of the AccessibleObjectFromX APIs. The following list describes thevarious 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 aboutthe object. For most system-provided objects such as list boxes and buttons, Active Accessibilityprovides complete information; for other objects, the information is limited. For example, ActiveAccessibility does not provide information for controls that do not have an hwnd. ActiveAccessibility returns a proxied IAccessible interface pointer that the client uses to get informationabout the object. Retrieving an IAccessible ObjectMicrosoft® Active Accessibility® provides application programming interfaces (APIs) such asAccessibleObjectFromWindow and AccessibleObjectFromPoint that allow clients to retrieveaccessible objects. These functions return either an IDispatch or IAccessible interface pointerthrough which clients get information about the accessible object.When a client calls AccessibleObjectFromWindow or any of the otherAccessibleObjectFromX APIs that retrieve an interface to an object, Active Accessibility sendsthe WM_GETOBJECT window message to the applicable window procedure within theappropriate application. To provide information to clients, servers must respond to theWM_GETOBJECT message. 24. Microsoft Active Accessibility 18To collect specific information about a UI element, clients must first retrieve an IAccessible forthe element. To retrieve an element’s IAccessible object, clients can use one of theAccessibleObjectFromX 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 GuidelinesFor Microsoft® Active Accessibility® to work as designed, servers must provide accessibilityinformation to clients. Active Accessibility server developers should make their applications moreaccessible by following the guidelines in The Microsoft Windows Guidelines for AccessibleSoftware Design. This document is available on the Microsoft Accessibility Web site atwww.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 applications 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 supporta number of accessibility features. For more information, see the Microsoft Accessibility Web siteat www.microsoft.com/enable.For suggestions and guidelines for designing accessible objects, see Developers Guide forActive Accessibility Servers. How Servers Implement Child IDs 25. Microsoft Active Accessibility 19Server developers can assign child IDs to both simple elements and accessible objects.However, the recommended approach is to support the standard COM interface IEnumVARIANTin 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 VARIANTstructures 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 ineach 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 thancall the servers IEnumVARIANT interface directly. Client GuidelinesClient developers should use the following functionality to get information about the user interfaceelements: 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 IDsClient developers can get an objects 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 objects 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 26. Microsoft Active Accessibility 20Because Microsoft® Active Accessibility® is based on COM, developers need a moderate level ofunderstanding about COM objects and interfaces and must know how to perform basic tasks (forexample, how to initialize the COM library). Server developers need to understand how to designclasses 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 ActiveAccessibility functions that return strings.To use Active Accessibility effectively, you should understand the following COM and Unicodefunctions, 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 IEnumVARIANTLimited information about some of these items is provided in this documentation. For adescription of standard COM parameter attributes [in], [out], [in/out], and [out, retval], seeDefinitions of Parameter Attributes. VARIANT StructureMost of the Active Accessibility functions and the IAccessible properties and methods take aVARIANT structure as a parameter. Essentially, the VARIANT structure is a container for a largeunion 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 usesonly the following types. vt Value Corresponding value member name VT_I4 lVal VT_DISPATCH pdispVal VT_BSTR bstrVal VT_EMPTY noneWhen you receive information in a VARIANT structure, check the vt member to find out whichmember 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 withthe structure, clear it before the memory that contains the VARIANT is freed by callingVariantClear. 27. Microsoft Active Accessibility 21For more information about the VARIANT structure, refer to the Automation documentation in thePlatform SDK. IDispatch InterfaceThe IDispatch interface was initially designed to support Automation. It provides a late-bindingmechanism to access and retrieve information about an objects methods and properties.Previously, server developers had to implement both the IDispatch and IAccessible interfacesfor their accessible objects; that is, they had to provide a dual interface. With Active Accessibility2.0, servers can return E_NOTIMPL from IDispatch methods and Active Accessibility willimplement the IAccessible interface for them.In addition to the methods inherited from IUnknown, server developers must implement thefollowing 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 objects 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 objects methods, or gets or sets one of its properties. Converting Unicode and ANSI StringsActive Accessibility uses Unicode strings as defined by the BSTR data type. If your applicationdoes not use Unicode strings, or if you want to convert strings for certain API calls, use theMultiByteToWideChar and WideCharToMultiByte Microsoft® Win32® functions to perform thenecessary conversion.Use WideCharToMultiByte to convert a Unicode string to an ANSI string. TheMultiByteToWideChar 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.