モジュール 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を使用するアプリケーションでは、これらの例外条件を正常に処理する必要があります。

導入されたバージョン:
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)
      指定したスクリーン座標にマウス・ポインタを移動します。
      パラメータ:
      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)
      指定されたスクリーン座標でピクセルの色を返します。
      パラメータ:
      x - ピクセルのX位置
      y - ピクセルのY位置
      戻り値:
      ピクセルの色

    • createScreenCapture

      public BufferedImage createScreenCapture​(Rectangle screenRect)
      スクリーンから読み取るピクセル・イメージを作成します。 このイメージにはマウス・カーソルが含まれません。
      パラメータ:
      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
      戻り値:
      文字列表現。