org.netbeans.jemmy
Class EventDispatcher

java.lang.Object
  org.netbeans.jemmy.EventDispatcher

All Implemented Interfaces:

Outputable, Timeoutable

public class EventDispatcher
extends java.lang.Object
implements Outputable, Timeoutable

Provides low level functions for reproducing user actions. One dispatch model uses the managed component's event queue to dispatch events. The other dispatch model uses java.awt.Robot to generate native events. It is an option in the Robot dispatch model to wait for the managed component's event queue to empty before dispatching events. Timeouts used:
EventDispatcher.WaitQueueEmptyTimeout - to wait event queue empty.
EventDispatcher.RobotAutoDelay - param for java.awt.Robot.setAutoDelay method.
EventDispatcher.WaitComponentUnderMouseTimeout - time to wait component under mouse.

Author:

Alexandre Iline (alexandre.iline@sun.com)

See Also:

Timeouts

Field Summary

protected java.awt.Component

component Component to dispatch events to.

Constructor Summary

EventDispatcher(java.awt.Component comp)
Constructor.

Method Summary

void	delayRobot(long time) Delays robot.
void	dispatchEvent(java.awt.AWTEvent event) Dispatches AWTEvent to component passed in constructor.
void	dispatchKeyEvent(int id, int mods, int keyCode) Dispatches KeyEvent.
void	dispatchKeyEvent(int id, int mods, int keyCode, char keyChar) Dispatches KeyEvent.
void	dispatchMouseEvent(int id, int mods, int clickCount, boolean popup) Dispatches MouseEvent at the center of component.
void	dispatchMouseEvent(int id, int mods, int clickCount, int x, int y, boolean popup) Dispatches a MouseEvent.
void	dispatchWindowEvent(int id) Dispatches WindowEvent.
protected int	getAbsoluteX(int x) Bind horizontal relative cursor coordinate to screen coordinate.
protected int	getAbsoluteY(int y) Bind vertical relative cursor coordinate to screen coordinate.
int	getDispatchingModel() Gets the dispatching model value.
java.lang.Object	getExistingField(java.lang.String field_name) Gets component field value through SwingUtilities.invokeAndWait(Runnable).
java.lang.Object	getExistingField(java.lang.String field_name, TestOut out) Gets component field value through SwingUtilities.invokeAndWait(Runnable).
java.lang.Object	getField(java.lang.String field_name) Gets component field value through SwingUtilities.invokeAndWait(Runnable).
static java.lang.String	getKeyDescription(int keyCode) Returns a string representation for a keyboard event.
static java.lang.String	getModifiersString(int modifiers) Get a string representation for key modifiers.
static java.lang.String	getMouseButtonDescription(int button) Returns a mouse button string representation.
TestOut	getOutput() Returns print output streams or writers.
Timeouts	getTimeouts() Return current timeouts.
void	checkComponentUnderMouse(boolean yesOrNo) Wait (or not) for the mouse to move over a Java component before pressing.
java.lang.Object	invokeExistingMethod(java.lang.String method_name, java.lang.Object[] params, java.lang.Class[] params_classes) Invokes component method through SwingUtilities.invokeAndWait(Runnable).
java.lang.Object	invokeExistingMethod(java.lang.String method_name, java.lang.Object[] params, java.lang.Class[] params_classes, TestOut out) Invokes component method through SwingUtilities.invokeAndWait(Runnable).
java.lang.Object	invokeMethod(java.lang.String method_name, java.lang.Object[] params, java.lang.Class[] params_classes) Invokes component method through SwingUtilities.invokeAndWait(Runnable).
void	robotMoveMouse(int x, int y) Moves mouse by robot.
void	robotPressKey(int keyCode) Press key with no modifiers using java.awt.Robot.
void	robotPressKey(int keyCode, int modifiers) Press a key using java.awt.Robot.
void	robotPressMouse(int button) Press mouse button with 0 modifiers.
void	robotPressMouse(int button, int modifiers) Press mouse button by robot.
void	robotReleaseKey(int keyCode) Releases key with 0 modifiers.
void	robotReleaseKey(int keyCode, int modifiers) Releases key by robot.
void	robotReleaseMouse(int button) Releases mouse button with 0 modifiers.
void	robotReleaseMouse(int button, int modifiers) Releases mouse button by robot.
void	setDispatchingModel(int m) Defines dispatching model.
void	setExistingField(java.lang.String field_name, java.lang.Object newValue) Sets component field value through SwingUtilities.invokeAndWait(Runnable).
void	setExistingField(java.lang.String field_name, java.lang.Object newValue, TestOut out) Sets component field value through SwingUtilities.invokeAndWait(Runnable).
void	setField(java.lang.String field_name, java.lang.Object newValue) Sets component field value through SwingUtilities.invokeAndWait(Runnable).
void	setOutput(TestOut out) Defines print output streams or writers.
void	setTimeouts(Timeouts timeouts) Defines current timeouts.
void	waitForIdle() Waits until all events currently on the event queue have been processed.
static void	waitQueueEmpty() Waits for the managed component's java.awt.EventQueue to empty.
static void	waitQueueEmpty(long emptyTime) Waits for the managed component's java.awt.EventQueue to stay empty.
static void	waitQueueEmpty(long emptyTime, TestOut output, Timeouts timeouts) Waits for the managed component's java.awt.EventQueue to stay empty.
static void	waitQueueEmpty(TestOut output, Timeouts timeouts) Waits for the managed component's java.awt.EventQueue to empty.

Methods inherited from class java.lang.Object

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

Field Detail

component

protected java.awt.Component component

Component to dispatch events to.

Constructor Detail

EventDispatcher

public EventDispatcher(java.awt.Component comp)

Constructor.

Parameters:

comp - Component to operate with.

Method Detail

waitQueueEmpty

public static void waitQueueEmpty(TestOut output,
                                  Timeouts timeouts)

Waits for the managed component's java.awt.EventQueue to empty. The timeout for this wait is EventDispatcher.WaitQueueEmptyTimeout.

Parameters:

output - Output to print exception into.

timeouts - A collection of timeout assignments.

Throws:

TimeoutExpiredException

See Also:

QueueTool

waitQueueEmpty

public static void waitQueueEmpty()

Waits for the managed component's java.awt.EventQueue to empty. Uses default output and timeouts. The timeout for this wait is EventDispatcher.WaitQueueEmptyTimeout.

Throws:

TimeoutExpiredException

See Also:

QueueTool

waitQueueEmpty

public static void waitQueueEmpty(long emptyTime,
                                  TestOut output,
                                  Timeouts timeouts)

Waits for the managed component's java.awt.EventQueue to stay empty. The timeout for this wait is EventDispatcher.WaitQueueEmptyTimeout.

Parameters:

emptyTime - The time that the event queue has to stay empty to avoid a TimeoutExpiredException.

output - Output to print exception into

timeouts - A collection of timeout assignments.

Throws:

TimeoutExpiredException

See Also:

QueueTool

waitQueueEmpty

public static void waitQueueEmpty(long emptyTime)

Waits for the managed component's java.awt.EventQueue to stay empty. Uses default output and timeouts. The timeout for this wait is EventDispatcher.WaitQueueEmptyTimeout.

Parameters:

emptyTime - The time that the event queue has to stay empty to avoid a TimeoutExpiredException.

Throws:

TimeoutExpiredException

See Also:

QueueTool

getModifiersString

public static java.lang.String getModifiersString(int modifiers)

Get a string representation for key modifiers. Used to print trace.

Parameters:

modifiers - Bit mask of keyboard event modifiers.

Returns:

a string representation for the keyboard event modifiers.

getKeyDescription

public static java.lang.String getKeyDescription(int keyCode)

Returns a string representation for a keyboard event. Used to print trace.

Parameters:

keyCode - Key code (KeyEvent.VK_* value)

Returns:

the KeyEvent field name.

getMouseButtonDescription

public static java.lang.String getMouseButtonDescription(int button)

Returns a mouse button string representation. Used to print trace.

Parameters:

button - Mouse button (InputEvent.BUTTON1/2/3_MASK value).

Returns:

InputEvent field name.

checkComponentUnderMouse

public void checkComponentUnderMouse(boolean yesOrNo)

Wait (or not) for the mouse to move over a Java component before pressing. This option is relevant when using java.awt.Robot to generate mouse events. If a mouse press occurs at a position not occupied by a known Java component then a NoComponentUnderMouseException will be thrown.

Parameters:

yesOrNo - if true then the test system will wait for the mouse to move over a Java component before pressing. therwise, mouse presses can take place anywhere on the screen.

setOutput

public void setOutput(TestOut out)

Defines print output streams or writers.

Specified by:

setOutput in interface Outputable

Parameters:

out - Identify the streams or writers used for print output.

See Also:

Outputable, TestOut, getOutput()

getOutput

public TestOut getOutput()

Returns print output streams or writers.

Specified by:

getOutput in interface Outputable

Returns:

an object that contains references to objects for printing to output and err streams.

See Also:

Outputable, TestOut, setOutput(org.netbeans.jemmy.TestOut)

setTimeouts

public void setTimeouts(Timeouts timeouts)

Defines current timeouts.

Specified by:

setTimeouts in interface Timeoutable

Parameters:

timeouts - A collection of timeout assignments.

See Also:

Timeoutable, Timeouts, getTimeouts()

getTimeouts

public Timeouts getTimeouts()

Return current timeouts.

Specified by:

getTimeouts in interface Timeoutable

Returns:

the collection of current timeout assignments.

See Also:

Timeoutable, Timeouts, setTimeouts(org.netbeans.jemmy.Timeouts)

setDispatchingModel

public void setDispatchingModel(int m)

Defines dispatching model.

Parameters:

m - New model value.

See Also:

getDispatchingModel(), JemmyProperties.QUEUE_MODEL_MASK, JemmyProperties.ROBOT_MODEL_MASK, JemmyProperties.getCurrentDispatchingModel(), JemmyProperties.setCurrentDispatchingModel(int), JemmyProperties.initDispatchingModel(boolean, boolean), JemmyProperties.initDispatchingModel()

getDispatchingModel

public int getDispatchingModel()

Gets the dispatching model value.

Returns:

the model value.

See Also:

setDispatchingModel(int), JemmyProperties.QUEUE_MODEL_MASK, JemmyProperties.ROBOT_MODEL_MASK, JemmyProperties.getCurrentDispatchingModel(), JemmyProperties.setCurrentDispatchingModel(int), JemmyProperties.initDispatchingModel(boolean, boolean), JemmyProperties.initDispatchingModel()

dispatchEvent

public void dispatchEvent(java.awt.AWTEvent event)

Dispatches AWTEvent to component passed in constructor. If (getDispatchingModel & JemmyProperties.QUEUE_MODEL_MASK) == 0 dispatched event directly, otherwise uses javax.swing.SwingUtilities.invokeAndWait(Runnable)

Parameters:

event - AWTEvent instance to be dispatched.

Throws:

ComponentIsNotVisibleException

ComponentIsNotFocusedException

dispatchMouseEvent

public void dispatchMouseEvent(int id,
                               int mods,
                               int clickCount,
                               int x,
                               int y,
                               boolean popup)

Dispatches a MouseEvent.

Parameters:

id - MouseEvent.MOUSE_* value

mods - InputEvent.MOUSE1/2/3_BUTTON | (modiviers value)

clickCount - Click count

x - Horizontal click point coordinate.

y - vertical click point coordinate.

popup - Difines if mouse event is popup event.

See Also:

dispatchEvent(AWTEvent)

dispatchMouseEvent

public void dispatchMouseEvent(int id,
                               int mods,
                               int clickCount,
                               boolean popup)

Dispatches MouseEvent at the center of component.

Parameters:

id - MouseEvent.MOUSE_* value

mods - InputEvent.MOUSE1/2/3_BUTTON | (modiviers value)

clickCount - Click count

popup - Difines if mouse event is popup event.

See Also:

dispatchEvent(AWTEvent)

dispatchWindowEvent

public void dispatchWindowEvent(int id)

Dispatches WindowEvent.

Parameters:

id - WindowEvent.WINDOW_* value

See Also:

dispatchEvent(AWTEvent)

dispatchKeyEvent

public void dispatchKeyEvent(int id,
                             int mods,
                             int keyCode)

Dispatches KeyEvent.

Parameters:

id - KeyEvent.KEY_PRESSED or KeyEvent.KEY_RELEASED value.

mods - Modifiers.

keyCode - Key code,

See Also:

dispatchEvent(AWTEvent)

dispatchKeyEvent

public void dispatchKeyEvent(int id,
                             int mods,
                             int keyCode,
                             char keyChar)

Dispatches KeyEvent.

Parameters:

id - KeyEvent.KEY_TYPED value.

mods - Modifiers.

keyCode - Key code,

keyChar - Char to be tiped

See Also:

dispatchEvent(AWTEvent)

waitForIdle

public void waitForIdle()

Waits until all events currently on the event queue have been processed.

getAbsoluteX

protected int getAbsoluteX(int x)

Bind horizontal relative cursor coordinate to screen coordinate.

Parameters:

x - Relative coordinate

Returns:

Absolute coordinate

getAbsoluteY

protected int getAbsoluteY(int y)

Bind vertical relative cursor coordinate to screen coordinate.

Parameters:

y - Relative coordinate

Returns:

Absolute coordinate

delayRobot

public void delayRobot(long time)

Delays robot.

Parameters:

time - Time to dalay robot for.

robotMoveMouse

public void robotMoveMouse(int x,
                           int y)

Moves mouse by robot.

Parameters:

x - Component relative horizontal coordinate.

y - Component relative vertical coordinate.

Throws:

ComponentIsNotVisibleException

robotPressMouse

public void robotPressMouse(int button,
                            int modifiers)

Press mouse button by robot.

Parameters:

button - Mouse button (InputEvent.MOUSE1/2/3_BUTTON value)

modifiers - Modifiers

Throws:

ComponentIsNotVisibleException

robotPressMouse

public void robotPressMouse(int button)

Press mouse button with 0 modifiers.

Parameters:

button - Mouse button (InputEvent.MOUSE1/2/3_BUTTON value)

See Also:

robotPressMouse(int, int)

robotReleaseMouse

public void robotReleaseMouse(int button,
                              int modifiers)

Releases mouse button by robot.

Parameters:

button - Mouse button (InputEvent.MOUSE1/2/3_BUTTON value)

modifiers - Modifiers

Throws:

ComponentIsNotVisibleException

robotReleaseMouse

public void robotReleaseMouse(int button)

Releases mouse button with 0 modifiers.

Parameters:

button - Mouse button (InputEvent.MOUSE1/2/3_BUTTON value)

See Also:

robotReleaseMouse(int, int)

robotPressKey

public void robotPressKey(int keyCode,
                          int modifiers)

Press a key using java.awt.Robot.

Parameters:

keyCode - Key (KeyEvent.VK_* value)

modifiers - Mask of KeyEvent modifiers.

Throws:

ComponentIsNotVisibleException

ComponentIsNotFocusedException

robotPressKey

public void robotPressKey(int keyCode)

Press key with no modifiers using java.awt.Robot.

Parameters:

keyCode - Key (KeyEvent.VK_* value)

See Also:

robotPressKey(int, int)

robotReleaseKey

public void robotReleaseKey(int keyCode,
                            int modifiers)

Releases key by robot.

Parameters:

keyCode - Key (KeyEvent.VK_* value)

modifiers - Mask of KeyEvent modifiers.

Throws:

ComponentIsNotVisibleException

ComponentIsNotFocusedException

robotReleaseKey

public void robotReleaseKey(int keyCode)

Releases key with 0 modifiers.

Parameters:

keyCode - Key (KeyEvent.VK_* value)

See Also:

robotPressKey(int, int)

invokeMethod

public java.lang.Object invokeMethod(java.lang.String method_name,
                                     java.lang.Object[] params,
                                     java.lang.Class[] params_classes)
                              throws java.lang.reflect.InvocationTargetException,
                                     java.lang.IllegalStateException,
                                     java.lang.NoSuchMethodException,
                                     java.lang.IllegalAccessException

Invokes component method through SwingUtilities.invokeAndWait(Runnable).

Parameters:

method_name - Name of a method to be invoked

params - Method params

params_classes - Method params' classes

Returns:

an Object - methods result.

Throws:

java.lang.IllegalAccessException

java.lang.NoSuchMethodException

java.lang.IllegalStateException

java.lang.reflect.InvocationTargetException

See Also:

ClassReference

getField

public java.lang.Object getField(java.lang.String field_name)
                          throws java.lang.reflect.InvocationTargetException,
                                 java.lang.IllegalStateException,
                                 java.lang.NoSuchFieldException,
                                 java.lang.IllegalAccessException

Gets component field value through SwingUtilities.invokeAndWait(Runnable).

Parameters:

field_name - Name of a field

Returns:

an Object - field value

Throws:

java.lang.IllegalAccessException

java.lang.IllegalStateException

java.lang.reflect.InvocationTargetException

java.lang.NoSuchFieldException

See Also:

setField(String, Object), ClassReference

setField

public void setField(java.lang.String field_name,
                     java.lang.Object newValue)
              throws java.lang.reflect.InvocationTargetException,
                     java.lang.IllegalStateException,
                     java.lang.NoSuchFieldException,
                     java.lang.IllegalAccessException

Sets component field value through SwingUtilities.invokeAndWait(Runnable).

Parameters:

field_name - Name of a field

newValue - New field value

Throws:

java.lang.IllegalAccessException

java.lang.IllegalStateException

java.lang.reflect.InvocationTargetException

java.lang.NoSuchFieldException

See Also:

getField(String), ClassReference

invokeExistingMethod

public java.lang.Object invokeExistingMethod(java.lang.String method_name,
                                             java.lang.Object[] params,
                                             java.lang.Class[] params_classes,
                                             TestOut out)

Invokes component method through SwingUtilities.invokeAndWait(Runnable). and catch all exceptions.

Parameters:

method_name - Name of a method to be invoked

params - Method params

params_classes - Method params' classes

out - TestOut instance to print exceptions stack trace to.

Returns:

an Object - method result

See Also:

invokeMethod(String, Object[], Class[]), ClassReference

getExistingField

public java.lang.Object getExistingField(java.lang.String field_name,
                                         TestOut out)

Gets component field value through SwingUtilities.invokeAndWait(Runnable). and catch all exceptions.

Parameters:

field_name - Name of a field

out - TestOut instance to print exceptions stack trace to.

Returns:

an Object - fields value

See Also:

getField(String), setExistingField(String, Object, TestOut), ClassReference

setExistingField

public void setExistingField(java.lang.String field_name,
                             java.lang.Object newValue,
                             TestOut out)

Sets component field value through SwingUtilities.invokeAndWait(Runnable). and catch all exceptions.

Parameters:

field_name - Name of a field

newValue - New field value

out - TestOut instance to print exceptions stack trace to.

See Also:

setField(String, Object), getExistingField(String, TestOut), ClassReference

invokeExistingMethod

public java.lang.Object invokeExistingMethod(java.lang.String method_name,
                                             java.lang.Object[] params,
                                             java.lang.Class[] params_classes)

Invokes component method through SwingUtilities.invokeAndWait(Runnable). and catch all exceptions. Exceptions are printed into TestOut object defined by setOutput(TestOut) method.

Parameters:

method_name - Name of a method to be invoked

params - Method params

params_classes - Method params' classes

Returns:

an Object - method result

See Also:

invokeExistingMethod(String, Object[], Class[], TestOut), ClassReference

getExistingField

public java.lang.Object getExistingField(java.lang.String field_name)

Gets component field value through SwingUtilities.invokeAndWait(Runnable). and catch all exceptions. Exceptions are printed into TestOut object defined by setOutput(TestOut) method.

Parameters:

field_name - Name of a field

Returns:

an Object - fields value

See Also:

getExistingField(String, TestOut), setExistingField(String, Object), ClassReference

setExistingField

public void setExistingField(java.lang.String field_name,
                             java.lang.Object newValue)

Sets component field value through SwingUtilities.invokeAndWait(Runnable). and catch all exceptions. Exceptions are printed into TestOut object defined by setOutput(TestOut) method.

Parameters:

field_name - Name of a field

newValue - New field value

See Also:

setExistingField(String, Object, TestOut), getExistingField(String), ClassReference