Summary

Migrate useful ExtendedRobot methods into java.awt.Robot.

Problem

ExtendedRobot contains useful convenience methods but requires building ExtendedRobot in each test. These methods could also be widely useful outside of testing. Each of these methods requires a new specification that is updated to meet the standards of the javadocs specification.

Solution

Add updated specifications to each ExtendedRobot method migrated into AWT Robot.

Specification

class java/awt/Robot.java

+    /**
+     * Default 20 milliseconds delay for mouse {@code click} and
+     * step delay for mouse {@code glide}.
+     */
+    public static final int DEFAULT_DELAY = 20;
+
+    /**
+     * Default 2 pixel step length for mouse {@code glide}.
+     */
+    public static final int DEFAULT_STEP_LENGTH = 2;


+    /**
+     * A convenience method that simulates clicking a mouse button by calling {@code mousePress}
+     * and {@code mouseRelease}. Invokes {@code waitForIdle} with a default {@link #DEFAULT_DELAY delay} after
+     * {@code mousePress} and {@code mouseRelease} calls. For specifics on valid inputs please see
+     * {@link java.awt.Robot#mousePress(int)}.
+     *
+     * @param   buttons The button mask; a combination of one or more mouse button masks.
+     * @throws  IllegalArgumentException if the {@code buttons} mask contains the mask for
+     *          extra mouse button and support for extended mouse buttons is
+     *          {@link Toolkit#areExtraMouseButtonsEnabled() disabled} by Java
+     * @throws  IllegalArgumentException if the {@code buttons} mask contains the mask for
+     *          extra mouse button that does not exist on the mouse and support for extended
+     *          mouse buttons is {@link Toolkit#areExtraMouseButtonsEnabled() enabled}
+     *          by Java
+     * @throws  IllegalThreadStateException if called on the AWT event dispatching thread
+     * @see     #mousePress(int)
+     * @see     #mouseRelease(int)
+     * @see     #DEFAULT_DELAY
+     * @see     InputEvent#getMaskForButton(int)
+     * @see     Toolkit#areExtraMouseButtonsEnabled()
+     * @see     java.awt.event.MouseEvent
+     * @since   25
+     */
+    public void click(int buttons);


+    /**
+     * A convenience method that clicks mouse button 1.
+     *
+     * @throws  IllegalThreadStateException if called on the AWT event dispatching thread
+     * @see     #click(int)
+     * @since   25
+     */
+    public void click();


+    /**
+     * A convenience method that calls {@code waitForIdle} then waits an additional specified
+     * {@code delayValue} time in milliseconds.
+     *
+     * @param   delayValue  Additional delay length in milliseconds to wait until thread
+     *                      sync been completed
+     * @throws  IllegalThreadStateException if called on the AWT event
+     *          dispatching thread
+     * @throws  IllegalArgumentException if {@code delayValue} is not between {@code 0}
+     *          and {@code 60,000} milliseconds inclusive
+     * @since   25
+     */
+    public synchronized void waitForIdle(int delayValue);


+    /**
+     * A convenience method that moves the mouse in multiple
+     * steps from its current location to the destination coordinates
+     * with a default {@link #DEFAULT_STEP_LENGTH step-length} and {@link #DEFAULT_DELAY delay}.
+     *
+     * @param   x   Destination point x coordinate
+     * @param   y   Destination point y coordinate
+     * @see     #DEFAULT_STEP_LENGTH
+     * @see     #DEFAULT_DELAY
+     * @see     #glide(int, int, int, int, int, int)
+     * @since   25
+     */
+    public void glide(int x, int y);


+    /**
+     * A convenience method that moves the mouse in multiple steps
+     * from source coordinates to the destination coordinates with
+     * a default {@link #DEFAULT_STEP_LENGTH step-length} and {@link #DEFAULT_DELAY delay}.
+     *
+     * @param   fromX   Source point x coordinate
+     * @param   fromY   Source point y coordinate
+     * @param   toX     Destination point x coordinate
+     * @param   toY     Destination point y coordinate
+     * @see     #DEFAULT_STEP_LENGTH
+     * @see     #DEFAULT_DELAY
+     * @see     #glide(int, int, int, int, int, int)
+     * @since   25
+     */
+    public void glide(int fromX, int fromY, int toX, int toY);


+    /**
+     * A convenience method that moves the mouse in multiple
+     * steps from source point to the destination point with
+     * given {@code stepLength} and {@code stepDelay}.
+     *
+     * @param   srcX        Source point x coordinate
+     * @param   srcY        Source point y coordinate
+     * @param   destX       Destination point x coordinate
+     * @param   destY       Destination point y coordinate
+     * @param   stepLength  Preferred length of one step in pixels
+     * @param   stepDelay   Delay between steps in milliseconds
+     *
+     * @throws  IllegalArgumentException if {@code stepLength} is a negative value or
+     *          greater than the distance between source and destination points
+     * @throws  IllegalArgumentException if {@code stepDelay} is not between {@code 0}
+     *          and {@code 60,000} milliseconds inclusive
+     * @see     #mouseMove(int, int)
+     * @see     #delay(int)
+     * @since   25
+     */
+    public void glide(int srcX, int srcY, int destX, int destY, int stepLength, int stepDelay);


+    /**
+     * A convenience method that simulates typing a key by calling {@code keyPress}
+     * and {@code keyRelease}. Invokes {@code waitForIdle} with a default {@link #DEFAULT_DELAY delay}
+     * after {@code keyPress} and {@code keyRelease} calls.
+     * 

+     * Key codes that have more than one physical key associated with them
+     * (e.g. {@code KeyEvent.VK_SHIFT} could mean either the
+     * left or right shift key) will map to the left key.
+     *
+     * @param   keycode Key to type (e.g. {@code KeyEvent.VK_A})
+     * @throws  IllegalArgumentException if {@code keycode} is not
+     *          a valid key
+     * @throws  IllegalThreadStateException if called on the AWT event dispatching thread
+     * @see     #keyPress(int)
+     * @see     #keyRelease(int)
+     * @see     java.awt.event.KeyEvent
+     * @see     #DEFAULT_DELAY
+     * @since   25
+     */
+    public synchronized void type(int keycode);