org.fest.swing.core
Interface Robot

All Known Implementing Classes:
BasicRobot

public interface 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.
 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.
 

Method Detail

hierarchy

ComponentHierarchy hierarchy()
Returns the ComponentHierarchy being used by this robot.

Returns:
the ComponentHierarchy being used by this robot.

finder

ComponentFinder finder()
Returns the ComponentFinder being used by this robot.

Returns:
the ComponentFinder being used by this robot.

printer

ComponentPrinter printer()
Returns the BasicComponentPrinter being used by this robot.

Returns:
the ComponentPrinter being used by this robot.

showWindow

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

Parameters:
w - the window to display.

showWindow

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.

Parameters:
w - the window to display.
size - the size of the window to display.

showWindow

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.

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

void close(Window w)
Simulates a user closing the given window.

Parameters:
w - the window to close.

focus

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

Parameters:
c - the component to give focus to.

focusAndWaitForFocusGain

void focusAndWaitForFocusGain(Component c)
Gives input focus to the given Component and waits until the Component has focus.

Parameters:
c - the component to give focus to.

cleanUp

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


cleanUpWithoutDisposingWindows

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 cleanUp(). Using cleanUpWithoutDisposingWindows() may leave many windows open after each test. Use it on very special cases. Please read bug 138 for more details.


click

void click(Component c)
Simulates a user clicking once the given Component using the left mouse button.

Parameters:
c - the Component to click on.
Throws:
ActionFailedException - if the component to click is out of the boundaries of the screen.

rightClick

void rightClick(Component c)
Simulates a user right-clicking the given Component.

Parameters:
c - the Component to click on.
Throws:
ActionFailedException - if the component to click is out of the boundaries of the screen.

click

void click(Component c,
           MouseButton button)
Simulates a user clicking once the given Component using the given mouse button.

Parameters:
c - the Component to click on.
button - the mouse button to use.
Throws:
ActionFailedException - if the component to click is out of the boundaries of the screen.

doubleClick

void doubleClick(Component c)
Simulates a user double-clicking the given Component.

Parameters:
c - the Component to click on.
Throws:
ActionFailedException - if the component to click is out of the boundaries of the screen.

click

void click(Component c,
           MouseButton button,
           int times)
Simulates a user clicking the given mouse button, the given times on the given Component.

Parameters:
c - the Component to click on.
button - the mouse button to click.
times - the number of times to click the given mouse button.
Throws:
ActionFailedException - if the component to click is out of the boundaries of the screen.

click

void click(Component c,
           Point where)
Simulates a user clicking at the given position on the given Component.

Parameters:
c - the Component to click on.
where - the given coordinates, relative to the given Component.
Throws:
ActionFailedException - if the component to click is out of the boundaries of the screen.

click

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.

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.
Throws:
ActionFailedException - if the component to click is out of the boundaries of the screen.

click

void click(Point where,
           MouseButton button,
           int times)
Simulates a user clicking the given mouse button, the given times at the given absolute coordinates.

Parameters:
where - the coordinates where to click.
button - the mouse button to click.
times - the number of times to click the given mouse button.

pressMouse

void pressMouse(MouseButton button)
Simulates a user pressing a mouse button.

Parameters:
button - the mouse button to press.

pressMouse

void pressMouse(Component c,
                Point where)
Simulates a user pressing the left mouse button on the given Component.

Parameters:
c - the Component to click on.
where - the given coordinates, relative to the given Component.

pressMouse

void pressMouse(Component c,
                Point where,
                MouseButton button)
Simulates a user pressing the given mouse button on the given Component.

Parameters:
c - the Component to click on.
where - the given coordinates, relative to the given Component.
button - the mouse button to press.

pressMouse

void pressMouse(Point where,
                MouseButton button)
Simulates a user pressing the given mouse button on the given coordinates.

Parameters:
where - the position where to press the given mouse button.
button - the mouse button to press.
Since:
1.1

moveMouse

void moveMouse(Component c)
Simulates a user moving the mouse pointer to the center of the given Component.

Parameters:
c - the given Component.

moveMouse

void moveMouse(Component c,
               Point p)
Simulates a user moving the mouse pointer to the given coordinates relative to the given Component.

Parameters:
c - the given Component.
p - the given coordinates, relative to the given Component.
Throws:
ActionFailedException - if the given component is not showing and ready for input.

moveMouse

void moveMouse(Component c,
               int x,
               int y)
Simulates a user moving the mouse pointer to the given coordinates relative to the given Component.

Parameters:
c - the given Component.
x - X coordinate, relative to the given Component.
y - Y coordinate, relative to the given Component.
Throws:
ActionFailedException - if the given component is not showing and ready for input.

moveMouse

void moveMouse(Point p)
Simulates a user moving the mouse pointer to the given coordinates.

Parameters:
p - the given coordinates.
Since:
1.1

moveMouse

void moveMouse(int x,
               int y)
Simulates a user moving the mouse pointer to the given coordinates.

Parameters:
x - X coordinate.
y - Y coordinate.
Since:
1.1

releaseMouse

void releaseMouse(MouseButton button)
Releases the given mouse button.

Parameters:
button - the mouse button to release.

releaseMouseButtons

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


rotateMouseWheel

void rotateMouseWheel(Component c,
                      int amount)
Moves the mouse pointer over to the given Component and rotates the scroll wheel on wheel-equipped mice.

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

void rotateMouseWheel(int amount)
Rotates the scroll wheel on wheel-equipped mice.

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

void jitter(Component c)
Makes the mouse pointer show small quick jumpy movements on the given Component.

Parameters:
c - the given Component.

jitter

void jitter(Component c,
            Point where)
Makes the mouse pointer show small quick jumpy movements on the given Component at the given point.

Parameters:
c - the given Component.
where - the given point.

enterText

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.

Parameters:
text - the text to enter.

type

void type(char character)
Types the given character. Note that this method sends the key strokes to the component that has input focus.

Parameters:
character - the character to type.

pressAndReleaseKey

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

Parameters:
keyCode - the code of the key to press.
modifiers - the given modifiers.
Throws:
IllegalArgumentException - if the given code is not a valid key code.

pressAndReleaseKeys

void pressAndReleaseKeys(int... keyCodes)
Simulates a user pressing and releasing the given keys. This method does not affect the current focus.

Parameters:
keyCodes - one or more codes of the keys to press.
Throws:
IllegalArgumentException - if any of the given codes is not a valid key code.
See Also:
KeyEvent

pressKey

void pressKey(int keyCode)
Simulates a user pressing given key. This method does not affect the current focus.

Parameters:
keyCode - the code of the key to press.
Throws:
IllegalArgumentException - if the given code is not a valid key code.
See Also:
KeyEvent

releaseKey

void releaseKey(int keyCode)
Simulates a user releasing the given key. This method does not affect the current focus.

Parameters:
keyCode - the code of the key to release.
Throws:
IllegalArgumentException - if the given code is not a valid key code.
See Also:
KeyEvent

pressModifiers

void pressModifiers(int modifierMask)
Presses the appropriate modifiers corresponding to the given mask. Use mask values from InputEvent.

Parameters:
modifierMask - the given mask.
See Also:
InputEvent

releaseModifiers

void releaseModifiers(int modifierMask)
Releases the appropriate modifiers corresponding to the given mask. Use mask values from InputEvent.

Parameters:
modifierMask - the given mask.
See Also:
InputEvent

waitForIdle

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.

Throws:
IllegalThreadStateException - if this method is called from the event dispatch thread.

isDragging

boolean isDragging()
Indicates whether the robot is currently in a dragging operation.

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

isReadyForInput

boolean isReadyForInput(Component c)
Indicates whether the given Component is ready for input.

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.

showPopupMenu

JPopupMenu showPopupMenu(Component invoker)
Shows a pop-up menu.

Parameters:
invoker - the component to invoke the pop-up menu from.
Returns:
the displayed pop-up menu.
Throws:
ComponentLookupException - if a pop-up menu cannot be found.

showPopupMenu

JPopupMenu showPopupMenu(Component invoker,
                         Point location)
Shows a pop-up menu at the given coordinates.

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.
Throws:
ComponentLookupException - if a pop-up menu cannot be found.

findActivePopupMenu

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

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

requireNoJOptionPaneIsShowing

void requireNoJOptionPaneIsShowing()
Ensures that there is no JOptionPane showing, and potentially blocking GUI tests.

Throws:
AssertionError - if there is one or more JOptionPanes showing on the screen.

settings

Settings settings()
Returns the configuration settings for this Robot.

Returns:
the configuration settings for this Robot.

isActive

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

Returns:
true if this Robot is active, false otherwise.


Copyright © 2007-2011 FEST (Fixtures for Easy Software Testing). All Rights Reserved.