README.TXT for Microsoft Active Accessibility(tm)
Software Developers Kit version 1.0 
Copyright (c) 1996-1997 by the Microsoft Corporation.
All Rights Reserved

------------------------
How To Use This Document
------------------------
To view Readme.txt on screen in Notepad, maximize the Notepad 
window.
To print Readme.txt, open it in Notepad or another word processor, 
then use the Print command on the File menu.
To view Readme.txt in DOS with page breaks, use the following 
command (without the quotes):
"TYPE README.TXT | MORE"

The most current release notes for Microsoft Active Accessibility
can be found via a link from the Microsoft Accessibility and 
Disabilities group web site located at 
http://microsoft.com/enable/.

--------
Contents
--------
Installing Microsoft Active Accessibility SDK
Replacing Core Components
Known Issues and Bugs
Application Compatibility
Building the Sample Applications and Utilities
Reporting Bugs
More Information

Installing Microsoft Active Accessibility SDK
=============================================
If you downloaded the MSAASDK.EXE file, then all that needs to be 
done is to execute the file from within Windows 95.  If you are 
running from the Active Accessibility CD-ROM, then executing the 
SETUP.EXE file from the root of the CD-ROM drive will start the 
install program.  You can also install from the CD-ROM by opening 
the My Computer icon on the desktop, selecting the CD-ROM drive 
and then using the "Install MSAA SDK" option on the File menu.
You should uninstall any Beta versions of the Active Accessibility 
SDK before proceeding.  If any MSAA sample applications are
running and the setup programs attempts to overwrite them, an 
error will occur.

NOTE: Active Accessibility only works under Windows 95.  It will 
not operate on any version of Windows prior, including Windows 
3.1, 3.11 nor Windows for Workgroups 3.1 and 3.11.  Support for 
Windows NT will be included in a future release.  For now, the 
setup program will refuse to run on any version of Windows NT.

When run, the setup program will copy the required files to 
your hard drive and ask if you want to install Active 
Accessibility.  Selecting "No" will cancel the installation and 
clean up the temporary files. Selecting "Yes" will display the 
license agreement.  You must read the license agreement.  After 
reading the agreement, choose the "Yes" button to continue.

The Setup program will install the core system components and
then prompt you for what SDK components to install, and where 
to install them.  NOTE: Exiting setup at this point will not 
uninstall the core system components.

IMPORTANT NOTE:  If you installed a beta version of the MSAA SDK,
you will be prompted when replacing core components.  This is 
because the beta versions of the MSAA SDK used higher version
numbers than the final release.  If you are running Windows 95
you should respond "No" to the "Do you want to keep the file 
currently on your computer?" prompt.  This is only valid if you
installed a beta version of the MSAA SDK.

Once completed, the installation program will prompt you to reboot 
your computer.  This is necessary because some system components 
are updated. Shut down any applications you might have running and 
select the "Yes" button.

You can explore the Microsoft Active Accessibility items under the 
Programs group in the Start Menu.  For more details on the 
applications and utilities provided, refer to the documentation.

To uninstall Active Accessibility, see the "Uninstall" section 
later in this document.

Replacing Core Components
=========================
The following system components located in the \WINDOWS\SYSTEM 
folder are updated when the Active Accessibility SDK is installed:
USER.EXE
USER32.DLL
GDI.EXE
GDI32.DLL
OLEAUT32.DLL
COMCTL32.DLL
STDOLE2.TLB

NOTE:  The original versions of these files are not restored when 
Active Accessibility is uninstalled.  The SDK SETUP program makes 
a copy of the core components in the \WINDOWS\SYSTEM\MSAABAK 
folder before updating these files.

It should never be neccessary to restore COMCTL32.DLL, 
OLEAUT32.DLL, and STDOLE2.TLB.  Doing so might render applications 
which depend on a newer version of these files inoperable.

For more information, please refer to the README.TXT file in the 
MSAABAK directory.

Known Issues
============
Documentation Fixes

The most current documentation can be found via a link from the
Microsoft Accessibility and Disabilities group web site located
at http://microsoft.com/enable/.

* The documentation for MSAA omits the following ROLE constants
that are included in OLEACC.H:
ROLE_SYSTEM_ANIMATION
ROLE_SYSTEM_CLOCK
ROLE_SYSTEM_EQUATION
ROLE_SYSTEM_INDICATOR
ROLE_SYSTEM_PAGETABLIST
ROLE_SYSTEM_PROPERTYPAGE
ROLE_SYSTEM_TOOLTIP
ROLE_SYSTEM_WHITESPACE

* ROLE_SYSTEM_HELPBALLON is defined as ROLE_SYSTEM_HELP in the
documentation.  ROLE_SYSTEM_HELPBALLON is the valid role.

* The data type returned from get_accHelpTopic is a pointer to a
LONG.  If calling the WinHelp() API, you need to cast this value
to a ULONG data type.

* Calling accDoDefaultAction on system and common controls will
observe the current keyboard status.  For example, if the SHIFT
key is down when accDoDefaultAction is called on a list view icon,
the system will open that item up as if the user held down the
shift key while double-clicking.

* Documentation clarification:  It's important that an object 
parent that returns VT_I4 for the child type is responsible for
handling all the properties and methods for that child.  If the
child is an object itself, the parent should provide VT_IUNKNOWN
as the child type, allowing the client to get the IUnknown
interface from the child and communicate directly with it.

* The WINUSER.H file included with the MSAA SDK is different from
the one included in Microsoft Visual C++ version 4.1 and greater.
If errors occur when compiling your code, manually copy the 
missing definition from one WINUSER.H to the other.  

SDK Package

* Please note that a frames compatible browser is required to view 
the HTML documentation.  Microsoft Internet Explorer 3.0 is a 
highly accessible, frames compatible browser that is available 
for free from http://microsoft.com/ie/.

* The source code for the DDIHOOK sample application does not 
include a MSVC++ build environment. 

* Source code to BABBLE, a sample talking application is included 
in the \SAMPLES directory.  BABBLE is incomplete at this time 
and requires that the Microsoft Speech API (SAPI) be installed.  
Additionally, a Text to Speech (TTS) engine must be installed.  
A TTS engine is not provided in either the Active Accessibility 
or Speech SDK's.  See the ENGINES.DOC in the Speech SDK for a 
listing of companies that produce TTS engines.

* The Microsoft Off-Screen Model is not included in this release 
of the Active Accessibility SDK.  It will be included in a 
later release.

* Possible incompatibilities with existing accessibility aids.  
Many accessibility aids use unsupported in-memory patching 
techniques that are incompatible with the new core components 
supplied with Active Accessibility.  If you have difficulty with 
your accessibility aid after installing Active Accessibility, 
please contact the vendor for an update.

* The Microsoft Magnifier accessory will cause the mouse pointer
to flash if any mouse pointer scheme other than "Windows Standard"
is used.  This includes "Windows Standard (large)" and "Windows
Standard (extra-large)".

* INSPECT and OACSPY conflict with each other.

* INSPECT has shortcut keys that may conflict with existing 
applications. INSPECT uses CTRL+SHIFT+Fx keys.

* INSPECT might freeze while trying to navigate Office
97 menus.  This will occur if the menu is not popped up and
INSPECT has to navigate all the off-screen children of a menu.

* The Accessible Event Watcher's horizontal scroll bar is not 
operational with this release.

* The debug version of INSPECT does not observe the buffer size
in GetObjectProperty.  This might result in a GPF when
GetObjectProperty formats and returns an error string that is
longer than 64 bytes.

* Uninstalling the SDK only removes components that were 
installed.  If you add files to the Active Accessibility 
directory, they will not be removed and the directory structure 
will be preserved.  This is also true of files that are in use 
at the time of un-installation.

Common and System Controls
* When the accSelect(SELFLAG_TAKEFOCUS) method is called on a 
static text object, we currently return DISP_E_MEMBERNOTFOUND.  
We will change this so that the first focusable item after the 
static text gets the focus. This is similar to the way that USER 
works when you send a WM_SETFOCUS message to a static text 
control.

* Internet Explorer's toolbar buttons do not return a state of 
Hot-Tracked.

* Embedded objects in WordPad are exposed with a "Editable text" 
role.

* Support for the Multi-line Edit control and the Richedit control 
is minimal.  This will be improved in a later release.

* The INSPECT sample applet always uses the cursor position to 
navigate from. This may lead to apparently strange traversal 
orders when using INSPECT's navigate next/previous commands 
(CTRL+SHIFT+F6/F7). 

* Owner-drawn controls do not return names and values.  The data
for such is kept inside of the application using the control and
not the control itself.  The Windows Explorer combo box on the
toolbar is an example of this.

* Progress bars do not expose a name.

* Standard controls show that the parent of a button is an 
intermediary window. For example, the Inspect tool shows that 
the parent of an OK button is the OK Window.  

* The right side of the taskbar (where the clock and "taskbar 
icons" are displayed) is not exposed via Active Accessibility.

* MSAA does not expose help popup text generated with right 
mouse click.

* Animated GIF's in Microsoft Internet Explorer do not have a role 
of "Animated".  This will be fixed in a later version of Internet 
Explorer.

* Text strings in Microsoft Internet Explorer 3.0 are broken up 
according to the HTML coding and the width of the window.  No 
text string exposed by Active Accessibility will be longer than 
the line that it appears on.

* The MS-DOS Prompt window has an optional toolbar.  This Toolbar 
is implemented in 16-bit code and is not available to be exposed 
by Active Accessibility

* The Device Manager in System Control Panel is implemented using 
16-bit code and is not available to be exposed by Active 
Accessibility.

* The Titlebar of an application has the state of "Focusable" but 
it can never have a state of "Focused".  This is a special case.  
Setting focus to a titlebar object actually focuses the 
application window.

* Owner-drawn menu items, such as the list of file types in the 
File->New context menu, do not display their Name or 
KeyboardShortcut properties.  This is true also of the Favorites 
menu in Microsoft Internet Explorer.

* Static controls that have SS_ICON style set might return garbage
for a name.

* Multi-column menus do not support NAVDIR_LEFT/NAVDIR_RIGHT.

* Calling accSelect() with SELFLAG_TAKEFOCUS will not work
on a menu popup item.  You can use accDoDefaultAction to open or 
close a menu popup.

* When Windows Explorer is in the Details View, it's not possible
to navigate to the header control.  You can use 
AccessibleObjectFromPoint() to get to the object however.

Application Compatibility
=========================
While every effort has been made to make Active Accessibility as 
high-quality as possible, there are some applications which depend 
on certain unsupported techniques which break with the sample 
programs that are part of MSAA.  The following is a list of known 
applications compatibility issues:

* Asking for Name properties on invisible windows when a
EVENT_OBJECT_DESTORY event occurs can cause a GPF in OLEAUT32.DLL.

* Spy++ (shipped with Microsoft Visual C++ 2.0 and later) doesn't 
work with ACCEVENT. SPYXX causes an invalid page fault in module 
COMCTL32.DLL.

* Beta versions of Word 97 sometimes cause a page fault when 
closing down if the INSPECT tool is running.

* Running SNAPSHOT against a Microsoft Office 97 application or
Visual Basic 5.0 is extremely slow.

* The Page Setup dialog in Microsoft Access 97 does not expose its 
controls properly.

* With Microsoft Access 2.0 and the Accessible Event Watcher 
running, General Protection Faults might occur when closing a 
Cue Card window.  This is a bug in Access 2.0 and does not occur 
in later versions.

* Navigating to a unvailable button in Word 97 returns E_FAIL
when using NAVDIR_FIRSTCHILD/LASTCHILD.

* Lotus 1-2-3 Release 5 uses list boxes which are incompatible
with MSAA.  Attempts to get the name of a list box item always
return the first item in the list.

* Microsoft Office applications that use SDM controls do not
return accValue in list boxes.

* Microsoft Visual Studio 97 has menus and tools bars which 
appear similar to the menus and tool bars present in Office 97.
However, Visual Studio 97 has not implemented MSAA to those
menus.  To work around this issue, select the "Use screen reader
compatible menus" in the Options/Workspace dialog.

* Microsoft Office 97 returns redundent entries for the Menu Bar
object.

Building the Sample Applications and Utilities
==============================================
All the samples (except DDIHOOK) can be built using Microsoft 
Visual C++ version 4.0 or greater.  We used MSVC++ version 4.2 
for testing purposes.

Before you can compile the sample sources, you must configure 
MSVC++ to search the \INC32 and \LIB directories.  Within MSVC++ 
4.x go to the Tools menu and choose Options.  From the Options 
dialog, choose the Directories property sheet.  Set the "Show 
directories for:" list box to "Include files" and then go to the 
Directories list box.  Add the following: "<msaa pathname>\inc32" 
where <msaa pathname> is the drive and directory where you 
installed MSAA.  If you accepted the default, this would be: 
c:\program files\active accessibility\inc32

Place this directory at the top of the list using the up and down 
buttons. There seems to be no keyboard way of doing this, it must 
be done via the mouse pointer.

Repeat the same steps for the "Libraries" option and instead of 
putting in "<msaa pathname>\inc32", put in "<msaa pathname>\lib" 
and make sure it is at the top of the list.

You can then open the .MAK files found in the \SAMPLES directories 
using the Open Workspace option on the file menu.  Note that by 
default, MSVC++ wants to open .MDP files.  MSAA provides .MAK 
files.  Change this in the Open Workspace dialog by selecting 
"Files of type:" and choosing "Makefiles (*.mak)".  After you 
compile for the first time, a .MDP file is created.

Reporting Bugs
=============
Please E-mail msaabug@microsoft.com with as much information 
as practical concerning the difficulty.

Please monitor our newsgroup as well, listed below.

A bug report should contain the version number of OLEACC.DLL and 
the steps used to reproduce the problem.  If a fault dialog 
appeared, please copy the text from the Details section.  The
version number of a DLL can be gotten by selecting the DLL in 
Windows Explorer and pressing ALT+ENTER.  Then choose the 
version tab.

More Information
===============
You can get more information about Microsoft Active Accessibility,
including the current release notes and documentation, from the 
following internet locations:

Email:		abletech@microsoft.com (technical questions)
                msaabug@microsoft.com (bug reporting)

WWW:		http://microsoft.com/enable/

Newsgroup:	microsoft.public.accessibility.axa available 
                from the NNTP server msnews.microsoft.com
