Accessibility Probe User's Guide

The Accessibility Probe (AccProbe) can be used to perform the following tasks.

• Viewing the Microsoft Active Accessibility (MSAA) or IAccessible2 hierarchy of a currently running application.
• Examining the accessibility properties of the GUI controls of each application.
• Monitoring the events generated by the GUI controls.

AccProbe combines the functionality found in tools like Microsoft Inspect32, AccExplorer, and AccEvent, into one tool which works for both MSAA and IAccessible2 objects.

AccProbe is a stand-alone Eclipse Rich Client Platform (RCP) application but it does not require the use of the Eclipse development framework.

Accessibility

As an Eclipse RCP application, AccProbe itself is fully accessible. Examples of keyboard navigation within the AccProbe application are:

• to move between views, use CTRL+F7;
• to access the toolbar icons such as the refresh button in the Explorer View press SHIFT-TAB and use the arrow keys to navigate the toolbar buttons.

Go to Eclipse Accessibility for more information on keyboard navigation in an Eclipse application.

AccProbe is provided as a zip file which contains all the components needed for it to run as a standalone Windows application in conjunction with the appropriate Java Runtime Environment. Installation instructions are as follows.

Windows Requirement

AccProbe is currently available for use only on the Microsoft Windows platform. For versions of Windows that support MSAA, see the list of supported platforms in the 'Getting Started' section of the MSAA documentation on the Microsoft Developer Network (msdn) site.

Obtaining the Required Java Runtime Environment

AccProbe currently requires a Java Runtime Environment (JRE) version 1.5.x installation or higher. If a JRE has been previously installed, check the version by opening a Command Prompt window (Start->All Programs->Accessories->Command Prompt) and invoking the command "java -version".

• If this command returns a version of 1.5.x or higher, proceed to the next section for Installing AccProbe.
• If this command returns a version older than 1.5.x (for example 1.4.2), download and install Java 5 or 6 as follows:
• Go to Sun Java 5 Download or Sun Java 6 Download
• Select the latest update from the list of downloads (the JDK includes the Java Runtime Environment (JRE), and follow the installation instructions.

Installing AccProbe

AccProbe is available as a zip file. Obtain and install AccProbe as follows:

• Create a directory which will be used to contain the AccProbe files.
• Get the AccProbe zip file as follows:
  • TODO
  • In the "Accessibility Probe (AccProbe)" section, select the AccProbe zip file and download the file to the directory previously created.
• Locate the AccProbe .zip file (file name format of 'accprobe-(xxxxxx).zip) and unzip the files into the directory of your choice. (This completes the installation process.)

To run AccProbe, simply execute the "accprobe.exe" command. To find this command:

1. Navigate to the directory created when the AccProbe zip file was "unzipped" and locate the 'accprobe' subdirectory.
2. Navigate into this subdirectory and locate the AccProbe executable 'accprobe.exe'.

See the Launching AccProbe section for details on startup options for AccProbe.

IAccessible2 Installation Considerations

To use AccProbe with the IAccessible2 interface, the IAccessible2Proxy.dll must be registered. Two methods to do this are listed below. (Use the correct path to the folder in which AccProbe was installed.)

• From a command prompt, type "regsvr32 'path to accprobe directory'\IAccessible2Proxy.dll"
• Or, from the start menu, choose Run. Type "regsvr32 'path to accprobe directory'\IAccessible2Proxy.dll" in the input field and press the OK button.

(If regsvr32 is not in your path, you may need to use the full path. Usually this is c:\windows\system32\regsvr32).

AccProbe is launched by executing the 'accprobe.exe' application. No command line options are required; for most cases, the option defaults are sufficient.

AccProbe can also be executed with the command line arguments listed below. Note since AccProbe is an Eclipse RCP application, AccProbe can also be executed with any Eclipse command line arguments.

• -consolelog - sends any console log output also to Java's System.out (typically back to the command shell, if any). Aids in debugging when combined with -debug option
• -vm <path to java executable> - when passed to the Eclipse executable, this option is used to locate the Java VM to use to run Eclipse. It must be the full file system path to an appropriate Java executable. If not specified, the Eclipse executable uses a search algorithm to locate a suitable VM. In any event, the executable then passes the path to the actual VM used to Java Main using the -vm argument. Java Main then stores this value in eclipse.vm.
• -vmargs [vmargs*] -when passed to the Eclipse executable, this option is used to customize the operation of the Java VM used to run Eclipse. If specified, this option must come at the end of the command line. Even if not specified on the executable command line, the executable will automatically add the relevant arguments (including the class being launched) to the command line passed into Java using the -vmargs argument. Java Main then stores this value in eclipse.vmargs.

Upon launch, AccProbe displays three separate views: the Explorer View, the Accessibility Properties View, and the Event Monitor View.

Explorer View

The Explorer View presents a list of applications running on your Windows desktop at the time AccProbe was started. If a single window has two processes running in it (such as Lotus Notes or Lotus Symphony), it will load a separate window for each process. The node selected in the Explorer View drives the content of the Accessibility Properties View and the Event Monitor View.

• The Explorer View is not automatically updated as applications on the desktop are opened and closed. The applications currently running on the Desktop in the Explorer View may be updated by using the Refresh button on the Explorer View toolbar. The Refresh button is the standard circular arrow icon. Hovering with the mouse over the Refresh button causes a tooltip to appear reading Read desktop windows.
• By default, the Explorer View tree hierarchy is not updated as the focus changes. To display the current control in focus in the tree hierarchy during any tracking mode, the user must enable the Enable tree expansion while tracking button in the Explorer View toolbar. This action applies to all tracking modes, both application-by-application tracking and global tracking.

Notes on using the Explorer View

Upon opening, AccProbe populates the Explorer View by reading all the top level windows of the current Windows desktop.

• Each node in the tree hierarchy represents a top level window.
• The role and the value of the object's accessibleName property are provided for each object in the tree.
• Nodes in the tree can be expanded to drill down into the GUI control hierarchy manifested by the selected application.
• If a single window has two processes running in it (such as Lotus Notes or Lotus Symphony), Explorer View will list a separate window for each process.

Accessibility Properties View

The Accessibility Properties View displays the accessibility properties of the window or control selected in the Explorer View. The Accessibility Properties View displays a set of top-level nodes called property groups. The following user selectable property groups are :

• accservice: Displays all accessibility service properties derived from IAccessibleElement and IAccessibleElement2. The default properties displayed are: accessibleName, accessibleRole, accessibleState, accessibleValue and accessibleText.
• msaa: Displays all properties derived from the underlying MSAA accessibility architecture. The default properties displayed are: accname, accRole, accState and accValue.
• ia2: Displays all properties derived from the underlying IAccessible2 architecture. The default properties displayed are: role, states, IAccessibleValue and IAccessibleText.

Some properties will display on a single line - these are generally primitive types. Other properties, including arrays, contain nested properties. To see the nested properties and their values, expand the node in the Accessibility Properties View.

All the displayed property groups are expanded by default, initially displaying the default properties for that group. The user can choose the property groups/properties to be displayed by selecting the Choose properties for display icon in the Accessibility Properties View toolbar. The Properties Filter dialog is displayed in which property groups and specific properties may be selected/deselected for display. In addition, the user may choose to display only properties that have a valid non-null value by checking the Filter properties with "null" values checkbox. This option is turned off by default so that all selected properties are displayed.

Event Monitor View

The Event Monitor View displays event information which is dynamically captured while GUI applications are running.

• Events to monitor may be selected by the user from a select list of MSAA, IAccessible2, and system events.
• The event information can be presented in a user configured format to allow for specific kinds of events to be reported.
• Also, a subset of GUI controls may be selected in an application to be monitored.

There are several user selectable viewing options available in the main window toolbar 'Options' dropdown menu as discussed below.

• Always on Top - Choosing this option causes the AccProbe main window to remain in the foreground when another application on the desktop has the primary focus. This option is turned off by default so that the AccProbe main window moves to the background when it does not have the primary focus.
  
  
• Highlight Selected - Choosing this option causes AccProbe to highlight GUI controls in applications when they are selected in the Explorer View by drawing a red rectangular box around the selected item. This provides positive identification of the control being examined. This option is turned off by default. A few things to note about this feature:
  • The rectangle is drawn using the accessible location of the selected element. No rectangle will be drawn if the height and width of the element are zero. Also, if the accessible location extends beyond the screen size (which may happen when a window is maximized), all or part of the rectangle will be invisible depending on which coordinates are beyond the screen size.
  • If the selected element is not hidden, a solid rectangle appears and stays until either a different item is selected, the highlighting feature is turned off or AccProbe is terminated. The outline rectangle will also disappear if the window hosting the selected item is minimized or hidden by another window. If the selected object is hidden by another window, the rectangle blinks and disappears. If the selected object is partly hidden, the rectangle appears only on the visible portion of the window and then blinks on the hidden part.

There are several user selectable tracking options available in the main window toolbar 'Options' dropdown menu when the Tracking option is selected. From the sub-menu, one the following methods may be selected for automatically locating a control in the Explorer View to examine.

• Enable Global Tracking - Choosing this option causes AccProbe to report the properties of the current control in focus in all applications currently listed in the Explorer View. Thus, with global tracking enabled, the Properties View is automatically updated to show the properties of the current control in focus, regardless of the application in which the control resides. When Global Tracking is disabled, only controls in the selected window in the Explorer View are updated as the focus changes. This option is turned on by default. By default, the tree hierarchy in the Explorer View is not updated as the focus changes. (See Explorer View options for instructions to expand the tree hierarchy).



• Keyboard Focus tracking - Choosing this option causes AccProbe to track keyboard focus events in the selected top-level window. When global tracking is turned off, the Explorer View will expand and highlight the node which currently has keyboard focus. The Accessibility Properties View is synchronized, displaying information about the currently selected control. This option is turned on by default. A few things to note about this feature:
  • Keyboard tracking in non-global tracking mode is not dynamic. The Explorer View must be refreshed every time the application changes, such as for a new page in a browser;
  • Any object focused in the selected window will be selected in the Explorer View as long as the accessibleName property of the object is not null;
  • Caret position tracking may not be enabled if Keyboard focus tracking is enabled.
  
  
• Mouse Cursor tracking - Choosing this option causes AccProbe to track the mouse cursor events in the selected top-level window. When global tracking is turned off, the Explorer View will expand and highlight the node which currently is under the mouse cursor. The Accessibility Properties View is synchronized, displaying information about the currently selected control. This option is turned on by default. A few things to note about this feature:
  • Mouse Cursor tracking in non-global tracking mode is not dynamic. The Explorer View must be refreshed every time the application changes, such as for a new page in a browser;
  • To select an object, first select the desired top level window in the Explorer View. Move the mouse over the selected window and once the mouse stops, the object on which the mouse is stopped will be selected in the Explorer View;
  • The location of the selected object should not overlap with the location of the AccProbe window;
  • No selection will be made as long as the mouse continues to move or when the mouse moves over a different window than that selected.
  • Caret position tracking may not be enabled if Mouse cursor focus tracking is enabled.
  
  
• Caret Position tracking - Choosing this option causes AccProbe to follow the caret position within text or text field type controls in the selected top-level window. The Explorer View will expand and highlight the node which currently is associated with the caret. The Accessibility Properties View is also synchronized, displaying information about the currently selected text or control. This option is turned off by default. A few things to note about this feature:
  • Caret Position tracking in non-global tracking mode is not dynamic. The Explorer View must be refreshed every time the application changes, such as for a new page in a browser or a new line in a paragraph;
  • When the caret position changes such as during typing, the Explorer View updates with the object containing the caret and the Properties View updates to select and expand the IAccessibleText field in "ia2" property group(for IA2 objects)
  • Caret position tracking may only be enabled if Keyboard focus tracking and Mouse cursor tracking are disabled.
  
  

All AccProbe operations may be suspended by pressing the Suspend all actions button in the main AccProbe window toolbar. This action stops all tracking, event monitoring and event processing. In addition, the Highlight Selected and Always on top options are disabled. Also the button text changes to Resume all actions. Pressing this button again causes Accprobe to return to its previous state.

In the suspended mode, the user will still be able to make changes to the Accprobe options/preferences with the exception of the Always on top option. This includes stopping event monitoring, modifying the event filters, and changing tracking options.

In the Event Monitor View, AccProbe displays accessibility event information which is dynamically captured while GUI applications are running on the desktop. This information can be tailored and filtered in a number of ways to allow selection of specific kinds of events and the information to be reported about the event. A subset of the GUI components in an application may be selected for monitoring. The Event Monitor by default captures events associated with all the processes. The user can also turn off Monitor all processes option to captures events specific to the top level window containing the component that is currently selected in the Explorer View. For example, if a menu bar for an application is selected in the Explorer View, the Event Monitor will capture events related to the entire top level window which contains the menu bar.

Choosing Events to Watch and Selecting Event Information to Display

The event monitor view pull-down menu (a small downward-pointing triangle icon) in the Event Monitor toolbar offers a number of functions for selecting events and displaying event data.

• Monitor all processes - Choosing this option allows monitoring of events for all processes without having to select a particular window in the Explorer View. This option is turned on by default. If the user wants to monitor the events for a specific window, this option should to be turned off and the particular window should be selected in the Explorer View.



• Get in-context events and Get out-of-context events - Choosing either the 'in context' or the 'out of context' method determines how events are detected. Note the same events are reported regardless of which technique is selected. However, there are some performance advantages when using the 'in context' method as described in this Microsoft MSDN article.



• Save events to file... - Choosing this option allows event data to be saved to a log file as selected from a Save As file dialog. Once logging is enabled, all events which appear in the Event Monitor View will be logged to the file. The file is continuously updated with event data until logging is disabled. The log file is a text file which may be viewed or edited with a standard word processor.



• Choose Events to Watch... - Choosing this option allows the selection of events to watch for the currently active node in the Explorer View. The events are selected in the "Choose Events to Watch" dialog window by checking appropriate events from a list of events. Note the list of events depends on the type of control (MSAA or IAccessible2).



• Choose columns to display... - Choosing this option allows the selection of event data to display in the Event Monitor View. The data to display is selected in the "Choose Table Columns" dialog by checking appropriate data from a list of data types. All the event data such as hwnd, windowclass etc are available in Event Data column as a single property. For Caret events (IA2_TEXT events), Event Data also displays data related to caret events.

In addition to the above functions, the event display can be cleared by pressing the Clear the events list button, a rectangular icon with an X on top.

Controlling Event Capture and Display

The Event Monitor View toolbar contains buttons which control the capture and display of real-time event data as discussed below. Initially event capture is turned off and the Start capture of events and Pause capture of Events buttons are active.

• Start capture of events - starts both the capture and display of events.



• Stop capture of events - stops both the capture and display of events.



• Pause display - pauses the display of events but does not stop the capture of events. Events captured while the display is paused may be displayed later using the Resume capture of events button. Pausing the display is useful when analyzing the event data, while continuing to capture events. Note the tooltip for this button reads Pause capture of events.



• Resume display - resumes the display of events, including events captured following a previous pausing of event capture. Note the tooltip for this button reads Resume capture of events.

The Accessibility Properties View can show only the properties of a control for which there are property "getter" functions. The non-getter methods which require parameters will have their name displayed as the property and a dummy string such as "<Double Click to enter parameters..>" as their value.

To invoke a non-getter method, double-click on the property in the Accessibility Properties View list. The Invoke Method dialog appears and presents a drop-down list of the methods defined by the selected object class. After selecting the method of interest, the input parameters entry fields (if any) are displayed. After entering any values, the method is invoked using the 'Invoke method' button. The results of the method invocation are displayed at the bottom of the dialog.

The following features are new with AccProbe release 1.0.0.

1. Implementation of new ia2 idl (version 1.1) which includes the new interfaces IAccessibleTableCell and IAccessibleTable2. The IAccessible2 interface will now display these two interfaces if present In order to test these two new interfaces, users will need to use the latest Mozilla Minefield browser (version 3.7a1pre).
2. Added a "howFound" property to accessible elements , which lets the user know about the event information and hwnd information for that accessibleAdded a "howFound" property to accessible elements which lets the user know how the event information and "hwnd" information for that accessible was determined.
3. All the event data such as hwnd, child id, object id, windowclass etc are available in Event Data column as a single property.

New Features in AccProbe release 1.2.0

The following features are new with AccProbe release 1.2.0.

1. New version 1.2.0 in accordance with the new ia2 idl
2. Changed BSD license to add copyright for linux foundation
3. Miscillaneous bug fixes

New Features in AccProbe release 1.2.1

1. Bug fixes for 492, 509 , 518, 523, 527, 528, 529, 531 and 534
2. Added support for missing IAccessible properties such as put_accValue

New Features in AccProbe release 1.2.1.1

The following features are new with AccProbe release 1.2.1.1

1. New build in accordance with the new ia2 idl version 1.2.1

There following are known problems when using AccProbe.

1. When global tracking is disabled, rapidly selecting URL links on a Web page when using keyboard and mouse tracking modes may cause AccProbe to crash.
2. Since app-by-app tracking is not dynamic, everytime the application changes (such as when a new page is loaded in a browser), the explorer view has to be refreshed.
3. During App-by-app tracking, it often takes a long time for the focused object to be selected in the Explorer view. In such cases,it is advisable for the user to wait until the object is selected in Explorer view.
4. Accprobe currently cannot display AccessibleChildren property for an Accessible Object if the child count is more than 1000. The child count is still reported in the AccessibleChildCount property. For Example, a symphony spreadsheet has more than 1000 children and hence AccessibleChildren will not be displayed.
5. Accprobe will not track the keyboard or mouse movements during task switching process (when using Alt-tab) to make global tracking more accessible.
6. Accprobe with Java 7 is causing SwingSet2 applications to crash. The crash happens when an out-of-context Focus event is fired from the taskbar part on the top of Swingset2 frame.
7. Accprobe does not set SPI_GETSCREENREADER flag and hence does not display IA2 properties for Symphony1.3 which is dependent on this flag. Until this is fixed in Symphony, a workaround for Accprobe to display Ia2 data in Symphony1.3 is to have a screenreader such as Jaws/Inspect32/UnoInspect32 open.