abbot.util
Class AWTFixtureHelper

java.lang.Object
  abbot.util.AWTFixtureHelper

public class AWTFixtureHelper
extends Object

Provides various facilities for setting up, using, and tearing down a test involving UI components. Handles standardized AWTEvent logging and catching exceptions on the AWT event dispatch thread (EDT). This class should be used at setup and teardown of your chosen fixture.

See Also:

ComponentTestFixture, StepRunner

Field Summary

static int	EVENT_GENERATION_DELAY Typical delay to wait for a robot event to be translated into a Java event.
static int	POPUP_DELAY
static int	WINDOW_DELAY

Constructor Summary

AWTFixtureHelper()

AWTFixtureHelper(Hierarchy hierarchy)
Create an instance of AWTFixtureHelper which makes a snapshot of the current VM state.

Method Summary

void	dispose() Dispose all windows created during this object's lifetime and restore the previous system/UI state, to the extent possible.
protected void	disposeAll()
void	disposeWindow(Window w) Synchronous, safe dispose of a window.
Throwable	getEventDispatchError() Returns the last exception thrown on the event dispatch thread, or null if no such exception has been thrown.
long	getEventDispatchErrorTime() Returns the time of the last exception thrown on the event dispatch thread.
Hierarchy	getHierarchy()
Robot	getRobot()
WindowTracker	getWindowTracker()
void	hideWindow(Window w) Synchronous, safe hide of a window.
void	installPopup(Component invoker, JPopupMenu popup) Install the given popup on the given component.
void	invokeAndWait(Runnable runnable) Convenience for getRobot().invokeAndWait(Runnable).
void	invokeLater(Runnable runnable) Convenience for getRobot().invokeLater(Runnable).
boolean	isShowing(String id) Returns whether a Component is showing.
boolean	isShowing(String id, ComponentFinder finder) Same as isShowing(String), but uses the given ComponentFinder to do the lookup.
void	restore() Restore the state that was preserved when this object was created.
void	setModifiers(int modifiers, boolean pressed) Convenience method to set key modifiers.
Frame	showFrame(Component comp) This method should be invoked to display the component under test.
Frame	showFrame(Component comp, Dimension size) This method should be invoked to display the component under test, when a specific size of frame is desired.
Frame	showFrame(Component comp, Dimension size, String title) This method should be invoked to display the component under test, when a specific size of frame is desired.
Dialog	showModalDialog(Runnable showAction) Display a modal dialog and wait for it to show.
Dialog	showModalDialog(Runnable showAction, ComponentFinder finder) Same as showModalDialog(Runnable), but provides a custom ComponentFinder to find the dialog.
void	showPopup(JPopupMenu popup, Component invoker) Safely install and display a popup in the center of the given component, returning when it is visible.
void	showPopup(JPopupMenu popup, Component invoker, int x, int y) Safely install and display a popup, returning when it is visible.
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	waitForWindow(Window w, boolean visible) Return when the window is ready for input or times out waiting.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

EVENT_GENERATION_DELAY

public static final int EVENT_GENERATION_DELAY

Typical delay to wait for a robot event to be translated into a Java event.

See Also:

Constant Field Values

WINDOW_DELAY

public static final int WINDOW_DELAY

See Also:

Constant Field Values

POPUP_DELAY

public static final int POPUP_DELAY

See Also:

Constant Field Values

Constructor Detail

AWTFixtureHelper

public AWTFixtureHelper()

AWTFixtureHelper

public AWTFixtureHelper(Hierarchy hierarchy)

Create an instance of AWTFixtureHelper which makes a snapshot of the current VM state.

Method Detail

getRobot

public Robot getRobot()

getWindowTracker

public WindowTracker getWindowTracker()

getHierarchy

public Hierarchy getHierarchy()

getEventDispatchError

public Throwable getEventDispatchError()

Returns the last exception thrown on the event dispatch thread, or null if no such exception has been thrown.

getEventDispatchErrorTime

public long getEventDispatchErrorTime()

Returns the time of the last exception thrown on the event dispatch thread.

setModifiers

public void setModifiers(int modifiers,
                         boolean pressed)

Convenience method to set key modifiers. Using this method is preferred to invoking Robot.setModifiers(int,boolean) or Robot.keyPress(int), since this method's effects will be automatically undone at the end of the test. If you use the Robot methods, you must remember to release any keys pressed during the test.

Parameters:

modifiers - mask indicating which modifier keys to use

pressed - whether the modifiers should be in the pressed state.

disposeAll

protected void disposeAll()

restore

public void restore()

Restore the state that was preserved when this object was created.

dispose

public void dispose()

Dispose all windows created during this object's lifetime and restore the previous system/UI state, to the extent possible.

showFrame

public Frame showFrame(Component comp)

This method should be invoked to display the component under test. The frame's size will be its preferred size. This method will return with the enclosing Frame is showing and ready for input.

showFrame

public Frame showFrame(Component comp,
                       Dimension size)

This method should be invoked to display the component under test, when a specific size of frame is desired. The method will return when the enclosing Frame is showing and ready for input.

Parameters:

comp -

size - Desired size of the enclosing frame, or null to make no explicit adjustments to its size.

showFrame

public Frame showFrame(Component comp,
                       Dimension size,
                       String title)

This method should be invoked to display the component under test, when a specific size of frame is desired. The method will return when the enclosing Frame is showing and ready for input.

Parameters:

comp -

size - Desired size of the enclosing frame, or null to make no explicit adjustments to its size.

title - Title of the wrapping frame

showWindow

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.

showWindow

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.

showWindow

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.

waitForWindow

public void waitForWindow(Window w,
                          boolean visible)

Return when the window is ready for input or times out waiting.

Parameters:

w -

hideWindow

public void hideWindow(Window w)

Synchronous, safe hide of a window. The window is ensured to be hidden (ComponentEvent.COMPONENT_HIDDEN or equivalent has been posted) when this method returns. Note that this will not trigger a WindowEvent.WINDOW_CLOSING event; use WindowTester.actionClose(Component) if a window manager window close operation is required.

disposeWindow

public void disposeWindow(Window w)

Synchronous, safe dispose of a window. The window is ensured to be disposed (WindowEvent.WINDOW_CLOSED has been posted) when this method returns.

invokeAndWait

public void invokeAndWait(Runnable runnable)

Convenience for getRobot().invokeAndWait(Runnable).

invokeLater

public void invokeLater(Runnable runnable)

Convenience for getRobot().invokeLater(Runnable).

installPopup

public void installPopup(Component invoker,
                         JPopupMenu popup)

Install the given popup on the given component. Takes care of installing the appropriate mouse handler to activate the popup.

showPopup

public void showPopup(JPopupMenu popup,
                      Component invoker)

Safely install and display a popup in the center of the given component, returning when it is visible. Does not install any mouse handlers not generate any mouse events.

showPopup

public void showPopup(JPopupMenu popup,
                      Component invoker,
                      int x,
                      int y)

Safely install and display a popup, returning when it is visible. Does not install any mouse handlers not generate any mouse events.

showModalDialog

public Dialog showModalDialog(Runnable showAction)
                       throws ComponentSearchException

Display a modal dialog and wait for it to show. Useful for things like JFileChooser.showOpenDialog(java.awt.Component) or JOptionPane.showInputDialog(Object), or any other instance where the dialog contents are not predefined and displaying the dialog involves anything more than show()/setVisible(true (if show()/setVisible(true) is all that is required, use the showWindow(Window) method instead).

The given Runnable should contain the code which will show the modal Dialog (and thus block); it will be run on the event dispatch thread.

This method will return when a Dialog becomes visible which contains the given component (which may be any component which will appear on the Dialog), or the standard timeout (10s) is reached, at which point a RuntimeException will be thrown.

For example,

     final Frame parent = ...;
     Dialog d = showModalDialog(new Runnable) {
         public void run() {
             JOptionPane.showInputDialog(parent, "Hit me");
         }
     });
     

Throws:

ComponentSearchException

See Also:

showWindow(java.awt.Window), showWindow(java.awt.Window,java.awt.Dimension), showWindow(java.awt.Window,java.awt.Dimension,boolean)

showModalDialog

public Dialog showModalDialog(Runnable showAction,
                              ComponentFinder finder)
                       throws ComponentSearchException

Same as showModalDialog(Runnable), but provides a custom ComponentFinder to find the dialog.

Throws:

ComponentSearchException

isShowing

public boolean isShowing(String id)

Returns whether a Component is showing. The ID may be the component name or, in the case of a Frame or Dialog, the title. Regular expressions may be used, but must be delimited by slashes, e.g. /expr/. Returns if one or more matches is found.

isShowing

public boolean isShowing(String id,
                         ComponentFinder finder)

Same as isShowing(String), but uses the given ComponentFinder to do the lookup.