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:
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.
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);
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.
These two functions start and shut down Java Access Bridge.
BOOL initializeAccessBridge();
Starts Java Access Bridge. You cannot use any part of the Java Access Bridge API until you call this function.
BOOL shutdownAccessBridge();
Shuts down Java Access Bridge. It is important to call this function when your application is finished using Java Access Bridge (before your application exists) so that Java Access Bridge can properly perform memory cleanup.
Note: Calling the function shutdownAccessBridge is not a substitute for releasing any data structures that are maintained by the JVM; do this by calling the function ReleaseJavaObject.
You typically call these functions before calling any other Java Access Bridge API function:
BOOL IsJavaWindow(HWND window);
Checks to see if the given window implements the Java Accessibility API.
BOOL GetAccessibleContextFromHWND(HWND target, long *vmID, AccessibleContext *ac);
Gets the AccessibleContext and vmID values for the given window. Many Java Access Bridge functions require the AccessibleContext and vmID values.
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.
void SetFocusGained(AccessBridge_FocusGainedFP fp);
void SetFocusLost(AccessBridge_FocusLostFP fp);
In order to determine the functionality available, you can get version information from the GetVersionInfo call.
void ReleaseJavaObject(long vmID, Java_Object object);
Release the memory used by the Java object object, where object is an object returned to you by Java Access Bridge. Java Access Bridge automatically maintains a reference to all Java objects that it returns to you in the JVM so they are not garbage collected. To prevent memory leaks, you must call ReleaseJavaObject on all Java objects returned to you by Java Access Bridge once you are finished with them. See JavaFerret.c for an illustration of how to do this.
BOOL GetVersionInfo(long vmID, AccessBridgeVersionInfo *info);
Gets the version information of the instance of Java Access Bridge instance your application is using. You can use this information to determine the available functionality of your version of Java Access Bridge.
Note:
In order to determine the version of the JVM, you need to pass in a valid vmID; otherwise all that is returned is the version of the WindowsAccessBridge.DLL file to which your application is connected.
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.
BOOL GetAccessibleContextAt(long vmID, AccessibleContext acParent, jint x, jint y, AccessibleContext *ac)
Retrieves an AccessibleContext object of the window or object that is under the mouse pointer.
BOOL GetAccessibleContextWithFocus(HWND window, long *vmID, AccessibleContext *ac);
Retrieves an AccessibleContext object of the window or object that has the focus.
BOOL GetAccessibleContextInfo(long vmID, AccessibleContext ac, AccessibleContextInfo *info);
Retrieves an AccessibleContextInfo object of the AccessibleContext object ac.
AccessibleContext GetAccessibleChildFromContext(long vmID, AccessibleContext ac, jint index);
Returns an AccessibleContext object that represents the nth child of the object ac, where n is specified by the value index.
AccessibleContext GetAccessibleParentFromContext(long vmID, AccessibleContext ac);
Returns an AccessibleContext object that represents the parent of object ac.
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".
BOOL GetAccessibleTextInfo(long vmID, AccessibleText at, AccessibleTextInfo *textInfo, jint x, jint y);
BOOL GetAccessibleTextItems(long vmID, AccessibleText at, AccessibleTextItemsInfo *textItems, jint index);
BOOL GetAccessibleTextSelectionInfo(long vmID, AccessibleText at, AccessibleTextSelectionInfo *textSelection);
char *GetAccessibleTextAttributes(long vmID, AccessibleText at, jint index, AccessibleTextAttributesInfo *attributes);
BOOL GetAccessibleTextRect(long vmID, AccessibleText at, AccessibleTextRectInfo *rectInfo, jint index);
BOOL GetAccessibleTextRange(long vmID, AccessibleText at, jint start, jint end, wchar_t *text, short len);
BOOL GetAccessibleTextLineBounds(long vmID, AccessibleText at, jint index, jint *startIndex, jint *endIndex);
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.
BOOL GetCurrentAccessibleValueFromContext(long vmID, AccessibleValue av, wchar_t *value, short len);
BOOL GetMaximumAccessibleValueFromContext(long vmID, AccessibleValue av, wchar_ *value, short len);
BOOL GetMinimumAccessibleValueFromContext(long vmID, AccessibleValue av, wchar_ *value, short len);
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).
void AddAccessibleSelectionFromContext(long vmID, AccessibleSelection as, int i);
void ClearAccessibleSelectionFromContext(long vmID, AccessibleSelection as);
jobject GetAccessibleSelectionFromContext(long vmID, AccessibleSelection as, int i);
int GetAccessibleSelectionCountFromContext(long vmID, AccessibleSelection as);
BOOL IsAccessibleChildSelectedFromContext(long vmID, AccessibleSelection as, int i);
void RemoveAccessibleSelectionFromContext(long vmID, AccessibleSelection as, int i);
void SelectAllAccessibleSelectionFromContext(long vmID, AccessibleSelection as);
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];
};
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.
typedef void (*AccessBridge_FocusGainedFP) (long vmID, JOBJECT64 event, JOBJECT64 source);
typedef void (*AccessBridge_FocusLostFP) (long vmID, JOBJECT64 event, JOBJECT64 source);
typedef void (*AccessBridge_CaretUpdateFP) (long vmID, JOBJECT64 event, JOBJECT64 source);
typedef void (*AccessBridge_MouseClickedFP) (long vmID, JOBJECT64 event, JOBJECT64 source);
typedef void (*AccessBridge_MouseEnteredFP) (long vmID, JOBJECT64 event, JOBJECT64 source);
typedef void (*AccessBridge_MouseExitedFP) (long vmID, JOBJECT64 event, JOBJECT64 source);
typedef void (*AccessBridge_MousePressedFP) (long vmID, JOBJECT64 event, JOBJECT64 source);
typedef void (*AccessBridge_MouseReleasedFP) (long vmID, JOBJECT64 event, JOBJECT64 source);
typedef void (*AccessBridge_MenuCanceledFP) (long vmID, JOBJECT64 event, JOBJECT64 source);
typedef void (*AccessBridge_MenuDeselectedFP) (long vmID, JOBJECT64 event, JOBJECT64 source);
typedef void (*AccessBridge_MenuSelectedFP) (long vmID, JOBJECT64 event, JOBJECT64 source);
typedef void (*AccessBridge_PopupMenuCanceledFP) (long vmID JOBJECT64 event, JOBJECT64 source);
typedef void (*AccessBridge_PopupMenuWillBecomeInvisibleFP) (long vmID, JOBJECT64 event, JOBJECT64 source);
typedef void (*AccessBridge_PopupMenuWillBecomeVisibleFP) (long vmID, JOBJECT64 event, JOBJECT64 source);
typedef void (*AccessBridge_PropertyNameChangeFP) (long vmID, JOBJECT64 event, JOBJECT64 source, wchar_t *oldName, wchar_t *newName);
typedef void (*AccessBridge_PropertyDescriptionChangeFP) (long vmID, JOBJECT64 event, JOBJECT64 source, wchar_t *oldDescription, wchar_t *newDescription);
typedef void (*AccessBridge_PropertyStateChangeFP) (long vmID, JOBJECT64 event, JOBJECT64 source, wchar_t *oldState, wchar_t *newState);
typedef void (*AccessBridge_PropertyValueChangeFP) (long vmID, JOBJECT64 event, JOBJECT64 source, wchar_t *oldValue, wchar_t *newValue);
typedef void (*AccessBridge_PropertySelectionChangeFP) (long vmID, JOBJECT64 event, JOBJECT64 source);
typedef void (*AccessBridge_PropertyTextChangeFP) (long vmID, JOBJECT64 event, JOBJECT64 source);
typedef void (*AccessBridge_PropertyCaretChangeFP) (long vmID, JOBJECT64 event, JOBJECT64 source, int oldPosition, int newPosition);
typedef void (*AccessBridge_PropertyVisibleDataChangeFP) (long vmID, JOBJECT64 event, JOBJECT64 source);
typedef void (*AccessBridge_PropertyChildChangeFP) (long vmID, JOBJECT64 event, JOBJECT64 source, JOBJECT64 oldChild, JOBJECT64 newChild);
typedef void (*AccessBridge_PropertyActiveDescendentChangeFP) (long vmID, JOBJECT64 event, JOBJECT64 source, JOBJECT64 oldActiveDescendent, JOBJECT64 newActiveDescendent);
