モジュール java.desktop

パッケージ java.awt

クラスRobot

java.lang.Object

java.awt.Robot

public class Robot extends Object

このクラスを用いると、テストの自動化、自動実行のデモ、およびマウスやキーボード制御が必要なアプリケーションのために、ネイティブなシステム入力イベントを生成することができます。 Robotの主な目的は、Javaプラットフォーム実装テストを自動化することです。

クラスを使用して、AWTイベント・キューへのイベント転送またはプラットフォームのネイティブな入力キューで生成されるAWTコンポーネントとは異なる、入力イベントを生成します。 たとえばRobot.mouseMoveでは、マウスの移動イベントを生成するだけではなく、マウスのカーソルを実際に動かします。

一部のプラットフォームでは、低レベル入力制御にアクセスするための、特別な特権または拡張機能が必要です。 現在のプラットフォーム構成では入力制御を行えない場合、Robotオブジェクトを構築しようとするとAWTExceptionがスローされます。 たとえば、XサーバーでXTEST 2.2標準拡張機能がサポートされていない、または使用できない場合、X Windowシステムは例外をスローします。

セルフ・テスト以外の目的でRobotを使用するアプリケーションでは、これらの例外条件を正常に処理する必要があります。

プラットフォームおよびデスクトップ環境では、Robotクラス内のすべての機能を実装するために必要なアクセスに対して制限または制限が課される場合があります。 たとえば:

• 実行中のアプリケーションによって所有されていないデスクトップまたはデスクトップ上のウィンドウのコンテンツへのアクセスを防止します。
• ウィンドウ装飾を非所有コンテンツとして扱います。
• ウィンドウを操作する特定のリクエストを無視または制限します。
• ロボットがキーボードやマウスなどに関連する (synthesized)イベントを生成する特定のリクエストを無視または制限します。
• ウィンドウ・コンテンツへのアクセス、アプリケーション所有のコンテンツ、またはイベントの合成を限定的に行うには、特定のアクセス権またはグローバル・アクセス権が必要です。

Robot API仕様では、これらに対する許可が完全な操作に付与されている必要があります。 付与されていない場合、ここで説明するようにAPIは機能低下します。 関連する特定のAPIメソッドでは、より具体的な制限および要件を文書化できます。 デスクトップ環境のポリシーに応じて、前述の承認は次のようになります:

• 毎回必須
• または、アプリケーションの存続期間中、
• または、複数のユーザー・デスクトップ・セッションにわたって永続的
• ファイングレイン権限
• 特定のバイナリ・アプリケーション、またはバイナリ・アプリケーションのクラスに関連付けられます。

このような承認を対話形式で付与する必要がある場合、承認されるまでアプリケーションの通常の操作が妨げられることがあります。また、承認が拒否されたり、不可能であったり、永続的にすることができない場合は、このクラスの機能が低下し、アプリケーションに依存するアプリケーションの操作の一部が変わります。

導入されたバージョン:

1.3

コンストラクタのサマリー

コンストラクタ

コンストラクタ	説明
Robot()	プライマリ・スクリーンの座標システムでRobotオブジェクトを構築します。
Robot(GraphicsDevice screen)	指定されたスクリーン・デバイスにRobotを作成します。

メソッドのサマリー

修飾子と型	メソッド	説明
MultiResolutionImage	createMultiResolutionScreenCapture(Rectangle screenRect)	スクリーンから読み取るピクセルを含むイメージを作成します。
BufferedImage	createScreenCapture(Rectangle screenRect)	スクリーンから読み取るピクセルを含むイメージを作成します。
void	delay(int ms)	指定時間スリープします。
int	getAutoDelay()	イベント生成後、このRobotがスリープする時間をミリ秒で返します。
Color	getPixelColor(int x, int y)	指定されたスクリーン座標でピクセルの色を返します。
boolean	isAutoWaitForIdle()	イベントを生成したあと、このRobotがwaitForIdleを自動的に呼び出すかどうかを返します。
void	keyPress(int keycode)	指定されたキーを押します。
void	keyRelease(int keycode)	指定されたキーを離します。
void	mouseMove(int x, int y)	指定したスクリーン座標にマウス・ポインタを移動します。
void	mousePress(int buttons)	1つまたは複数のマウス・ボタンを押します。
void	mouseRelease(int buttons)	1つまたは複数のマウス・ボタンを離します。
void	mouseWheel(int wheelAmt)	ホイール・マウスのホイール・スクロールを回転させます。
void	setAutoDelay(int ms)	イベント生成後、このRobotがスリープする時間をミリ秒で設定します。
void	setAutoWaitForIdle(boolean isOn)	イベントを生成したあと、このRobotがwaitForIdleを自動的に呼び出すかどうかを設定します。
String	toString()	このRobotの文字列表現を返します。
void	waitForIdle()	現在イベント・キューにあるすべてのイベントが処理されるまで待機します。

クラスjava.lang.Objectで宣言されたメソッド

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

コンストラクタの詳細

Robot

public Robot() throws AWTException

プライマリ・スクリーンの座標システムでRobotオブジェクトを構築します。

例外:

AWTException - プラットフォーム構成で低レベルの入力制御が許可されない場合。 この例外はGraphicsEnvironment.isHeadless()がtrueを返す場合に必ずスローされる

SecurityException - createRobotアクセス権が許可されない場合

関連項目:

• GraphicsEnvironment.isHeadless()
• SecurityManager.checkPermission(java.security.Permission)
• AWTPermission

Robot

public Robot(GraphicsDevice screen) throws AWTException

指定されたスクリーン・デバイスにRobotを作成します。 mouseMove、getPixelColor、createScreenCaptureなどのRobotメソッド・コールに渡される座標は、指定された画面と同じ座標系にあると解釈されます。 プラットフォーム構成によっては、複数スクリーンで次のことが行えます。

• 同じ座標系を共有し、仮想スクリーンを結合する
• 異なる座標系を使用し、個々のスクリーンのように動作する

スクリーン・デバイスで座標系に影響がでるように再構成されている場合、既存のRobotオブジェクトの動作は保証されません。

パラメータ:

screen - Robotが動作する座標系を示す、スクリーンGraphicsDevice。

例外:

AWTException - プラットフォーム構成で低レベルの入力制御が許可されない場合。 この例外はGraphicsEnvironment.isHeadless()がtrueを返す場合に必ずスローされる。

IllegalArgumentException - screenがスクリーンGraphicsDeviceではない場合。

SecurityException - createRobotアクセス権が許可されない場合

関連項目:

• GraphicsEnvironment.isHeadless()
• GraphicsDevice
• SecurityManager.checkPermission(java.security.Permission)
• AWTPermission

メソッドの詳細

mouseMove

public void mouseMove(int x, int y)

指定したスクリーン座標にマウス・ポインタを移動します。

一部のプラットフォームではマウス・ポインタが視覚的に移動しない場合がありますが、後続のmousePressおよびmouseReleaseを正しいロケーションに配信できます

パラメータ:

x - X位置

y - Y位置

mousePress

public void mousePress(int buttons)

1つまたは複数のマウス・ボタンを押します。 マウス・ボタンを離すにはmouseRelease(int)メソッドを使用する必要があります。

パラメータ:

buttons - Buttonマスク。1つ以上のマウス・ボタン・マスクの組み合わせ。

buttonsパラメータとして有効な値の組み合わせのみの使用が許可されます。 有効な組み合わせは、InputEvent.getMaskForButton(button)メソッドによって返されたInputEvent.BUTTON1_DOWN_MASK、InputEvent.BUTTON2_DOWN_MASK、InputEvent.BUTTON3_DOWN_MASK、および値で構成されます。 有効な組み合わせは、次のようにToolkit.areExtraMouseButtonsEnabled()値によっても異なります。

• 拡張マウス・ボタンのサポートがJavaでdisabledにされている場合は、標準ボタン・マスクInputEvent.BUTTON1_DOWN_MASK、InputEvent.BUTTON2_DOWN_MASK、InputEvent.BUTTON3_DOWN_MASKのみを使用できます。
• 拡張マウス・ボタンのサポートがJavaでenabledにされている場合は、標準ボタン・マスクを使用でき、マウスに4つ以上のボタンがあれば、存在する拡張マウス・ボタンのマスクを使用できます。 そのようにして、1からMouseInfo.getNumberOfButtons()までの範囲のボタンに対応するボタン・マスクの使用が許可されます。
  InputEvent.getMaskForButton(button)メソッドを使用して、任意のマウス・ボタンのマスクをその番号で取得することをお薦めします。

また、次の標準のボタン・マスクも受け入れられます。

• InputEvent.BUTTON1_MASK
• InputEvent.BUTTON2_MASK
• InputEvent.BUTTON3_MASK

ただし、代わりにInputEvent.BUTTON1_DOWN_MASK、InputEvent.BUTTON2_DOWN_MASK、InputEvent.BUTTON3_DOWN_MASKを使用することをお薦めします。 拡張された_DOWN_MASKまたは古い_MASKのどちらかの値を使用するべきですが、これらの両方のモデルを混在させてはいけません。

例外:

IllegalArgumentException - buttonsマスクに追加のマウス・ボタンのマスクが含まれ、拡張されたマウス・ボタンのサポートがJavaによってdisabledになっている場合

IllegalArgumentException - buttonsマスクに、マウス上に存在しない追加のマウス・ボタンのマスクが含まれ、拡張されたマウス・ボタンのサポートがJavaによってenabledになっている場合

関連項目:

• mouseRelease(int)
• InputEvent.getMaskForButton(int)
• Toolkit.areExtraMouseButtonsEnabled()
• MouseInfo.getNumberOfButtons()
• MouseEvent

mouseRelease

public void mouseRelease(int buttons)

1つまたは複数のマウス・ボタンを離します。

パラメータ:

buttons - Buttonマスク。1つ以上のマウス・ボタン・マスクの組み合わせ。

buttonsパラメータとして有効な値の組み合わせのみの使用が許可されます。 有効な組み合わせは、InputEvent.getMaskForButton(button)メソッドによって返されたInputEvent.BUTTON1_DOWN_MASK、InputEvent.BUTTON2_DOWN_MASK、InputEvent.BUTTON3_DOWN_MASK、および値で構成されます。 有効な組み合わせは、次のようにToolkit.areExtraMouseButtonsEnabled()値によっても異なります。

• 拡張マウス・ボタンのサポートがJavaでdisabledにされている場合は、標準ボタン・マスクInputEvent.BUTTON1_DOWN_MASK、InputEvent.BUTTON2_DOWN_MASK、InputEvent.BUTTON3_DOWN_MASKのみを使用できます。
• 拡張マウス・ボタンのサポートがJavaでenabledにされている場合は、標準ボタン・マスクを使用でき、マウスに4つ以上のボタンがあれば、存在する拡張マウス・ボタンのマスクを使用できます。 そのようにして、1からMouseInfo.getNumberOfButtons()までの範囲のボタンに対応するボタン・マスクの使用が許可されます。
  InputEvent.getMaskForButton(button)メソッドを使用して、任意のマウス・ボタンのマスクをその番号で取得することをお薦めします。

また、次の標準のボタン・マスクも受け入れられます。

• InputEvent.BUTTON1_MASK
• InputEvent.BUTTON2_MASK
• InputEvent.BUTTON3_MASK

ただし、代わりにInputEvent.BUTTON1_DOWN_MASK、InputEvent.BUTTON2_DOWN_MASK、InputEvent.BUTTON3_DOWN_MASKを使用することをお薦めします。 拡張された_DOWN_MASKまたは古い_MASKのどちらかの値を使用するべきですが、これらの両方のモデルを混在させてはいけません。

例外:

IllegalArgumentException - buttonsマスクに追加のマウス・ボタンのマスクが含まれ、拡張されたマウス・ボタンのサポートがJavaによってdisabledになっている場合

IllegalArgumentException - buttonsマスクに、マウス上に存在しない追加のマウス・ボタンのマスクが含まれ、拡張されたマウス・ボタンのサポートがJavaによってenabledになっている場合

関連項目:

• mousePress(int)
• InputEvent.getMaskForButton(int)
• Toolkit.areExtraMouseButtonsEnabled()
• MouseInfo.getNumberOfButtons()
• MouseEvent

mouseWheel

public void mouseWheel(int wheelAmt)

ホイール・マウスのホイール・スクロールを回転させます。

パラメータ:

wheelAmt - マウス・ホイールを移動する「ノッチ」の数。負の値はユーザーから見て上または離れる方向への移動を示し、正の値はユーザーから見て下または近づく方向への移動を示す。

導入されたバージョン:

1.4

keyPress

public void keyPress(int keycode)

指定されたキーを押します。 キーを離すにはkeyReleaseメソッドを使用する必要があります。

複数の物理的なキーが関連付けられているキー・コード(たとえば、KeyEvent.VK_SHIFTは左または右のShiftキーを示す可能性がある)は、左のキーにマップされます。

パラメータ:

keycode - 押す対象のキー(KeyEvent.VK_Aなど)

例外:

IllegalArgumentException - keycodeが有効なキーでない場合

関連項目:

• keyRelease(int)
• KeyEvent

keyRelease

public void keyRelease(int keycode)

指定されたキーを離します。

複数の物理的なキーが関連付けられているキー・コード(たとえば、KeyEvent.VK_SHIFTは左または右のShiftキーを示す可能性がある)は、左のキーにマップされます。

パラメータ:

keycode - 離す対象のキー(KeyEvent.VK_Aなど)

例外:

IllegalArgumentException - keycodeが有効なキーでない場合

関連項目:

• keyPress(int)
• KeyEvent

getPixelColor

public Color getPixelColor(int x, int y)

指定されたスクリーン座標でピクセルの色を返します。

デスクトップ環境で画面コンテンツを取得する権限を付与する必要があり、必要な権限が付与されていない場合は、SecurityExceptionがスローされるか、返されたColorの内容が未定義になります。

APIのノート:

スクリーン・キャプチャは長い操作である可能性があるため(特に権限の取得が必要でユーザーの操作を伴う場合)、AWTイベント・ディスパッチ・スレッドでこのメソッドをコールしないことをお薦めします。

パラメータ:

x - ピクセルのX位置

y - ピクセルのY位置

戻り値:

ピクセルの色

例外:

SecurityException - readDisplayPixelsアクセス権が付与されていないか、またはデスクトップ環境で画面へのアクセスが拒否された場合

createScreenCapture

public BufferedImage createScreenCapture(Rectangle screenRect)

スクリーンから読み取るピクセルを含むイメージを作成します。

デスクトップ環境で画面の内容を取得する権限を付与する必要があり、必要な権限が付与されていない場合は、SecurityExceptionがスローされるか、返されたBufferedImageの内容が未定義になります。

APIのノート:

スクリーン・キャプチャは長い操作である可能性があるため(特に権限の取得が必要でユーザーの操作を伴う場合)、AWTイベント・ディスパッチ・スレッドでこのメソッドをコールしないことをお薦めします。

パラメータ:

screenRect - スクリーン座標で取り込むRect

戻り値:

取り込んだイメージ

例外:

IllegalArgumentException - screenRectの幅および高さが0以下の場合

SecurityException - readDisplayPixelsアクセス権が付与されていないか、またはデスクトップ環境で画面へのアクセスが拒否された場合

関連項目:

• SecurityManager.checkPermission(java.security.Permission)
• AWTPermission

createMultiResolutionScreenCapture

public MultiResolutionImage createMultiResolutionScreenCapture(Rectangle screenRect)

スクリーンから読み取るピクセルを含むイメージを作成します。 このメソッドは、ユーザー領域から画面(device)領域へのスケーリング変換がある場合に使用できます。 通常、これはディスプレイが高解像度の画面であることを意味しますが、厳密には、このような変換が存在する場合を意味します。 MultiResolutionImageを返します。

非スケール表示の場合、MultiResolutionImageには1つのイメージ・バリアントがあります:

• ユーザーが指定したサイズのベース・イメージ。

スケーリング変換がある高解像度表示の場合、MultiResolutionImageには2つのイメージ・バリアントがあります:

• ユーザーが指定したサイズのベース・イメージ。 これは画面からスケーリングされます。
• デバイス・サイズ・ピクセルによるネイティブ・デバイス解像度イメージ。

例:

      Image nativeResImage;
      MultiResolutionImage mrImage = robot.createMultiResolutionScreenCapture(frame.getBounds());
      List<Image> resolutionVariants = mrImage.getResolutionVariants();
      if (resolutionVariants.size() > 1) {
          nativeResImage = resolutionVariants.get(1);
      } else {
          nativeResImage = resolutionVariants.get(0);
      }
 

パラメータ:

screenRect - スクリーン座標で取り込むRect

戻り値:

取り込んだイメージ

例外:

IllegalArgumentException - screenRectの幅および高さが0以下の場合

SecurityException - readDisplayPixelsアクセス権が付与されていないか、またはデスクトップ環境で画面へのアクセスが拒否された場合

導入されたバージョン:

9

関連項目:

• SecurityManager.checkPermission(java.security.Permission)
• AWTPermission

isAutoWaitForIdle

public boolean isAutoWaitForIdle()

イベントを生成したあと、このRobotがwaitForIdleを自動的に呼び出すかどうかを返します。

戻り値:

waitForIdleが自動で呼び出されるかどうか

setAutoWaitForIdle

public void setAutoWaitForIdle(boolean isOn)

イベントを生成したあと、このRobotがwaitForIdleを自動的に呼び出すかどうかを設定します。

パラメータ:

isOn - waitForIdleが自動で起動されるかどうか

getAutoDelay

public int getAutoDelay()

イベント生成後、このRobotがスリープする時間をミリ秒で返します。

戻り値:

遅延時間(ミリ秒単位)

setAutoDelay

public void setAutoDelay(int ms)

イベント生成後、このRobotがスリープする時間をミリ秒で設定します。

パラメータ:

ms - 遅延時間(ミリ秒単位)

例外:

IllegalArgumentException - msが0から60,000ミリ秒の範囲にない場合

delay

public void delay(int ms)

指定時間スリープします。

呼出し側スレッドが待機中に中断されると、割込みステータスが設定された状態ですぐに戻ります。 割り込みステータスがすでに設定されている場合、このメソッドは割り込みステータスが設定された状態でただちに復帰します。

パラメータ:

ms - ミリ秒単位のスリープ時間

例外:

IllegalArgumentException - msが0から60,000ミリ秒の間にない場合

waitForIdle

public void waitForIdle()

現在イベント・キューにあるすべてのイベントが処理されるまで待機します。

例外:

IllegalThreadStateException - AWTイベント・ディスパッチ・スレッドに対して呼び出された場合

toString

public String toString()

このRobotの文字列表現を返します。

オーバーライド:

toString、クラスObject

戻り値:

文字列表現。