libjava/classpath/java/awt/Robot.java

   1 /* Robot.java -- a native input event generator
   2    Copyright (C) 2004, 2005  Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.awt;
  40
  41 import gnu.java.awt.ClasspathToolkit;
  42
  43 import java.lang.reflect.InvocationTargetException;
  44 import java.awt.event.InputEvent;
  45 import java.awt.image.BufferedImage;
  46 import java.awt.peer.RobotPeer;
  47
  48 /**
  49  * The Robot class is used to simulate user interaction with graphical
  50  * programs.  It can generate native windowing system input events and
  51  * retrieve image data from the current screen.  Robot is used to test
  52  * the AWT and Swing library implementations; it can also be used to
  53  * create self-running demo programs.
  54  *
  55  * Since Robot generates native windowing system events, rather than
  56  * simply inserting {@link AWTEvent}s on the AWT event queue, its use
  57  * is not restricted to Java programs.  It can be used to
  58  * programatically drive any graphical application.
  59  *
  60  * This implementation requires an X server that supports the XTest
  61  * extension.
  62  *
  63  * @author Thomas Fitzsimmons (fitzsim@redhat.com)
  64  *
  65  * @since 1.3
  66  */
  67 public class Robot
  68 {
  69   private boolean waitForIdle;
  70   private int autoDelay;
  71   private RobotPeer peer;
  72
  73   /**
  74    * Construct a Robot object that operates on the default screen.
  75    *
  76    * @exception AWTException if GraphicsEnvironment.isHeadless()
  77    * returns true or if the X server does not support the XTest
  78    * extension
  79    * @exception SecurityException if createRobot permission is not
  80    * granted
  81    */
  82   public Robot () throws AWTException
  83   {
  84     if (GraphicsEnvironment.isHeadless ())
  85       throw new AWTException ("Robot: headless graphics environment");
  86
  87     SecurityManager sm = System.getSecurityManager ();
  88     if (sm != null)
  89       sm.checkPermission (new AWTPermission ("createRobot"));
  90
  91     ClasspathToolkit tk = (ClasspathToolkit) Toolkit.getDefaultToolkit ();
  92
  93     // createRobot will throw AWTException if XTest is not supported.
  94     peer = tk.createRobot (GraphicsEnvironment.getLocalGraphicsEnvironment ()
  95                            .getDefaultScreenDevice ());
  96   }
  97
  98   /**
  99    * Construct a Robot object that operates on the specified screen.
 100    *
 101    * @exception AWTException if GraphicsEnvironment.isHeadless()
 102    * returns true or if the X server does not support the XTest
 103    * extension
 104    * @exception IllegalArgumentException if screen is not a screen
 105    * GraphicsDevice
 106    * @exception SecurityException if createRobot permission is not
 107    * granted
 108    */
 109   public Robot (GraphicsDevice screen) throws AWTException
 110   {
 111     if (GraphicsEnvironment.isHeadless ())
 112       throw new AWTException ("Robot: headless graphics environment");
 113
 114     if (screen.getType () != GraphicsDevice.TYPE_RASTER_SCREEN)
 115       throw new IllegalArgumentException ("Robot: graphics"
 116                                           + " device is not a screen");
 117
 118     SecurityManager sm = System.getSecurityManager ();
 119     if (sm != null)
 120       sm.checkPermission (new AWTPermission ("createRobot"));
 121
 122     ClasspathToolkit tk = (ClasspathToolkit) Toolkit.getDefaultToolkit ();
 123
 124     // createRobot will throw AWTException if XTest is not supported.
 125     peer = tk.createRobot (screen);
 126   }
 127
 128   /**
 129    * Move the mouse pointer to absolute coordinates (x, y).
 130    *
 131    * @param x the destination x coordinate
 132    * @param y the destination y coordinate
 133    */
 134   public void mouseMove(int x, int y)
 135   {
 136     peer.mouseMove (x, y);
 137
 138     if (waitForIdle)
 139       waitForIdle ();
 140
 141     if (autoDelay > 0)
 142       delay (autoDelay);
 143   }
 144
 145   /**
 146    * Press one or more mouse buttons.
 147    *
 148    * @param buttons the buttons to press; a bitmask of one or more of
 149    * these {@link InputEvent} fields:
 150    *
 151    * <ul>
 152    *   <li>BUTTON1_MASK</li>
 153    *   <li>BUTTON2_MASK</li>
 154    *   <li>BUTTON3_MASK</li>
 155    * </ul>
 156    *
 157    * @exception IllegalArgumentException if the button mask is invalid
 158    */
 159   public void mousePress (int buttons)
 160   {
 161     if ((buttons & InputEvent.BUTTON1_MASK) == 0
 162         && (buttons & InputEvent.BUTTON2_MASK) == 0
 163         && (buttons & InputEvent.BUTTON3_MASK) == 0)
 164       throw new IllegalArgumentException ("Robot: mousePress:"
 165                                           + " invalid button mask");
 166
 167     peer.mousePress (buttons);
 168
 169     if (waitForIdle)
 170       waitForIdle ();
 171
 172     if (autoDelay > 0)
 173       delay (autoDelay);
 174   }
 175
 176   /**
 177    * Release one or more mouse buttons.
 178    *
 179    * @param buttons the buttons to release; a bitmask of one or more
 180    * of these {@link InputEvent} fields:
 181    *
 182    * <ul>
 183    *   <li>BUTTON1_MASK</li>
 184    *   <li>BUTTON2_MASK</li>
 185    *   <li>BUTTON3_MASK</li>
 186    * </ul>
 187    *
 188    * @exception IllegalArgumentException if the button mask is invalid
 189    */
 190   public void mouseRelease(int buttons)
 191   {
 192     if ((buttons & InputEvent.BUTTON1_MASK) == 0
 193         && (buttons & InputEvent.BUTTON2_MASK) == 0
 194         && (buttons & InputEvent.BUTTON3_MASK) == 0)
 195       throw new IllegalArgumentException ("Robot: mouseRelease:"
 196                                           + " invalid button mask");
 197
 198     peer.mouseRelease (buttons);
 199
 200     if (waitForIdle)
 201       waitForIdle ();
 202
 203     if (autoDelay > 0)
 204       delay (autoDelay);
 205   }
 206
 207   /**
 208    * Rotate the mouse scroll wheel.
 209    *
 210    * @param wheelAmt number of steps to rotate mouse wheel.  negative
 211    * to rotate wheel up (away from the user), positive to rotate wheel
 212    * down (toward the user).
 213    *
 214    * @since 1.4
 215    */
 216   public void mouseWheel (int wheelAmt)
 217   {
 218     peer.mouseWheel (wheelAmt);
 219
 220     if (waitForIdle)
 221       waitForIdle ();
 222
 223     if (autoDelay > 0)
 224       delay (autoDelay);
 225   }
 226
 227   /**
 228    * Press a key.
 229    *
 230    * @param keycode key to press, a {@link java.awt.event.KeyEvent} VK_ constant
 231    *
 232    * @exception IllegalArgumentException if keycode is not a valid key
 233    */
 234   public void keyPress (int keycode)
 235   {
 236     peer.keyPress (keycode);
 237
 238     if (waitForIdle)
 239       waitForIdle ();
 240
 241     if (autoDelay > 0)
 242       delay (autoDelay);
 243   }
 244
 245   /**
 246    * Release a key.
 247    *
 248    * @param keycode key to release, a {@link java.awt.event.KeyEvent} VK_
 249    *                constant
 250    *
 251    * @exception IllegalArgumentException if keycode is not a valid key
 252    */
 253   public void keyRelease (int keycode)
 254   {
 255     peer.keyRelease (keycode);
 256
 257     if (waitForIdle)
 258       waitForIdle ();
 259
 260     if (autoDelay > 0)
 261       delay (autoDelay);
 262   }
 263
 264   /**
 265    * Return the color of the pixel at the given screen coordinates.
 266    *
 267    * @param x the x coordinate of the pixel
 268    * @param y the y coordinate of the pixel
 269    *
 270    * @return the Color of the pixel at screen coodinates <code>(x, y)</code>
 271    */
 272   public Color getPixelColor (int x, int y)
 273   {
 274     return new Color (peer.getRGBPixel (x, y));
 275   }
 276
 277   /**
 278    * Create an image containing pixels read from the screen.  The
 279    * image does not include the mouse pointer.
 280    *
 281    * @param screenRect the rectangle of pixels to capture, in screen
 282    * coordinates
 283    *
 284    * @return a BufferedImage containing the requested pixels
 285    *
 286    * @exception IllegalArgumentException if requested width and height
 287    * are not both greater than zero
 288    * @exception SecurityException if readDisplayPixels permission is
 289    * not granted
 290    */
 291   public BufferedImage createScreenCapture (Rectangle screenRect)
 292   {
 293     if (screenRect.width <= 0)
 294       throw new IllegalArgumentException ("Robot: capture width is <= 0");
 295
 296     if (screenRect.height <= 0)
 297       throw new IllegalArgumentException ("Robot: capture height is <= 0");
 298
 299     SecurityManager sm = System.getSecurityManager ();
 300     if (sm != null)
 301       sm.checkPermission (new AWTPermission ("readDisplayPixels"));
 302
 303     int[] pixels = peer.getRGBPixels (screenRect);
 304
 305     BufferedImage bufferedImage =
 306       new BufferedImage (screenRect.width, screenRect.height,
 307                          BufferedImage.TYPE_INT_ARGB);
 308
 309     bufferedImage.setRGB (0, 0, screenRect.width, screenRect.height,
 310                           pixels, 0, screenRect.width);
 311
 312     return bufferedImage;
 313   }
 314
 315   /**
 316    * Check if this Robot automatically calls {@link #waitForIdle()} after
 317    * generating an event.
 318    *
 319    * @return true if waitForIdle is automatically called
 320    */
 321   public boolean isAutoWaitForIdle ()
 322   {
 323     return waitForIdle;
 324   }
 325
 326   /**
 327    * Set whether or not this Robot automatically calls {@link
 328    * #waitForIdle()} after generating an event.
 329    *
 330    * @param isOn true if waitForIdle should be called automatically
 331    */
 332   public void setAutoWaitForIdle (boolean isOn)
 333   {
 334     waitForIdle = isOn;
 335   }
 336
 337   /**
 338    * Retrieve the length of time this Robot sleeps after generating an
 339    * event.
 340    *
 341    * @return the length of time in milliseconds
 342    */
 343   public int getAutoDelay ()
 344   {
 345     return autoDelay;
 346   }
 347
 348   /**
 349    * Set the length of time this Robot sleeps after generating an
 350    * event.
 351    *
 352    * @param ms the length of time in milliseconds
 353    *
 354    * @exception IllegalArgumentException if ms is not between 0 and
 355    * 60,000 milliseconds inclusive
 356    */
 357   public void setAutoDelay (int ms)
 358   {
 359     if (ms <= 0 || ms >= 60000)
 360       throw new IllegalArgumentException ("Robot: delay length out-of-bounds");
 361
 362     autoDelay = ms;
 363   }
 364
 365   /**
 366    * Sleep for a specified length of time.
 367    *
 368    * @param ms the length of time in milliseconds
 369    *
 370    * @exception IllegalArgumentException if ms is not between 0 and
 371    * 60,000 milliseconds inclusive
 372    */
 373   public void delay (int ms)
 374   {
 375     if (ms < 0 || ms > 60000)
 376       throw new IllegalArgumentException ("Robot: delay length out-of-bounds");
 377
 378     try
 379       {
 380         Thread.sleep (ms);
 381       }
 382     catch (InterruptedException e)
 383       {
 384         System.err.println ("Robot: delay interrupted");
 385       }
 386   }
 387
 388   /**
 389    * Wait until all events currently on the event queue have been
 390    * dispatched.
 391    */
 392   public void waitForIdle ()
 393   {
 394     if (EventQueue.isDispatchThread ())
 395       throw new IllegalThreadStateException ("Robot: waitForIdle called from "
 396                                              + "the event dispatch thread");
 397
 398     try
 399       {
 400         EventQueue.invokeAndWait (new Runnable () { public void run () { } });
 401       }
 402     catch (InterruptedException e)
 403       {
 404         System.err.println ("Robot: waitForIdle interrupted");
 405       }
 406     catch (InvocationTargetException e)
 407       {
 408         System.err.println ("Robot: waitForIdle cannot invoke target");
 409       }
 410   }
 411
 412   /**
 413    * Return a string representation of this Robot.
 414    *
 415    * @return a string representation
 416    */
 417   public String toString ()
 418   {
 419     return getClass ().getName ()
 420         + "[ autoDelay = " + autoDelay + ", autoWaitForIdle = "
 421         + waitForIdle + " ]";
 422   }
 423 }