モジュール java.desktop
パッケージ 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​()
      現在イベント・キューにあるすべてのイベントが処理されるまで待機します。

    • コンストラクタの詳細

      • 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位置
        戻り値:
        ピクセルの色

      • 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)
        指定時間スリープします。 発生する任意のInterruptedExceptionをキャッチするために、代わりにThread.sleep()が使用されます。
        パラメータ:
        ms - ミリ秒単位のスリープ時間
        例外:
        IllegalArgumentException - msが0から60,000ミリ秒の範囲にない場合
        関連項目:
        Thread.sleep(long)

      • waitForIdle

        public void waitForIdle​()
        現在イベント・キューにあるすべてのイベントが処理されるまで待機します。
        例外:
        IllegalThreadStateException - AWTイベント・ディスパッチ・スレッドに対して呼び出された場合

      • toString

        public String toString​()
        このRobotの文字列表現を返します。
        オーバーライド:
        toString、クラス: Object
        戻り値:
        文字列表現。