abbot.tester
Class Robot

java.lang.Object
  extended byabbot.tester.Robot
Direct Known Subclasses:
ComponentTester

public class Robot
extends Object

Provide a higher level of abstraction for user input (A Better Robot). The Robot's operation may be affected by the following properties:

abbot.robot.auto_delay

Set this to a value representing the millisecond count in between generated events. Usually just set to 100-200 if you want to slow down the playback to simulate actual user input. The default is zero delay.
abbot.robot.mode

Set this to either "robot" or "awt" to designate the desired mode of event generation. "robot" uses java.awt.Robot to generate events, while "awt" stuffs events directly into the AWT event queue.
abbot.robot.event_post_delay

This is the maximum number of ms it takes the system to post an AWT event in response to a Robot-generated event.
abbot.robot.default_delay

Base delay setting, acts as default value for the next two.
abbot.robot.popup_delay

Set this to the maximum time to wait for a menu to appear or be generated.
abbot.robot.component_delay

Set this to the maximum time to wait for a Component to become available.

NOTE: Only use invokeAndWait when a subsequent robot-level action is being applied to the results of a prior action (e.g. focus, deiconify, menu selection). Otherwise, don't introduce a mandatory delay.

NOTE: If a robot action isn't reproduced properly, you may need to introduce either additional events or extra delay. Adding enforced delay for a given platform is preferable to additional events, so always try that first, but be sure to restrict it to the platform in question.

NOTE: Robot actions should never be invoked on the event dispatch thread.


Field Summary
static int BUTTON_MASK
           
static int componentDelay
          Delay before failing to find a component that should be visible.
static int defaultDelay
          Base delay setting.
static int DRAG_THRESHOLD
          Number of pixels traversed before a drag starts.
static int EM_AWT
          Post events to the AWT event queue.
static int EM_ROBOT
          Use java.awt.Robot to generate events.
static String MENU_SHORTCUT_KEYCODE
           
static int MENU_SHORTCUT_MASK
           
static String MENU_SHORTCUT_MODIFIER
           
static String MENU_SHORTCUT_STRING
           
static int MULTI_CLICK_INTERVAL
           
static int POPUP_MASK
           
static String POPUP_MODIFIER
           
static boolean POPUP_ON_PRESS
           
protected static int popupDelay
          Delay before failing to find a popup menu that should appear.
static int TERTIARY_MASK
           
static String TERTIARY_MODIFIER
           
 
Constructor Summary
Robot()
           
 
Method Summary
 void activate(Window win)
          Activate the given window.
static boolean canMoveWindows()
          Returns whether it is possible to move windows that are not an instance of Frame or Dialog.
static boolean canResizeWindows()
          Returns whether it is possible to resize windows that are not an instance of Frame or Dialog.
 BufferedImage capture(Component comp)
          Capture the contents of the given component, sans any border or insets.
 BufferedImage capture(Component comp, boolean ignoreBorder)
          Capture the contents of the given component, optionally including the border and/or insets.
 BufferedImage capture(Rectangle bounds)
          Capture the contents of the given rectangle.
 void click(Component comp)
          Click in the center of the given component.
 void click(Component comp, int mask)
          Click in the center of the given component, specifying which button.
 void click(Component comp, int x, int y)
          Click in the component at the given location.
 void click(Component comp, int x, int y, int mask)
          Click in the component at the given location with the given button.
 void click(Component comp, int x, int y, int mask, int count)
          Click in the given part of the component.
 void close(Window w)
          Invoke the window close operation.
 void deiconify(Frame frame)
           
 void delay(int ms)
          Sleep the given duration of ms.
protected static String descriptiveClassName(Class cls)
           
 void drag(Component src, int sx, int sy)
          Begin a drag operation using button 1.
 void drag(Component src, int sx, int sy, int buttons)
          Begin a drag operation using the given button mask.
 void dragOver(Component dst, int x, int y)
          Move the mouse appropriately to get from the source to the destination.
 void drop(Component target, int x, int y)
          End a drag operation, releasing the mouse button over the given target location.
 Component findFocusOwner()
          Return the Component which currently owns the focus.
protected  void fireAccessibleAction(AccessibleAction action, String name)
           
 void focus(Component comp)
          Move keyboard focus to the given component.
 void focus(Component comp, boolean wait)
          Move keyboard focus to the given component.
static int getAutoDelay()
           
static Class getCanonicalClass(Class refClass)
           
protected  Point getCloseLocation(Container c)
           
static String getEventID(AWTEvent event)
          Return the symbolic name of the given event's ID.
static int getEventID(Class cls, String id)
          Return the numeric event ID corresponding to the given string.
static int getEventMode()
          Returns the current event-generation mode.
static String getEventModeDescription()
           
static int getEventPostDelay()
           
protected  EventQueue getEventQueue(Component c)
          Usually only needed when dealing with Applets.
protected  Point getIconifyLocation(Container c)
          Identify the coordinates of the iconify button where we can, returning (0, 0) if we can't.
static String getKeyCode(int keycode)
           
static int getKeyCode(String code)
           
static String getKeyModifiers(int flags)
           
protected  Point getMaximizeLocation(Container c)
          Identify the coordinates of the maximize button where possible, returning null if not.
static String getModifiers(InputEvent event)
          Convert the integer modifier flags into a string representation.
static int getModifiers(String mods)
          Convert the string representation into the actual modifier mask.
static String getMouseModifiers(int flags)
           
protected  Point getMoveLocation(Container c)
          Return where the mouse usually grabs to move a window.
static int getPreferredRobotAutoDelay()
          Returns the appropriate auto delay for robot-generated events.
protected  Point getResizeLocation(Container c)
          Return where the mouse usually grabs to resize a window.
static boolean hasFrameDeiconifyBug()
           
static boolean hasHierarchyEventGenerationBug()
          Prior to 1.4.1, hierarchy events are only sent if listeners are added to a given component.
static boolean hasKeyStrokeGenerationBug()
          OSX prior to 1.4 has really crappy key input handling.
static boolean hasMultiClickFrameBug()
          Do we get multiple clicks even when the individual clicks are on different frames?
static boolean hasRobotMotionBug()
          OS X (as of 1.3.1, v10.1.5), will sometimes send a click to the wrong component after a mouse move.
 void iconify(Frame frame)
          Iconify the given Frame.
 void invokeAction(Component c, Runnable action)
          Post a runnable on the given component's event queue.
 void invokeAction(Runnable action)
          Run the given action on the event dispatch thread.
 void invokeAndWait(Component c, Runnable action)
          Post a runnable on the given component's event queue and wait for it to finish.
 void invokeAndWait(Runnable action)
          Run the given action on the event dispatch thread, but don't return until it's been run.
static boolean isModifier(int keycode)
           
protected  boolean isReadyForInput(Component c)
          Is the given component ready for robot input?
static boolean isTertiaryButton(int mods)
          Return whether this is the tertiary button, considering primary to be button1 and secondary to be the popup trigger button.
protected  void jitter(Component comp, int x, int y)
           
protected  void jitter(int x, int y)
           
 void key(int keycode)
          Type the given keycode with no modifiers.
 void key(int keycode, int modifiers)
          Type the given keycode with the given modifiers.
static int keyCodeToMask(int code)
           
 void keyPress(int keycode)
           
 void keyRelease(int keycode)
          Send a key release event.
 void keyString(String str)
          Type the given string.
 void keyStroke(char ch)
          Type the given character.
static int maskToKeyCode(int mask)
          Convert the given modifier event mask to the equivalent key code.
 void maximize(Frame frame)
          Make the window full size.
 void mouseMove(Component comp)
          Move the pointer to the center of the given component.
 void mouseMove(Component comp, int x, int y)
          Move the pointer to the given coordinates relative to the given component.
 void mousePress(Component comp)
           
 void mousePress(Component comp, int mask)
           
 void mousePress(Component comp, int x, int y)
           
 void mousePress(Component comp, int x, int y, int mask)
          Mouse down in the given part of the component.
 void mousePress(int buttons)
          Send a button press event.
 void mouseRelease()
          Send a button release event for button 1.
 void mouseRelease(int buttons)
          Send a button release event.
 void move(Container comp, int newx, int newy)
          Move the given Frame/Dialog to the requested location.
 void moveBy(Container comp, int dx, int dy)
          Move the given Window by the given amount.
 void normalize(Frame frame)
           
protected  void postEvent(Component comp, AWTEvent ev)
          Post the given event to the corresponding event queue for the given component.
 void reset()
           
 void resize(Container comp, int width, int height)
          Resize the given Frame/Dialog to the given size.
 void resizeBy(Container comp, int dx, int dy)
          Resize the given Frame/Dialog by the given amounts.
 Color sample(Component c, int x, int y)
          Sample the color at the given point on the component.
 Color sample(int x, int y)
          Sample the color at the given point on the screen.
 void selectAWTMenuItem(MenuComponent item)
          Select an AWT menu item.
 void selectAWTMenuItemByLabel(Frame frame, String label)
          Find and select the given AWT menu item.
 void selectAWTPopupMenuItem(MenuComponent item)
          Select an AWT popup menu item.
 void selectAWTPopupMenuItemByLabel(Component invoker, String label)
          Find and select the given AWT popup menu item.
 void selectMenuItem(Component item)
          Find and select the given menu item.
 void sendEvent(AWTEvent event)
          Send the given event as appropriate to the event-generation mode.
static void setAutoDelay(int ms)
          Allow this to be adjusted, mostly for testing.
(package private) static void setEventMode(int mode)
          Set the event-generation mode.
static void setEventPostDelay(int delay)
           
 void setModifiers(int modifiers, boolean press)
          Press or release the appropriate modifiers corresponding to the given mask.
 Component showPopupMenu(Component invoker)
          Attempt to display a popup menu at center of the component.
 Component showPopupMenu(Component invoker, int x, int y)
          Attempt to display a popup menu at the given coordinates.
static String simpleClassName(Class cls)
          Strip the package from the class name.
 void sleep()
          Sleep for a little bit, measured in UI time.
static String toHierarchyPath(Component c)
          Provides the hierarchic path of the given component by component class, e.g.
static String toString(AWTEvent event)
          Provide a more concise representation of the event than the default AWTEvent.toString().
static String toString(Component comp)
          Provides a more concise representation of the component than the default Component.toString().
static String toString(Object obj)
          Provide a string representation of the given component (Component or MenuComponent.
protected  boolean userMovable(Component comp)
          Return whether it is possible for the user to move the given component.
protected  boolean userResizable(Component comp)
          Return whether it is possible for the user to resize the given component.
protected static boolean useScreenMenuBar()
          OS X using screenMenuBar actually uses an AWT menu as the live component.
 void wait(Condition condition)
          Wait for the given Condition to return true.
 void wait(Condition condition, long timeout)
          Wait for the given Condition to return true, waiting for timeout ms.
 void wait(Condition condition, long timeout, int interval)
          Wait for the given Condition to return true, waiting for timeout ms, polling at the given interval.
 void waitForIdle()
          Wait for an idle AWT event queue.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

EM_ROBOT

public static int EM_ROBOT
Use java.awt.Robot to generate events.


EM_AWT

public static int EM_AWT
Post events to the AWT event queue.


MULTI_CLICK_INTERVAL

public static final int MULTI_CLICK_INTERVAL
See Also:
Constant Field Values

DRAG_THRESHOLD

public static final int DRAG_THRESHOLD
Number of pixels traversed before a drag starts.


BUTTON_MASK

public static final int BUTTON_MASK
See Also:
Constant Field Values

POPUP_MASK

public static final int POPUP_MASK

POPUP_MODIFIER

public static final String POPUP_MODIFIER

POPUP_ON_PRESS

public static final boolean POPUP_ON_PRESS

TERTIARY_MASK

public static final int TERTIARY_MASK

TERTIARY_MODIFIER

public static final String TERTIARY_MODIFIER

MENU_SHORTCUT_MASK

public static final int MENU_SHORTCUT_MASK

MENU_SHORTCUT_MODIFIER

public static final String MENU_SHORTCUT_MODIFIER

MENU_SHORTCUT_STRING

public static final String MENU_SHORTCUT_STRING

MENU_SHORTCUT_KEYCODE

public static final String MENU_SHORTCUT_KEYCODE

defaultDelay

public static int defaultDelay
Base delay setting.


popupDelay

protected static int popupDelay
Delay before failing to find a popup menu that should appear.


componentDelay

public static int componentDelay
Delay before failing to find a component that should be visible.

Constructor Detail

Robot

public Robot()
Method Detail

isTertiaryButton

public static boolean isTertiaryButton(int mods)
Return whether this is the tertiary button, considering primary to be button1 and secondary to be the popup trigger button.


useScreenMenuBar

protected static final boolean useScreenMenuBar()
OS X using screenMenuBar actually uses an AWT menu as the live component. The JXXX components exist, but are not effectively active.


getAutoDelay

public static int getAutoDelay()

getEventMode

public static int getEventMode()
Returns the current event-generation mode.


getEventModeDescription

public static String getEventModeDescription()

setEventMode

static void setEventMode(int mode)
Set the event-generation mode.


getEventPostDelay

public static int getEventPostDelay()

setEventPostDelay

public static void setEventPostDelay(int delay)

setAutoDelay

public static void setAutoDelay(int ms)
Allow this to be adjusted, mostly for testing.


mousePress

public void mousePress(int buttons)
Send a button press event.


mouseRelease

public void mouseRelease()
Send a button release event for button 1.


mouseRelease

public void mouseRelease(int buttons)
Send a button release event.


focus

public void focus(Component comp)
Move keyboard focus to the given component. Note that the component may not yet have focus when this method returns.


focus

public void focus(Component comp,
                  boolean wait)
Move keyboard focus to the given component.


getEventQueue

protected EventQueue getEventQueue(Component c)
Usually only needed when dealing with Applets.


invokeAction

public void invokeAction(Component c,
                         Runnable action)
Post a runnable on the given component's event queue. For use when driving Applets.


invokeAndWait

public void invokeAndWait(Component c,
                          Runnable action)
Post a runnable on the given component's event queue and wait for it to finish. For use when driving Applets.


invokeAction

public void invokeAction(Runnable action)
Run the given action on the event dispatch thread. This should be used for any non-read-only methods invoked directly on a GUI component. NOTE: if you want to use the results of the action, use invokeAndWait instead.


invokeAndWait

public void invokeAndWait(Runnable action)
Run the given action on the event dispatch thread, but don't return until it's been run.


keyPress

public void keyPress(int keycode)

keyRelease

public void keyRelease(int keycode)
Send a key release event.


sleep

public void sleep()
Sleep for a little bit, measured in UI time.


delay

public void delay(int ms)
Sleep the given duration of ms.


waitForIdle

public void waitForIdle()
Wait for an idle AWT event queue. Note that this is different from the implementation of the robot wait for idle, which may have events on the queue when it returns. Do NOT use this method if there are animations or other continual refreshes happening, since in that case it may never return.


sample

public Color sample(int x,
                    int y)
Sample the color at the given point on the screen.


sample

public Color sample(Component c,
                    int x,
                    int y)
Sample the color at the given point on the component.


capture

public BufferedImage capture(Rectangle bounds)
Capture the contents of the given rectangle.


capture

public BufferedImage capture(Component comp)
Capture the contents of the given component, sans any border or insets. This should only be used on components that do not use a LAF UI, or the results will not be consistent across platforms.


capture

public BufferedImage capture(Component comp,
                             boolean ignoreBorder)
Capture the contents of the given component, optionally including the border and/or insets. This should only be used on components that do not use a LAF UI, or the results will not be consistent across platforms.


jitter

protected void jitter(Component comp,
                      int x,
                      int y)

jitter

protected void jitter(int x,
                      int y)

mouseMove

public void mouseMove(Component comp)
Move the pointer to the center of the given component.


mouseMove

public void mouseMove(Component comp,
                      int x,
                      int y)
Move the pointer to the given coordinates relative to the given component.


dragOver

public void dragOver(Component dst,
                     int x,
                     int y)
Move the mouse appropriately to get from the source to the destination. Enter/exit events will be generated where appropriate.


drag

public void drag(Component src,
                 int sx,
                 int sy)
Begin a drag operation using button 1.


drag

public void drag(Component src,
                 int sx,
                 int sy,
                 int buttons)
Begin a drag operation using the given button mask.


drop

public void drop(Component target,
                 int x,
                 int y)
End a drag operation, releasing the mouse button over the given target location.


key

public void key(int keycode)
Type the given keycode with no modifiers.


setModifiers

public void setModifiers(int modifiers,
                         boolean press)
Press or release the appropriate modifiers corresponding to the given mask.


key

public void key(int keycode,
                int modifiers)
Type the given keycode with the given modifiers. Modifiers is a mask from the available InputEvent masks.


keyStroke

public void keyStroke(char ch)
Type the given character. Note that this sends the key to whatever component currently has the focus.


keyString

public void keyString(String str)
Type the given string.


mousePress

public void mousePress(Component comp)

mousePress

public void mousePress(Component comp,
                       int mask)

mousePress

public void mousePress(Component comp,
                       int x,
                       int y)

mousePress

public void mousePress(Component comp,
                       int x,
                       int y,
                       int mask)
Mouse down in the given part of the component. All other mousePress methods must eventually invoke this one.


click

public final void click(Component comp)
Click in the center of the given component.


click

public final void click(Component comp,
                        int mask)
Click in the center of the given component, specifying which button.


click

public final void click(Component comp,
                        int x,
                        int y)
Click in the component at the given location.


click

public final void click(Component comp,
                        int x,
                        int y,
                        int mask)
Click in the component at the given location with the given button.


click

public void click(Component comp,
                  int x,
                  int y,
                  int mask,
                  int count)
Click in the given part of the component. All other click methods must eventually invoke this one. This method sometimes needs to be redefined (i.e. JComponent to scroll before clicking).


selectAWTMenuItemByLabel

public void selectAWTMenuItemByLabel(Frame frame,
                                     String label)
Find and select the given AWT menu item. Note that this method doesn't require referencing the MenuComponent directly as a parameter.


selectAWTPopupMenuItemByLabel

public void selectAWTPopupMenuItemByLabel(Component invoker,
                                          String label)
Find and select the given AWT popup menu item.


fireAccessibleAction

protected void fireAccessibleAction(AccessibleAction action,
                                    String name)

selectAWTMenuItem

public void selectAWTMenuItem(MenuComponent item)
Select an AWT menu item.


selectAWTPopupMenuItem

public void selectAWTPopupMenuItem(MenuComponent item)
Select an AWT popup menu item.


isReadyForInput

protected boolean isReadyForInput(Component c)
Is the given component ready for robot input?


selectMenuItem

public void selectMenuItem(Component item)
Find and select the given menu item.


showPopupMenu

public Component showPopupMenu(Component invoker)
Attempt to display a popup menu at center of the component.


showPopupMenu

public Component showPopupMenu(Component invoker,
                               int x,
                               int y)
Attempt to display a popup menu at the given coordinates.


activate

public void activate(Window win)
Activate the given window.


getCloseLocation

protected Point getCloseLocation(Container c)

close

public void close(Window w)
Invoke the window close operation.


getMoveLocation

protected Point getMoveLocation(Container c)
Return where the mouse usually grabs to move a window. Center of the top of the frame is usually a good choice.


move

public void move(Container comp,
                 int newx,
                 int newy)
Move the given Frame/Dialog to the requested location.


moveBy

public void moveBy(Container comp,
                   int dx,
                   int dy)
Move the given Window by the given amount.


getResizeLocation

protected Point getResizeLocation(Container c)
Return where the mouse usually grabs to resize a window. The lower right corner of the window is usually a good choice.


userMovable

protected boolean userMovable(Component comp)
Return whether it is possible for the user to move the given component.


userResizable

protected boolean userResizable(Component comp)
Return whether it is possible for the user to resize the given component.


resize

public void resize(Container comp,
                   int width,
                   int height)
Resize the given Frame/Dialog to the given size.


resizeBy

public void resizeBy(Container comp,
                     int dx,
                     int dy)
Resize the given Frame/Dialog by the given amounts.


getIconifyLocation

protected Point getIconifyLocation(Container c)
Identify the coordinates of the iconify button where we can, returning (0, 0) if we can't.


getMaximizeLocation

protected Point getMaximizeLocation(Container c)
Identify the coordinates of the maximize button where possible, returning null if not.


iconify

public void iconify(Frame frame)
Iconify the given Frame. Don't support iconification of Dialogs at this point (although maybe should).


deiconify

public void deiconify(Frame frame)

normalize

public void normalize(Frame frame)

maximize

public void maximize(Frame frame)
Make the window full size. On 1.3.1, this is not reversible.


sendEvent

public void sendEvent(AWTEvent event)
Send the given event as appropriate to the event-generation mode.


getEventID

public static String getEventID(AWTEvent event)
Return the symbolic name of the given event's ID.


getCanonicalClass

public static Class getCanonicalClass(Class refClass)

toString

public static String toString(Component comp)
Provides a more concise representation of the component than the default Component.toString().


toString

public static String toString(Object obj)
Provide a string representation of the given component (Component or MenuComponent.


descriptiveClassName

protected static String descriptiveClassName(Class cls)

toHierarchyPath

public static String toHierarchyPath(Component c)
Provides the hierarchic path of the given component by component class, e.g. "JFrame:JRootPane:JPanel:JButton".


toString

public static String toString(AWTEvent event)
Provide a more concise representation of the event than the default AWTEvent.toString().


getEventID

public static int getEventID(Class cls,
                             String id)
Return the numeric event ID corresponding to the given string.


getModifiers

public static int getModifiers(String mods)
Convert the string representation into the actual modifier mask.


getKeyModifiers

public static String getKeyModifiers(int flags)

getMouseModifiers

public static String getMouseModifiers(int flags)

getModifiers

public static String getModifiers(InputEvent event)
Convert the integer modifier flags into a string representation.


getKeyCode

public static String getKeyCode(int keycode)

getKeyCode

public static int getKeyCode(String code)

simpleClassName

public static String simpleClassName(Class cls)
Strip the package from the class name.


isModifier

public static boolean isModifier(int keycode)

keyCodeToMask

public static int keyCodeToMask(int code)

maskToKeyCode

public static int maskToKeyCode(int mask)
Convert the given modifier event mask to the equivalent key code.


postEvent

protected void postEvent(Component comp,
                         AWTEvent ev)
Post the given event to the corresponding event queue for the given component.


wait

public void wait(Condition condition)
Wait for the given Condition to return true. The default timeout may be changed by setting abbot.robot.default_delay.

Throws:
WaitTimedOutError - if the default timeout (30s) is exceeded.

wait

public void wait(Condition condition,
                 long timeout)
Wait for the given Condition to return true, waiting for timeout ms.

Throws:
WaitTimedOutError - if the timeout is exceeded.

wait

public void wait(Condition condition,
                 long timeout,
                 int interval)
Wait for the given Condition to return true, waiting for timeout ms, polling at the given interval.

Throws:
WaitTimedOutError - if the timeout is exceeded.

reset

public void reset()

findFocusOwner

public Component findFocusOwner()
Return the Component which currently owns the focus.


hasHierarchyEventGenerationBug

public static boolean hasHierarchyEventGenerationBug()
Prior to 1.4.1, hierarchy events are only sent if listeners are added to a given component.


hasKeyStrokeGenerationBug

public static boolean hasKeyStrokeGenerationBug()
OSX prior to 1.4 has really crappy key input handling.


hasFrameDeiconifyBug

public static boolean hasFrameDeiconifyBug()

hasMultiClickFrameBug

public static boolean hasMultiClickFrameBug()
Do we get multiple clicks even when the individual clicks are on different frames?


hasRobotMotionBug

public static boolean hasRobotMotionBug()
OS X (as of 1.3.1, v10.1.5), will sometimes send a click to the wrong component after a mouse move. This continues to be an issue in 1.4.1

Linux x86 (1.3.1) has a similar problem, although it manifests it at different times (need a bug test case for this one).

Solaris and HPUX probably share code with the linux VM implementation, so the bug there is probably identical.


canResizeWindows

public static boolean canResizeWindows()
Returns whether it is possible to resize windows that are not an instance of Frame or Dialog. Most X11 window managers will allow this, but stock Macintosh and Windows do not.


canMoveWindows

public static boolean canMoveWindows()
Returns whether it is possible to move windows that are not an instance of Frame or Dialog. Most X11 window managers will allow this, but stock Macintosh and Windows do not.


getPreferredRobotAutoDelay

public static int getPreferredRobotAutoDelay()
Returns the appropriate auto delay for robot-generated events.



Copyright © 2002-2004 Timothy Wall. All Rights Reserved.
Abbot is hosted on

SourceForge