org.netbeans.jemmy
Class EventDispatcher

java.lang.Object
  extended by org.netbeans.jemmy.EventDispatcher
All Implemented Interfaces:
Outputable, Timeoutable

public class EventDispatcher
extends 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  Component component
          Component to dispatch events to.
 
Constructor Summary
EventDispatcher(Component comp)
          Constructor.
 
Method Summary
 void checkComponentUnderMouse(boolean yesOrNo)
          Wait (or not) for the mouse to move over a Java component before pressing.
 void delayRobot(long time)
          Delays robot.
 void dispatchEvent(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.
 Object getExistingField(String field_name)
          Gets component field value through SwingUtilities.invokeAndWait(Runnable).
 Object getExistingField(String field_name, TestOut out)
          Gets component field value through SwingUtilities.invokeAndWait(Runnable).
 Object getField(String field_name)
          Gets component field value through SwingUtilities.invokeAndWait(Runnable).
static String getKeyDescription(int keyCode)
          Returns a string representation for a keyboard event.
static String getModifiersString(int modifiers)
          Get a string representation for key modifiers.
static String getMouseButtonDescription(int button)
          Returns a mouse button string representation.
 TestOut getOutput()
          Returns print output streams or writers.
 Timeouts getTimeouts()
          Return current timeouts.
 Object invokeExistingMethod(String method_name, Object[] params, Class[] params_classes)
          Invokes component method through SwingUtilities.invokeAndWait(Runnable).
 Object invokeExistingMethod(String method_name, Object[] params, Class[] params_classes, TestOut out)
          Invokes component method through SwingUtilities.invokeAndWait(Runnable).
 Object invokeMethod(String method_name, Object[] params, Class[] params_classes)
          Invokes component method through SwingUtilities.invokeAndWait(Runnable).
static void performInit()
           
 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(String field_name, Object newValue)
          Sets component field value through SwingUtilities.invokeAndWait(Runnable).
 void setExistingField(String field_name, Object newValue, TestOut out)
          Sets component field value through SwingUtilities.invokeAndWait(Runnable).
 void setField(String field_name, 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 Component component
Component to dispatch events to.

Constructor Detail

EventDispatcher

public EventDispatcher(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 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 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 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.

performInit

public static void performInit()

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(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 Object invokeMethod(String method_name,
                           Object[] params,
                           Class[] params_classes)
                    throws InvocationTargetException,
                           IllegalStateException,
                           NoSuchMethodException,
                           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:
IllegalAccessException
NoSuchMethodException
IllegalStateException
InvocationTargetException
See Also:
ClassReference

getField

public Object getField(String field_name)
                throws InvocationTargetException,
                       IllegalStateException,
                       NoSuchFieldException,
                       IllegalAccessException
Gets component field value through SwingUtilities.invokeAndWait(Runnable).

Parameters:
field_name - Name of a field
Returns:
an Object - field value
Throws:
IllegalAccessException
IllegalStateException
InvocationTargetException
NoSuchFieldException
See Also:
setField(String, Object), ClassReference

setField

public void setField(String field_name,
                     Object newValue)
              throws InvocationTargetException,
                     IllegalStateException,
                     NoSuchFieldException,
                     IllegalAccessException
Sets component field value through SwingUtilities.invokeAndWait(Runnable).

Parameters:
field_name - Name of a field
newValue - New field value
Throws:
IllegalAccessException
IllegalStateException
InvocationTargetException
NoSuchFieldException
See Also:
getField(String), ClassReference

invokeExistingMethod

public Object invokeExistingMethod(String method_name,
                                   Object[] params,
                                   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 Object getExistingField(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(String field_name,
                             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 Object invokeExistingMethod(String method_name,
                                   Object[] params,
                                   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 Object getExistingField(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(String field_name,
                             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