Interface Robot

All Known Implementing Classes:
BasicRobot

public interface Robot
Understands simulation of user events on a GUI Component.
  • Method Details

    • 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:
    • 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:
    • 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:
    • 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:
    • 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:
    • 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.