org.fest.swing.core
Class BasicRobot

java.lang.Object
  org.fest.swing.core.BasicRobot

All Implemented Interfaces:

Robot

public class BasicRobot
extends Object
implements Robot

Understands simulation of user events on a GUI Component.

Author:

Alex Ruiz, Yvonne Wang

Method Summary

void	cleanUp() Cleans up any used resources (keyboard, mouse, open windows and ScreenLock) used by this robot.
void	cleanUpWithoutDisposingWindows() Cleans up any used resources (keyboard, mouse and ScreenLock) used by this robot.
void	click(Component c) Simulates a user clicking once the given Component using the left mouse button.
void	click(Component c, MouseButton button) Simulates a user clicking once the given Component using the given mouse button.
void	click(Component c, MouseButton button, int times) Simulates a user clicking the given mouse button, the given times on the given Component.
void	click(Component c, Point where) Simulates a user clicking at the given position on the given Component.
void	click(Component c, Point where, MouseButton button, int times) Simulates a user clicking the given mouse button, the given times at the given position on the given Component.
void	click(Point where, MouseButton button, int times) Simulates a user clicking the given mouse button, the given times at the given absolute coordinates.
void	close(Window w) Simulates a user closing the given window.
void	doubleClick(Component c) Simulates a user double-clicking the given Component.
void	enterText(String text) Simulates a user entering the given text.
JPopupMenu	findActivePopupMenu() Returns the currently active pop-up menu, if any.
ComponentFinder	finder() Returns the ComponentFinder being used by this robot.
void	focus(Component c) Gives input focus to the given Component.
void	focusAndWaitForFocusGain(Component c) Gives input focus to the given Component and waits until the Component has focus.
ComponentHierarchy	hierarchy() Returns the ComponentHierarchy being used by this robot.
boolean	isActive() Indicates whether this Robot is active.
boolean	isDragging() Indicates whether the robot is currently in a dragging operation.
boolean	isReadyForInput(Component c) Indicates whether the given Component is ready for input.
void	jitter(Component c) Makes the mouse pointer show small quick jumpy movements on the given Component.
void	jitter(Component c, Point where) Makes the mouse pointer show small quick jumpy movements on the given Component at the given point.
void	moveMouse(Component c) Simulates a user moving the mouse pointer to the center of the given Component.
void	moveMouse(Component c, int x, int y) Simulates a user moving the mouse pointer to the given coordinates relative to the given Component.
void	moveMouse(Component c, Point p) Simulates a user moving the mouse pointer to the given coordinates relative to the given Component.
void	moveMouse(int x, int y) Simulates a user moving the mouse pointer to the given coordinates.
void	moveMouse(Point p) Simulates a user moving the mouse pointer to the given coordinates.
void	pressAndReleaseKey(int keyCode, int... modifiers) Type the given key code with the given modifiers.
void	pressAndReleaseKeys(int... keyCodes) Simulates a user pressing and releasing the given keys.
void	pressKey(int keyCode) Simulates a user pressing given key.
void	pressModifiers(int modifierMask) Presses the appropriate modifiers corresponding to the given mask.
void	pressMouse(Component c, Point where) Simulates a user pressing the left mouse button on the given Component.
void	pressMouse(Component c, Point where, MouseButton button) Simulates a user pressing the given mouse button on the given Component.
void	pressMouse(MouseButton button) Simulates a user pressing a mouse button.
void	pressMouse(Point where, MouseButton button) Simulates a user pressing the given mouse button on the given coordinates.
ComponentPrinter	printer() Returns the BasicComponentPrinter being used by this robot.
void	releaseKey(int keyCode) Simulates a user releasing the given key.
void	releaseModifiers(int modifierMask) Releases the appropriate modifiers corresponding to the given mask.
void	releaseMouse(MouseButton button) Releases the given mouse button.
void	releaseMouseButtons() Releases any mouse button(s) used by the robot.
void	requireNoJOptionPaneIsShowing() Ensures that there is no JOptionPane showing, and potentially blocking GUI tests.
void	rightClick(Component c) Simulates a user right-clicking the given Component.
static Robot	robotWithCurrentAwtHierarchy() Creates a new Robot that has access to all the GUI components in the AWT hierarchy.
static Robot	robotWithNewAwtHierarchy() Creates a new Robot with a new AWT hierarchy.
void	rotateMouseWheel(Component c, int amount) Moves the mouse pointer over to the given Component and rotates the scroll wheel on wheel-equipped mice.
void	rotateMouseWheel(int amount) Rotates the scroll wheel on wheel-equipped mice.
Settings	settings() Returns the configuration settings for this Robot.
JPopupMenu	showPopupMenu(Component invoker) Shows a pop-up menu.
JPopupMenu	showPopupMenu(Component invoker, Point location) Shows a pop-up menu at the given coordinates.
void	showWindow(Window w) Safely display a window with proper EDT synchronization.
void	showWindow(Window w, Dimension size) Safely display a window with proper EDT synchronization.
void	showWindow(Window w, Dimension size, boolean pack) Safely display a window with proper EDT synchronization.
void	type(char character) Types the given character.
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

Method Detail

robotWithNewAwtHierarchy

public static Robot robotWithNewAwtHierarchy()

Creates a new Robot with a new AWT hierarchy. The created Robot will not be able to access any components that were created before it.

Returns:

the created Robot.

robotWithCurrentAwtHierarchy

public static Robot robotWithCurrentAwtHierarchy()

Creates a new Robot that has access to all the GUI components in the AWT hierarchy.

Returns:

the created Robot.

printer

public ComponentPrinter printer()

Returns the BasicComponentPrinter being used by this robot.

Specified by:

printer in interface Robot

Returns:

the ComponentPrinter being used by this robot.

finder

public ComponentFinder finder()

Returns the ComponentFinder being used by this robot.

Specified by:

finder in interface Robot

Returns:

the ComponentFinder being used by this robot.

showWindow

@RunsInEDT
public void showWindow(Window w)

Safely display a window with proper EDT synchronization. This method blocks until the Window is showing and ready for input.

Specified by:

showWindow in interface Robot

Parameters:

w - the window to display.

showWindow

@RunsInEDT
public void showWindow(Window w,
                                 Dimension size)

Safely display a window with proper EDT synchronization. This method blocks until the Window is showing and ready for input.

Specified by:

showWindow in interface Robot

Parameters:

w - the window to display.

size - the size of the window to display.

showWindow

@RunsInEDT
public void showWindow(Window w,
                                 Dimension size,
                                 boolean pack)

Safely display a window with proper EDT synchronization. This method blocks until the window is showing. This method will return even when the window is a modal dialog, since the show method is called on the event dispatch thread. The window will be packed if the pack flag is set, and set to the given size if it is non-null.

Modal dialogs may be shown with this method without blocking.

Specified by:

showWindow in interface Robot

Parameters:

w - the window to display.

size - the size of the window to display.

pack - flag that indicates if the window should be packed or not. By packed we mean calling w.pack().

close

@RunsInEDT
public void close(Window w)

Simulates a user closing the given window.

Specified by:

close in interface Robot

Parameters:

w - the window to close.

focusAndWaitForFocusGain

@RunsInEDT
public void focusAndWaitForFocusGain(Component c)

Gives input focus to the given Component and waits until the Component has focus.

Specified by:

focusAndWaitForFocusGain in interface Robot

Parameters:

c - the component to give focus to.

focus

@RunsInEDT
public void focus(Component c)

Gives input focus to the given Component. Note that the component may not yet have focus when this method returns.

Specified by:

focus in interface Robot

Parameters:

c - the component to give focus to.

cleanUp

@RunsInEDT
public void cleanUp()

Cleans up any used resources (keyboard, mouse, open windows and ScreenLock) used by this robot.

Specified by:

cleanUp in interface Robot

cleanUpWithoutDisposingWindows

@RunsInEDT
public void cleanUpWithoutDisposingWindows()

Cleans up any used resources (keyboard, mouse and ScreenLock) used by this robot. This method does not dispose any open windows.

Note: The preferred method to use to clean up resources is Robot.cleanUp(). Using Robot.cleanUpWithoutDisposingWindows() may leave many windows open after each test. Use it on very special cases. Please read bug 138 for more details.

Specified by:

cleanUpWithoutDisposingWindows in interface Robot

click

@RunsInEDT
public void click(Component c)

Simulates a user clicking once the given Component using the left mouse button.

Specified by:

click in interface Robot

Parameters:

c - the Component to click on.

rightClick

@RunsInEDT
public void rightClick(Component c)

Simulates a user right-clicking the given Component.

Specified by:

rightClick in interface Robot

Parameters:

c - the Component to click on.

click

@RunsInEDT
public void click(Component c,
                            MouseButton button)

Simulates a user clicking once the given Component using the given mouse button.

Specified by:

click in interface Robot

Parameters:

c - the Component to click on.

button - the mouse button to use.

doubleClick

@RunsInEDT
public void doubleClick(Component c)

Simulates a user double-clicking the given Component.

Specified by:

doubleClick in interface Robot

Parameters:

c - the Component to click on.

click

@RunsInEDT
public void click(Component c,
                            MouseButton button,
                            int times)

Simulates a user clicking the given mouse button, the given times on the given Component.

Specified by:

click in interface Robot

Parameters:

c - the Component to click on.

button - the mouse button to click.

times - the number of times to click the given mouse button.

click

@RunsInEDT
public void click(Component c,
                            Point where)

Simulates a user clicking at the given position on the given Component.

Specified by:

click in interface Robot

Parameters:

c - the Component to click on.

where - the given coordinates, relative to the given Component.

click

@RunsInEDT
public void click(Point where,
                            MouseButton button,
                            int times)

Simulates a user clicking the given mouse button, the given times at the given absolute coordinates.

Specified by:

click in interface Robot

Parameters:

where - the coordinates where to click.

button - the mouse button to click.

times - the number of times to click the given mouse button.

click

@RunsInEDT
public void click(Component c,
                            Point where,
                            MouseButton button,
                            int times)

Simulates a user clicking the given mouse button, the given times at the given position on the given Component.

Specified by:

click in interface Robot

Parameters:

c - the Component to click on.

where - the given coordinates, relative to the given Component.

button - the mouse button to click.

times - the number of times to click the given mouse button.

pressModifiers

public void pressModifiers(int modifierMask)

Presses the appropriate modifiers corresponding to the given mask. Use mask values from InputEvent.

Specified by:

pressModifiers in interface Robot

Parameters:

modifierMask - the given mask.

See Also:

InputEvent

releaseModifiers

public void releaseModifiers(int modifierMask)

Releases the appropriate modifiers corresponding to the given mask. Use mask values from InputEvent.

Specified by:

releaseModifiers in interface Robot

Parameters:

modifierMask - the given mask.

See Also:

InputEvent

moveMouse

@RunsInEDT
public void moveMouse(Component c)

Simulates a user moving the mouse pointer to the center of the given Component.

Specified by:

moveMouse in interface Robot

Parameters:

c - the given Component.

moveMouse

@RunsInEDT
public void moveMouse(Component c,
                                Point p)

Simulates a user moving the mouse pointer to the given coordinates relative to the given Component.

Specified by:

moveMouse in interface Robot

Parameters:

c - the given Component.

p - the given coordinates, relative to the given Component.

moveMouse

@RunsInEDT
public void moveMouse(Component c,
                                int x,
                                int y)

Simulates a user moving the mouse pointer to the given coordinates relative to the given Component.

Specified by:

moveMouse in interface Robot

Parameters:

c - the given Component.

x - X coordinate, relative to the given Component.

y - Y coordinate, relative to the given Component.

moveMouse

public void moveMouse(Point p)

Simulates a user moving the mouse pointer to the given coordinates.

Specified by:

moveMouse in interface Robot

Parameters:

p - the given coordinates.

moveMouse

public void moveMouse(int x,
                      int y)

Simulates a user moving the mouse pointer to the given coordinates.

Specified by:

moveMouse in interface Robot

Parameters:

x - X coordinate.

y - Y coordinate.

pressMouse

public void pressMouse(MouseButton button)

Simulates a user pressing a mouse button.

Specified by:

pressMouse in interface Robot

Parameters:

button - the mouse button to press.

pressMouse

public void pressMouse(Component c,
                       Point where)

Simulates a user pressing the left mouse button on the given Component.

Specified by:

pressMouse in interface Robot

Parameters:

c - the Component to click on.

where - the given coordinates, relative to the given Component.

pressMouse

public void pressMouse(Component c,
                       Point where,
                       MouseButton button)

Simulates a user pressing the given mouse button on the given Component.

Specified by:

pressMouse in interface Robot

Parameters:

c - the Component to click on.

where - the given coordinates, relative to the given Component.

button - the mouse button to press.

pressMouse

public void pressMouse(Point where,
                       MouseButton button)

Simulates a user pressing the given mouse button on the given coordinates.

Specified by:

pressMouse in interface Robot

Parameters:

where - the position where to press the given mouse button.

button - the mouse button to press.

releaseMouse

@RunsInEDT
public void releaseMouse(MouseButton button)

Releases the given mouse button.

Specified by:

releaseMouse in interface Robot

Parameters:

button - the mouse button to release.

releaseMouseButtons

@RunsInEDT
public void releaseMouseButtons()

Releases any mouse button(s) used by the robot.

Specified by:

releaseMouseButtons in interface Robot

rotateMouseWheel

public void rotateMouseWheel(Component c,
                             int amount)

Moves the mouse pointer over to the given Component and rotates the scroll wheel on wheel-equipped mice.

Specified by:

rotateMouseWheel in interface Robot

Parameters:

c - the given Component.

amount - number of "notches" to move the mouse wheel. Negative values indicate movement up/away from the user, while positive values indicate movement down/towards the user.

rotateMouseWheel

public void rotateMouseWheel(int amount)

Rotates the scroll wheel on wheel-equipped mice.

Specified by:

rotateMouseWheel in interface Robot

Parameters:

amount - number of "notches" to move the mouse wheel. Negative values indicate movement up/away from the user, while positive values indicate movement down/towards the user.

jitter

@RunsInEDT
public void jitter(Component c)

Makes the mouse pointer show small quick jumpy movements on the given Component.

Specified by:

jitter in interface Robot

Parameters:

c - the given Component.

jitter

@RunsInEDT
public void jitter(Component c,
                             Point where)

Makes the mouse pointer show small quick jumpy movements on the given Component at the given point.

Specified by:

jitter in interface Robot

Parameters:

c - the given Component.

where - the given point.

enterText

@RunsInEDT
public void enterText(String text)

Simulates a user entering the given text. Note that this method the key strokes to the component that has input focus.

Specified by:

enterText in interface Robot

Parameters:

text - the text to enter.

type

@RunsInEDT
public void type(char character)

Types the given character. Note that this method sends the key strokes to the component that has input focus.

Specified by:

type in interface Robot

Parameters:

character - the character to type.

pressAndReleaseKey

@RunsInEDT
public void pressAndReleaseKey(int keyCode,
                                         int... modifiers)

Type the given key code with the given modifiers. Modifiers is a mask from the available InputEvent masks.

Specified by:

pressAndReleaseKey in interface Robot

Parameters:

keyCode - the code of the key to press.

modifiers - the given modifiers.

pressAndReleaseKeys

@RunsInEDT
public void pressAndReleaseKeys(int... keyCodes)

Simulates a user pressing and releasing the given keys. This method does not affect the current focus.

Specified by:

pressAndReleaseKeys in interface Robot

Parameters:

keyCodes - one or more codes of the keys to press.

See Also:

KeyEvent

pressKey

@RunsInEDT
public void pressKey(int keyCode)

Simulates a user pressing given key. This method does not affect the current focus.

Specified by:

pressKey in interface Robot

Parameters:

keyCode - the code of the key to press.

See Also:

KeyEvent

releaseKey

@RunsInEDT
public void releaseKey(int keyCode)

Simulates a user releasing the given key. This method does not affect the current focus.

Specified by:

releaseKey in interface Robot

Parameters:

keyCode - the code of the key to release.

See Also:

KeyEvent

waitForIdle

@RunsInEDT
public void waitForIdle()

Wait for an idle AWT event queue. Note that this is different from the implementation of java.awt.Robot.waitForIdle(), 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.

Specified by:

waitForIdle in interface Robot

isDragging

public boolean isDragging()

Indicates whether the robot is currently in a dragging operation.

Specified by:

isDragging in interface Robot

Returns:

true if the robot is currently in a dragging operation, false otherwise.

showPopupMenu

@RunsInEDT
public JPopupMenu showPopupMenu(Component invoker)

Shows a pop-up menu.

Specified by:

showPopupMenu in interface Robot

Parameters:

invoker - the component to invoke the pop-up menu from.

Returns:

the displayed pop-up menu.

showPopupMenu

@RunsInEDT
public JPopupMenu showPopupMenu(Component invoker,
                                          Point location)

Shows a pop-up menu at the given coordinates.

Specified by:

showPopupMenu in interface Robot

Parameters:

invoker - the component to invoke the pop-up menu from.

location - the given coordinates for the pop-up menu.

Returns:

the displayed pop-up menu.

isReadyForInput

@RunsInCurrentThread
public boolean isReadyForInput(Component c)

Indicates whether the given Component is ready for input.

Note: This method is not guaranteed to be executed in the event dispatch thread (EDT.) Clients are responsible for calling this method from the EDT.

Specified by:

isReadyForInput in interface Robot

Parameters:

c - the given Component.

Returns:

true if the given Component is ready for input, false otherwise.

Throws:

ActionFailedException - if the given Component does not have a Window ancestor.

findActivePopupMenu

@RunsInEDT
public JPopupMenu findActivePopupMenu()

Returns the currently active pop-up menu, if any. If no pop-up is currently showing, returns null.

Specified by:

findActivePopupMenu in interface Robot

Returns:

the currently active pop-up menu or null, if no pop-up is currently showing.

requireNoJOptionPaneIsShowing

@RunsInEDT
public void requireNoJOptionPaneIsShowing()

Ensures that there is no JOptionPane showing, and potentially blocking GUI tests.

Specified by:

requireNoJOptionPaneIsShowing in interface Robot

settings

public Settings settings()

Returns the configuration settings for this Robot.

Specified by:

settings in interface Robot

Returns:

the configuration settings for this Robot.

hierarchy

public ComponentHierarchy hierarchy()

Returns the ComponentHierarchy being used by this robot.

Specified by:

hierarchy in interface Robot

Returns:

the ComponentHierarchy being used by this robot.

isActive

public boolean isActive()

Indicates whether this Robot is active. Being "active" means that Robot.cleanUp() has not been called yet.

Specified by:

isActive in interface Robot

Returns:

true if this Robot is active, false otherwise.