Java Accessibility ガイド > ユーザー補助テクノロジ開発者向け Java Access Bridge プログラマーズガイド > Java Access Bridge API
Java Access Bridge API を使用すると、Java アプリケーションで機能する、Microsoft Windows オペレーティングシステム向けユーザー補助テクノロジアプリケーションを開発できます。これには、Java アプリケーションの GUI 要素についての情報 (Java Access Bridge 経由でユーザー補助テクノロジアプリケーションに転送される) を表示および操作できるネイティブメソッドが含まれています。
次の項目について説明します。
Java Access Bridge API は、AccessBridgeCalls.h
、AccessBridgePackages.h
、および AccessBridgeCallbacks.h
の 3 つのファイルにあります。これらのファイルは、Java Access Bridge API 呼び出し、API データ構造、および API コールバックにそれぞれ対応しています。
Java Access Bridge 2.0.2 には、64 ビットシステムをサポートするために新しい API セットが含まれます。ただし、API の変更は API 呼び出しに渡されるパラメータだけで、API. の名前は変更されていません。
ユーザー補助テクノロジのアプリケーションは、ソースで提供されている新しいヘッダーファイルで再コンパイルする必要があります。
jobject
型のオブジェクトは jlong
として渡されるようになりました。typedef JOBJECT64
は、ACCESSBRIDGE_ARCH_LEGACY
が定義されているかどうかに応じて jobject
または jlong
のいずれかになります。AccessBridgePackages.h
ヘッダーファイルを参照してください。
使用例については、JavaFerret.cpp
の例を参照してください。
void HandlePropertyChildChange( long vmID, PropertyChangeEvent event, AccessibleContext ac, JOBJECT64 oldChild, JOBJECT64 newChild); void HandlePropertyActiveDescendentChange( long vmID, PropertyChangeEvent event, AccessibleContext ac, JOBJECT64 oldActiveDescendent, JOBJECT64 newActiveDescendent);
Java Access Bridge API 呼び出しは AccessBridgeCalls.h
に含まれていて、これらを使用するには使用しているアプリケーションと WindowsAccessBridge.dll
との間のインタフェースとして機能するファイル AccessBridgeCalls.c
もコンパイルする必要があります。
これらの 2 つの関数は Java Access Bridge を起動してシャットダウンします。
BOOL
initializeAccessBridge
();
Java Access Bridge を起動します。この関数を呼び出すまでは Java Access Bridge API のいずれの部分も使用できません。
BOOL
shutdownAccessBridge
();
Java Access Bridge をシャットダウンします。アプリケーションが Java Access Bridge の使用を終了するときは、(アプリケーションが存在する前に) この関数を呼び出して Java Access Bridge が正しくメモリークリーンアップを実行できるようにすることが重要です。
注: 関数 shutdownAccessBridge
を呼び出すことは、JVM によって保持されているデータ構造を解放することの代わりにはならないため、関数 ReleaseJavaObject
を呼び出すことでこれを行なってください。
通常はこれらの関数を呼び出してから、その他の Java Access Bridge API 関数を呼び出します。
BOOL
IsJavaWindow
(HWND window);
指定されたウィンドウが Java Accessibility API を実装しているかどうかを確認します。
BOOL
GetAccessibleContextFromHWND
(HWND target, long *vmID, AccessibleContext *ac);
指定されたウィンドウの AccessibleContext
および vmID
値を取得します。多くの Java Access Bridge 関数には AccessibleContext
および vmID
値が必要です。
これらは、イベントタイプを処理する関数への関数ポインタを取ります。これらのタイプのイベントを受け取る必要がなくなった場合、関数を再度呼び出して NULL
値を渡します。ファイル AccessBridgeCallbacks.h
内で、これらの関数に渡す必要がある関数ポインタのプロトタイプを探します。これらのプロトタイプの詳細は、セクション「API コールバック」を参照してください。
void
SetFocusGained
(AccessBridge_FocusGainedFP fp);
void
SetFocusLost
(AccessBridge_FocusLostFP fp);
使用可能な機能を判別するために、GetVersionInfo
呼び出しからバージョン情報を取得できます。
void
ReleaseJavaObject
(long vmID, Java_Object object);
Java オブジェクト object
によって使用されるメモリーを解放します (object
は Java Access Bridge によって返されるオブジェクト)。Java Access Bridge は JVM 内で返されるすべての Java オブジェクトへの参照を自動的に保持するため、それらはガベージコレクトされません。メモリーリークを防ぐには、Java Access Bridge によって返されたすべての Java オブジェクトの使用が終了したら、それらに対して ReleaseJavaObject
を呼び出す必要があります。これの実行例については、JavaFerret.c
を参照してください。
BOOL
GetVersionInfo
(long vmID, AccessBridgeVersionInfo *info);
アプリケーションが使用している Java Access Bridge インスタンスのインスタンスバージョン情報を取得します。この情報を使用して、Java Access Bridge のバージョンの利用できる機能を判別できます。
注: JVM のバージョンを判別するには有効な vmID
を渡す必要があります。そうでない場合は返されるものはすべて、アプリケーションが接続されている WindowsAccessBridge.DLL
ファイルのバージョンです。
これらの関数は、Java Access Bridge により公開される Java Accessibility API のコア部分を提供します。
関数 GetAccessibleContextAt
および GetAccessibleContextWithFocus
は、AccessibleContext
オブジェクト (Accessible
オブジェクトへのマジッククッキー (実際には Java Object
参照) と JVM クッキー) を取得します。これらの 2 つのクッキーを使用して、Java Access Bridge 経由でオブジェクトを参照します。ほとんどの Java Access Bridge API 関数には、これら 2 つのパラメータを渡す必要があります。
注: AccessibleContext
オブジェクトは 64 ビットプロセス間通信 (ファイル名に -32
および -64
が付いた DLL および JAR ファイルを使用) での 64 ビット参照、AccessibleContext
オブジェクトは 32 ビットプロセス間通信 (ファイル名に -32
および -64
が付いていない DLL および JAR ファイルを使用) での 32 ビット参照です。したがって、64 ビットプロセス間通信を使用している場合は、ユーザー補助テクノロジアプリケーションを再コンパイルする必要があります。
関数 GetAccessibleContextInfo
は、JVM に属する AccessibleContext
オブジェクトの詳細情報を返します。パフォーマンスを向上させるために、Java Accessibility API のさまざまな異なるメソッドが集められて Java Access Bridge API のいくつかのルーチンにまとめられ、struct
値で返されます。これらの struct
値はファイル AccessBridgePackages.h
で定義されており、セクション「API コールバック」で説明されています。
関数 GetAccessibleChildFromContext
および GetAccessibleParentFromContext
を使用すると、GUI コンポーネント階層をウォークして、特定の GUI オブジェクトの n 番目の子 (または親) を取得できます。
BOOL
GetAccessibleContextAt
(long vmID, AccessibleContext acParent, jint x, jint y, AccessibleContext *ac)
マウスポインタの下にあるウィンドウまたはオブジェクトの AccessibleContext
オブジェクトを取得します。
BOOL
GetAccessibleContextWithFocus
(HWND window, long *vmID, AccessibleContext *ac);
フォーカスを持つウィンドウまたはオブジェクトの AccessibleContext
オブジェクトを取得します。
BOOL
GetAccessibleContextInfo
(long vmID, AccessibleContext ac, AccessibleContextInfo *info);
AccessibleContext
オブジェクト ac
の AccessibleContextInfo
オブジェクトを取得します。
AccessibleContext
GetAccessibleChildFromContext
(long vmID, AccessibleContext ac, jint index);
オブジェクト ac
の n 番目の子を表す AccessibleContext
オブジェクトを返します (n は値 index
で指定される)。
AccessibleContext
GetAccessibleParentFromContext
(long vmID, AccessibleContext ac);
オブジェクト ac
の親を表す AccessibleContext
オブジェクトを返します。
これらの関数は、Java Accessibility API によって提供される AccessibleText
情報を取得します (効率化のために 7 つのチャンクに分割されます)。AccessibleContextInfo
データ構造内の accessibleText
フラグが TRUE
に設定されている場合、AccessibleContext
内に AccessibleText
情報が含まれます。これらの関数で使用される struct
値はファイル AccessBridgePackages.h
で定義されており、セクション「API コールバック」で説明されています。
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);
これらの関数は、Java Accessibility API によって提供される AccessibleValue
情報を取得します。AccessibleContextInfo
データ構造内の accessibleValue
フラグが TRUE
に設定されている場合、AccessibleContext
オブジェクト内に AccessibleValue
情報が含まれます。返される値は文字列 (char *value
) です (値が、Java 言語構造体 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);
これらの関数は、Java Accessibility API によって提供される AccessibleSelection
情報を取得および操作します。AccessibleContextInfo
データ構造内の accessibleSelection
フラグが TRUE
に設定されている場合、AccessibleContext
内に AccessibleSelection
情報が含まれます。AccessibleSelection
サポートは、照会時とは異なり、選択に対して項目を追加および削除することでユーザーインタフェースを操作できる最初の場所です。一部の関数は子座標にあるインデックスを使用し、その他は選択座標を使用します。たとえば、子インデックスを渡すことにより、選択に対する追加または削除を行います (たとえば、4 番目の子を選択に追加するなど)。一方、選択された子の列挙は選択座標内で行われます (たとえば、選択された最初のオブジェクトの AccessibleContext
を取得するなど)。
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);
Java Access Bridge API データ構造はファイル AccessBridgePackages.h
に含まれています。このファイルには必要がない (および無視できる) データ構造があります。これらは 2 つの Java Access Bridge DLL のプロセス間通信メカニズムの一部として使用されます。重要なデータ構造は次のとおりです。
#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]; };
Java Access Bridge API コールバックはファイル AccessBridgeCallbacks.h
に含まれています。イベント処理関数はこれらのプロトタイプに一致する必要があります。
注: すべての Java Access Bridge イベントハンドラは、Java Ferret の例で定義および使用されています。
これらのイベントハンドラの使用が終了したら、イベントハンドラにより返されたすべての jobject
に対して関数 ReleaseJavaObject
を呼び出し、JVM のメモリーリークを防ぐ必要があります。
ここで、JOBJECT64
は 64 ビットシステムでは jlong
、レガシーバージョンの Java Access Bridge では jobject
として定義されています。定義については、AccessBridgePackages.h
ヘッダーファイルのセクション ACCESSBRIDGE_ARCH_LEGACY
を参照してください。
レガシー API を使用する場合は、ACCESSBRIDGE_ARCH_LEGACY
を定義してください。AccessBridgePackages.h
ヘッダーファイルを参照してください。
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, jobject event, JOBJECT64 source, JOBJECT64 oldActiveDescendent, JOBJECT64 newActiveDescendent);