Java Access Bridge API

Java Accessibility Guide > Java Access Bridge Programmer's Guide for Assistive Technology Developers > Java Access Bridge API

The Java Access Bridge API enables you to develop assistive technology applications for the Microsoft Windows operating system that work with Java applications. It contains native methods that enable you to view and manipulate information about GUI elements in a Java application, which is forwarded to your assistive technology application through Java Access Bridge.

The following topics are covered:

API Files

The Java Access Bridge API can be found in three files: AccessBridgeCalls.h, AccessBridgePackages.h, and AccessBridgeCallbacks.h. These files correspond to the Java Access Bridge API calls, the API data structures, and the API callbacks, respectively.

API Changes from 2.0.1

Java Access Bridge 2.0.2 includes a new set of APIs in order to support 64-bit systems. However, the changes to the API are specific to parameters passed in API calls; there are no name changes in the API.

Assistive Technologies must recompile their applications with the new header files provided in the source.

Objects of type jobject are now passed as jlong. The typedef JOBJECT64 is either a jobject or jlong depending on whether ACCESSBRIDGE_ARCH_LEGACY is defined. See the AccessBridgePackages.h header file.

For usage examples, see the JavaFerret.cpp example:

void HandlePropertyChildChange(
  long vmID, PropertyChangeEvent event,
  AccessibleContext ac, JOBJECT64 oldChild, JOBJECT64 newChild);
 
void HandlePropertyActiveDescendentChange(
  long vmID, PropertyChangeEvent event, AccessibleContext ac,
  JOBJECT64 oldActiveDescendent, JOBJECT64 newActiveDescendent);

API Calls

The Java Access Bridge API calls are contained in AccessBridgeCalls.h and to use them, you must also compile the file AccessBridgeCalls.c, which acts as the interface between your application and WindowsAccessBridge.dll.

Initialization/Shutdown Functions

These two functions start and shut down Java Access Bridge.

Gateway Functions

You typically call these functions before calling any other Java Access Bridge API function:

Event Handling Functions

These take a function pointer to the function that will handle the event type. When you no longer are interested in receiving those types of events, call the function again, passing in the NULL value. Find prototypes for the function pointers you need pass into these functions in the file AccessBridgeCallbacks.h. See the section "API Callbacks" for more information about these prototypes.

General Functions

In order to determine the functionality available, you can get version information from the GetVersionInfo call.

Accessible Context Functions

These functions provide the core of the Java Accessibility API that is exposed by Java Access Bridge.

The functions GetAccessibleContextAt and GetAccessibleContextWithFocus retrieve an AccessibleContext object, which is a magic cookie (really a Java Object reference) to an Accessible object and a JVM cookie. You use these two cookies to reference objects through Java Access Bridge. Most Java Access Bridge API functions require that you pass in these two parameters.

Note: AccessibleContext objects are 64-bit references under 64-bit inter-process communication (which uses the DLL and JAR files with -32 and -64 in their file names), while AccessibleContext objects are 32-bit references under 32-bit inter-process communication (which uses the DLL and JAR files without -32 and -64 in their file names). Consequently, you need to recompile your Assistive Technology applications if you are using 64-bit inter-process communication.

The function GetAccessibleContextInfo returns detailed information about an AccessibleContext object belonging to the JVM. In order to improve performance, the various distinct methods in the Java Accessibility API are collected together into a few routines in the Java Access Bridge API and returned in struct values. These struct values are defined in the file AccessBridgePackages.h and are described in the section "API Callbacks".

The functions GetAccessibleChildFromContext and GetAccessibleParentFromContext enable you to walk the GUI component hierarchy, retrieving the nth child, or the parent, of a particular GUI object.

Accessible Text Functions

These functions get AccessibleText information provided by the Java Accessibility API, broken down into seven chunks for efficiency. An AccessibleContext has AccessibleText information contained within it if the flag accessibleText in the AccessibleContextInfo data structure is set to TRUE. The struct values used in these functions are defined in the file AccessBridgePackages.h and are described in the section "API Callbacks".

Accessible Value Functions

These functions get AccessibleValue information provided by the Java Accessibility API. An AccessibleContext object has AccessibleValue information contained within it if the flag accessibleValue in the AccessibleContextInfo data structure is set to TRUE. The values returned are strings (char *value) because there is no way to tell in advance if the value is an integer, a floating point value, or some other object that subclasses the Java language construct java.lang.Number.

Accessible Selection Functions

These functions get and manipulate AccessibleSelection information provided by the Java Accessibility API. An AccessibleContext has AccessibleSelection information contained within it if the flag accessibleSelection in the AccessibleContextInfo data structure is set to TRUE. The AccessibleSelection support is the first place where the user interface can be manipulated, as opposed to being queries, through adding and removing items from a selection. Some of the functions use an index that is in child coordinates, while other use selection coordinates. For example, add to remove from a selection by passing child indicies (for example, add the fourth child to the selection). On the other hand, enumerating the selected children is done in selection coordinates (for example, get the AccessibleContext of the first object selected).

API Data Structures

The Java Access Bridge API data structures are contained in the file AccessBridgePackages.h. There are data structures in this file that you do not need (and can ignore); they are used as part of the inter-process communication mechanism of the two Java Access Bridge DLLs. The data structures of importance are as follows:

#define MAX_STRING_SIZE     1024
#define SHORT_STRING_SIZE    256
 
struct AccessBridgeVersionInfo {
 wchar_t VMversion[SHORT_STRING_SIZE];              // version of the Java VM
 wchar_t bridgeJavaClassVersion[SHORT_STRING_SIZE]; // version of the
                                                    //   AccessBridge.class
 wchar_t bridgeJavaDLLVersion[SHORT_STRING_SIZE];   // version of 
                                                    //   JavaAccessBridge.dll
 wchar_t bridgeWinDLLVersion[SHORT_STRING_SIZE];    // version of 
                                                    //   WindowsAccessBridge.dll
};
 
struct AccessibleContextInfo {
 wchar_ name[MAX_STRING_SIZE];        // the AccessibleName of the object
 wchar_ description[MAX_STRING_SIZE]; // the AccessibleDescription of the object
 wchar_ role[SHORT_STRING_SIZE];      // localized AccesibleRole string
 wchar_ states[SHORT_STRING_SIZE];    // localized AccesibleStateSet string
                                      //   (comma separated)
 jint indexInParent                   // index of object in parent
 jint childrenCount                   // # of children, if any
 jint x;                              // screen x-axis co-ordinate in pixels
 jint y;                              // screen y-axis co-ordinate in pixels
 jint width;                          // pixel width of object
 jint height;                         // pixel height of object
 BOOL accessibleComponent;            // flags for various additional
 BOOL accessibleAction;               // Java Accessibility interfaces
 BOOL accessibleSelection;            // FALSE if this object doesn't
 BOOL accessibleText;                 // implement the additional interface
 BOOL accessibleInterfaces;           // new bitfield containing additional
                                      //   interface flags
};
 
struct AccessibleTextInfo {
 jint charCount;       // # of characters in this text object
 jint caretIndex;      // index of caret
 jint indexAtPoint;    // index at the passsed in point
};

struct AccessibleTextItemsInfo {
 wchar_t letter;
 wchar_t word[SHORT_STRING_SIZE];
 wchar_t sentence[MAX_STRING_SIZE];
};
 
struct AccessibleTextSelectionInfo {
 jint selectionStartIndex;
 jint selectionEndIndex;
 wchar_t selectedText[MAX_STRING_SIZE];
};
 
struct AccessibleTextRectInfo {
 jint x;          // bounding recttangle of char at index, x-axis co-ordinate
 jint y;          // y-axis co-ordinate
 jint width;      // bounding rectangle width
 jint height;     // bounding rectangle height
};
 
struct AccessibleTextAttributesInfo {
 BOOL bold;
 BOOL italic;
 BOOL underline;
 BOOL strikethrough;
 BOOL superscript;
 BOOL subscript;
 wchar_t backgroundColor[SHORT_STRING_SIZE];
 wchar_t foregroundColor[SHORT_STRING_SIZE];
 wchar_t fontFamily[SHORT_STRING_SIZE];
 jint fontSize;
 jint alignment;
 jint bidiLevel;
 jfloat firstLineIndent;
 jfloat leftIndent;
 jfloat rightIndent;
 jfloat lineSpacing;
 jfloat spaceAbove;
 jfloat spaceBelow;
 wchar_t fullAttributesString[MAX_STRING_SIZE];
};

API Callbacks

The Java Access Bridge API callbacks are contained in the file AccessBridgeCallbacks.h. Your event handling functions must match these prototypes.

Note: All of the Java Access Bridge event handlers are defined and used in the Java Ferret example.

You must call the function ReleaseJavaObject on every JOBJECT64 returned through these event handlers once you are finished with them to prevent memory leaks in the JVM.

Here, JOBJECT64 is defined as jlong on 64-bit systems and jobject on legacy versions of Java Access Bridge. For definitions, see the section ACCESSBRIDGE_ARCH_LEGACY in the AccessBridgePackages.h header file.

If using legacy APIs, define ACCESSBRIDGE_ARCH_LEGACY. See the AccessBridgePackages.h header file.

Copyright © 1993, 2014, Oracle and/or its affiliates. All rights reserved.