IBM Rational Functional Tester
Version 6.1
IBM Rational Functional Tester API Reference

Project Version 2.0

com.rational.test.ft.object.interfaces
Class GuiTestObject

java.lang.Object
  extended bycom.rational.test.ft.object.interfaces.TestObject
      extended bycom.rational.test.ft.object.interfaces.GuiTestObject
All Implemented Interfaces:
IGraphical
Direct Known Subclasses:
EmbeddedBrowserTestObject, FrameTestObject, ScrollTestObject, SiebTestObject, StatelessGuiSubitemTestObject, SubitemTestObject, TextGuiTestObject, ToggleTestObject

public class GuiTestObject
extends TestObject
implements IGraphical

The core class for modeling GUI components. All GUI objects must extend this class.

Since:
RFT1.0

Constructor Summary
GuiTestObject(com.rational.test.ft.object.map.SpyMappedTestObject mappedObject)
          For internal use.
GuiTestObject(com.rational.test.ft.object.map.SpyMappedTestObject mappedObject, TestObject anchor)
          For internal use.
GuiTestObject(com.rational.test.ft.object.map.SpyMappedTestObject mappedObject, TestObject anchor, long scriptCommandFlags)
          For internal use.
GuiTestObject(TestObject obj)
          Constructs one GuiTestObject from another TestObject.
GuiTestObject(com.rational.test.ft.object.TestObjectReference ref)
          For internal use.
 
Method Summary
 void click()
          Performs a left-mouse click on the center point of the associated TestObject.
 void click(MouseModifiers modifiers)
          Performs a left-mouse click on the specified object, relative to the coordinates within the associated TestObject.
 void click(MouseModifiers modifiers, java.awt.Point pt)
          Performs a left-mouse click on the specified coordinates, relative to the associated TestObject.
 void click(java.awt.Point pt)
          Performs a left-mouse click on the specified coordinates, relative to the associated TestObject.
 void clickRadio(Subitem childProperties)
          Locate a radiobutton child with the supplied properties and click on it.
 void doubleClick()
          Performs a left-mouse double-click on the center point of the associated TestOject.
 void doubleClick(MouseModifiers modifiers)
          Performs a left-mouse double-click at the specified object, relative to the coordinates within the associated TestObject.
 void doubleClick(MouseModifiers modifiers, java.awt.Point pt)
          Performs a mouse double-click on the specified coordinates, relative to the associated TestObject.
 void doubleClick(java.awt.Point pt)
          Performs a left-mouse double-click on the specified coordinates, relative to the associated TestObject.
 void drag()
          Performs a MOUSE_LEFT drag action on the associated TestObject.
 void drag(MouseModifiers modifiers)
          Performs a drag action on the associated TestObject with the supplied set of mouse modifiers.
 void drag(MouseModifiers modifiers, java.awt.Point pt1, java.awt.Point pt2)
          Performs a drag action on the associated TestObject.
 void drag(java.awt.Point pt1, java.awt.Point pt2)
          Performs a MOUSE_LEFT drag action on the associated TestObject.
 void dragToScreenPoint(MouseModifiers modifiers, java.awt.Point objectPt, java.awt.Point screenPt)
          Performs a drag action against the associated TestObject.
 void dragToScreenPoint(java.awt.Point screenPt)
          Performs a MOUSE_LEFT drag action on the associated TestObject.
 void dragToScreenPoint(java.awt.Point objectPt, java.awt.Point screenPt)
          Performs a MOUSE_LEFT drag action against the associated TestObject.
 java.lang.Object getChildAtPoint(java.awt.Point pt)
          Finds the child object that is at the specified point.
 java.awt.Rectangle getClippedScreenRectangle()
          Returns the clipped-screen rectangle for the associated TestObject, relative to the top-left corner of the screen.
 java.awt.Point getScreenPoint()
          Returns the screen-relative point to a valid point within the object.
 java.awt.Point getScreenPoint(java.awt.Point pt)
          Returns the screen-relative point, given an object-relative point.
 java.awt.Rectangle getScreenRectangle()
          Returns the rectangle that contains the component being evaluated, relative to the top-left corner of the screen.
 java.awt.image.BufferedImage getScreenSnapshot()
          Takes a snapshot (screen capture) of the visible GuiTestObject
 boolean hasFocus()
          Determines whether a component has keyboard focus.
 void hover()
          Hovers the mouse over the center of the associated TestObject.
 void hover(double secondDelay)
          Hovers the mouse over the center of the associated TestObject.
 void hover(double secondDelay, java.awt.Point pt)
          Hovers the mouse over the specified coordinates of the associated TestObject.
 void hover(java.awt.Point pt)
          Hovers the mouse over the specified coordinates of the associated TestObject.
protected  java.lang.Object invokeProxyWithGuiDelay(java.lang.String method)
          Invokes a method on the proxy for an object in the software under test.
protected  java.lang.Object invokeProxyWithGuiDelay(java.lang.String method, java.lang.String methodSignature, java.lang.Object[] args)
          Invokes a method on the proxy for an object in the software under test.
 boolean isEnabled()
          Determines whether a component is enabled.
 boolean isOpaque()
          Determines whether a component is opaque.
 boolean isPointInObject(java.awt.Point pt)
          Determines whether the specified screen-relative point is contained in the component under evaluation.
 boolean isShowing()
          Determines whether a component is showing.
 void mouseMove(MouseModifiers modifiers, java.awt.Point pt)
          Performs a move action against the associated TestObject.
 void mouseMove(java.awt.Point pt)
          Performs a MOUSE_LEFT move action on the associated TestObject.
 void nClick(int clickCount, MouseModifiers modifiers, java.awt.Point pt)
          Performs a mouse n-click action on the specified coordinates, relative to the associated TestObject.
 void nClickDrag(int clickCount, MouseModifiers modifiers, java.awt.Point pt1, java.awt.Point pt2)
          Performs a mouse n-click drag action on the specified coordinates, relative to the associated TestObject.
 void nClickDragToScreenPoint(int clickCount, MouseModifiers modifiers, java.awt.Point objectPt, java.awt.Point screenPt)
          Performs a mouse n-click drag action on the specified coordinates, relative to the associated TestObject.
 
Methods inherited from class com.rational.test.ft.object.interfaces.TestObject
equals, exists, find, find, find, findAndInvoke, findAndInvoke, findAndInvokeProxy, getChildren, getDescribedObject, getDescribedObjects, getDomain, getField, getIndexer, getIndexer, getIndexers, getMappableChildren, getMappableParent, getMethods, getNameInScript, getNonValueProperties, getObjectClassName, getObjectReference, getOwnedObjects, getOwner, getParent, getProcess, getProperties, getProperty, getPropertyFromMap, getRecognitionProperties, getRecognitionPropertyWeight, getScriptCommandFlags, getStandardProperties, getTestData, getTestDataTypes, getTopMappableParent, getTopParent, invoke, invoke, invokeProxy, invokeProxy, isMappedObject, isSameObject, setIndexer, setIndexer, setProperty, toString, unregister, updateTestData, waitForExistence, waitForExistence
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

GuiTestObject

public GuiTestObject(com.rational.test.ft.object.map.SpyMappedTestObject mappedObject)
For internal use.

Since:
RFT1.0

GuiTestObject

public GuiTestObject(com.rational.test.ft.object.map.SpyMappedTestObject mappedObject,
                     TestObject anchor)
For internal use.

Since:
RFT1.0

GuiTestObject

public GuiTestObject(com.rational.test.ft.object.map.SpyMappedTestObject mappedObject,
                     TestObject anchor,
                     long scriptCommandFlags)
For internal use.

Since:
RFT1.0

GuiTestObject

public GuiTestObject(com.rational.test.ft.object.TestObjectReference ref)
For internal use.

Since:
RFT1.0

GuiTestObject

public GuiTestObject(TestObject obj)
Constructs one GuiTestObject from another TestObject. Both are references to the same object.

Since:
RFT1.0
Method Detail

isShowing

public boolean isShowing()
Determines whether a component is showing.

Specified by:
isShowing in interface IGraphical
Returns:
true if the component is showing; false otherwise.
Since:
RFT1.0

isEnabled

public boolean isEnabled()
Determines whether a component is enabled.

Specified by:
isEnabled in interface IGraphical
Returns:
true if the component is enabled; false otherwise.
Since:
RFT1.0

isOpaque

public boolean isOpaque()
Determines whether a component is opaque.

Specified by:
isOpaque in interface IGraphical
Returns:
true if the component is opaque; false otherwise.
Since:
RFT1.0

getChildAtPoint

public java.lang.Object getChildAtPoint(java.awt.Point pt)
Finds the child object that is at the specified point. Note that the point is relative to the top-left corner of the screen and not to the component itself, or its parent.

Specified by:
getChildAtPoint in interface IGraphical
Parameters:
pt - the x,y coordinates of the specified point
Returns:
The object at the point, or null if no child object is found.
Since:
RFT1.0
See Also:
getScreenRectangle()

hasFocus

public boolean hasFocus()
Determines whether a component has keyboard focus.

Specified by:
hasFocus in interface IGraphical
Returns:
true if component has keyboard focus; false otherwise.
Since:
RFT1.0

isPointInObject

public boolean isPointInObject(java.awt.Point pt)
Determines whether the specified screen-relative point is contained in the component under evaluation. Note that the point is relative to the top-left corner of the screen and not to the component itself, or its parent.

This functionality is performed by the proxy because of the potentially unusual aspects associated with this functionality. Although getScreenRectangle is typically used to resolve this query, there are situations for which this is not accurate. For example, if the clickable region on a button is not rectangular, checking only whether the point is in the rectangle would yield an invalid result.

Specified by:
isPointInObject in interface IGraphical
Parameters:
pt - the x,y coordinates of the specified point
Returns:
true if the component contains the point; false otherwise.
Since:
RFT1.0
See Also:
getScreenRectangle()

getScreenRectangle

public java.awt.Rectangle getScreenRectangle()
Returns the rectangle that contains the component being evaluated, relative to the top-left corner of the screen. This commonly consists of a combination of the following two operations:
The rectangle is exposed so that actions can be directly scripted against a visible GUI object.

Specified by:
getScreenRectangle in interface IGraphical
Returns:
The adjusted rectangle surrounding the component, relative to the screen, or null if the GUI object does not appear.
Since:
RFT1.0
See Also:
isPointInObject(java.awt.Point)

getClippedScreenRectangle

public java.awt.Rectangle getClippedScreenRectangle()
Description copied from interface: IGraphical
Returns the clipped-screen rectangle for the associated TestObject, relative to the top-left corner of the screen. While IGraphical.getScreenRectangle() returns the true rectangle of the TestObject, this method clips the true screen rectangle to the bounds of any clipping parent TestObject. Clipping parents, such as scroll panes or a browser window, may hide part or all of the true screen rectangle. Only the screen-level viewable rectangle is returned, or null if the object is not showing, or is completely clipped by a clipping parent.

Specified by:
getClippedScreenRectangle in interface IGraphical
Returns:
The clipped screen rectangle, or null if the object cannot be seen in any window on the screen.
See Also:
IGraphical.getScreenRectangle()

getScreenPoint

public java.awt.Point getScreenPoint()
Returns the screen-relative point to a valid point within the object.

Specified by:
getScreenPoint in interface IGraphical
Since:
RFT1.0

getScreenPoint

public java.awt.Point getScreenPoint(java.awt.Point pt)
Returns the screen-relative point, given an object-relative point.

Specified by:
getScreenPoint in interface IGraphical
Parameters:
pt - the x,y coordinates of the object-relative point
Since:
RFT1.0

invokeProxyWithGuiDelay

protected java.lang.Object invokeProxyWithGuiDelay(java.lang.String method,
                                                   java.lang.String methodSignature,
                                                   java.lang.Object[] args)
Invokes a method on the proxy for an object in the software under test. This version also waits according to the standard delayBeforeGuiAction. Note that invokeProxyWithGuiDelay can directly modify the object in the software under test. Whenever possible, avoid using this method, because it enables you to modify the software under test in ways that a typical user cannot. If you use it, be sure to discuss its use with the developers of the software that you are testing.

If the returned object is not a value class, invoke registers the object and returns a reference to the object in the software under test. Registered object references are released by calling one of the unregister methods.

Parameters:
method - the name of the method to be called
methodSignature - the signature of the method to be called (using standard JNI syntax)
args - the arguments to be passed to the method
Returns:
An object in the software under test
Since:
RFT1.0
See Also:
TestObject.unregister(), RationalTestScript.unregisterAll(), RationalTestScript.unregister(Object[]), RationalTestScript.getRegisteredTestObjects()

invokeProxyWithGuiDelay

protected java.lang.Object invokeProxyWithGuiDelay(java.lang.String method)
Invokes a method on the proxy for an object in the software under test. This version also waits according to the standard delayBeforeGuiAction. Note that invokeProxyWithGuiDelay can directly modify the object in the software under test. Whenever possible, avoid using this method, because it enables you to modify the software under test in ways that a typical user cannot. If you use it, be sure to discuss its use with the developers of the software that you are testing.

If the returned object is not a value class, invoke registers the object and returns a reference to the object in the software under test. Registered object references are released by calling one of the unregister methods.

Parameters:
method - the name of the method to be called
Returns:
An object in the software under test
Since:
RFT1.0
See Also:
TestObject.unregister(), RationalTestScript.unregisterAll(), RationalTestScript.unregister(Object[]), RationalTestScript.getRegisteredTestObjects()

click

public void click()
Performs a left-mouse click on the center point of the associated TestObject. This method is a shortcut to the click method with a modifier parameter. (The modifier is set to MOUSE_LEFT.)

Specified by:
click in interface IGraphical
Since:
RFT1.0

click

public void click(MouseModifiers modifiers)
Performs a left-mouse click on the specified object, relative to the coordinates within the associated TestObject.

Specified by:
click in interface IGraphical
Since:
RFT1.0

click

public void click(java.awt.Point pt)
Performs a left-mouse click on the specified coordinates, relative to the associated TestObject. This method is a shortcut to the click method with a modifier parameter and coordinates. (The modifier is set to MOUSE_LEFT.)

Specified by:
click in interface IGraphical
Parameters:
pt - the x,y coordinates where the left-mouse click is performed
Since:
RFT1.0

click

public void click(MouseModifiers modifiers,
                  java.awt.Point pt)
Performs a left-mouse click on the specified coordinates, relative to the associated TestObject.

Specified by:
click in interface IGraphical
Parameters:
modifiers -
pt - the x,y coordinates where the left-mouse click is performed
Since:
RFT1.0

doubleClick

public void doubleClick()
Performs a left-mouse double-click on the center point of the associated TestOject. This method is a shortcut to the double-click method with a modifier parameter. (The modifier is set to MOUSE_LEFT.)

Specified by:
doubleClick in interface IGraphical
Since:
RFT1.0

doubleClick

public void doubleClick(MouseModifiers modifiers)
Performs a left-mouse double-click at the specified object, relative to the coordinates within the associated TestObject.

Specified by:
doubleClick in interface IGraphical
Since:
RFT1.0

doubleClick

public void doubleClick(java.awt.Point pt)
Performs a left-mouse double-click on the specified coordinates, relative to the associated TestObject. This method is a shortcut to the double-click method with a modifier parameter and coordinates. (The modifier is set to MOUSE_LEFT.)

Specified by:
doubleClick in interface IGraphical
Parameters:
pt - the x,y coordinates where the left-mouse double-click is performed
Since:
RFT1.0

doubleClick

public void doubleClick(MouseModifiers modifiers,
                        java.awt.Point pt)
Performs a mouse double-click on the specified coordinates, relative to the associated TestObject.

Specified by:
doubleClick in interface IGraphical
Since:
RFT1.0

nClick

public void nClick(int clickCount,
                   MouseModifiers modifiers,
                   java.awt.Point pt)
Performs a mouse n-click action on the specified coordinates, relative to the associated TestObject.

Specified by:
nClick in interface IGraphical
Since:
RFT1.0

drag

public void drag()
Performs a MOUSE_LEFT drag action on the associated TestObject. This method is used to simulate drag actions against controls that are typically not sensitive to drag actions.

Specified by:
drag in interface IGraphical
Since:
RFT1.0

drag

public void drag(MouseModifiers modifiers)
Performs a drag action on the associated TestObject with the supplied set of mouse modifiers. This method is used to simulate drag actions against controls that are typically not sensitive to drag actions.

Specified by:
drag in interface IGraphical
Since:
RFT1.0

drag

public void drag(java.awt.Point pt1,
                 java.awt.Point pt2)
Performs a MOUSE_LEFT drag action on the associated TestObject. The action is performed from (x1, y1) to (x2, y2) coordinates, relative to this TestObject.

Specified by:
drag in interface IGraphical
Parameters:
pt1 - the point where the drag action begins
pt2 - the point where the drag action ends
Since:
RFT1.0

drag

public void drag(MouseModifiers modifiers,
                 java.awt.Point pt1,
                 java.awt.Point pt2)
Performs a drag action on the associated TestObject. The action is performed from (x1, y1) to (x2, y2) coordinates, relative to this TestObject.

Specified by:
drag in interface IGraphical
Since:
RFT1.0

nClickDrag

public void nClickDrag(int clickCount,
                       MouseModifiers modifiers,
                       java.awt.Point pt1,
                       java.awt.Point pt2)
Performs a mouse n-click drag action on the specified coordinates, relative to the associated TestObject.

Specified by:
nClickDrag in interface IGraphical
Since:
RFT1.0

dragToScreenPoint

public void dragToScreenPoint(java.awt.Point screenPt)
Performs a MOUSE_LEFT drag action on the associated TestObject. The action is performed from a valid point within this TestObject to the screen-relative screenPt coordinates.

Specified by:
dragToScreenPoint in interface IGraphical
Since:
RFT1.0

dragToScreenPoint

public void dragToScreenPoint(java.awt.Point objectPt,
                              java.awt.Point screenPt)
Performs a MOUSE_LEFT drag action against the associated TestObject. The action is performed from (x, y), relative to this TestObject, to the screen-relative screenPt coordinates.

Specified by:
dragToScreenPoint in interface IGraphical
Since:
RFT1.0

dragToScreenPoint

public void dragToScreenPoint(MouseModifiers modifiers,
                              java.awt.Point objectPt,
                              java.awt.Point screenPt)
Performs a drag action against the associated TestObject. The action is performed from (x, y), relative to this TestObject, to the screen-relative screenPt coordinates.

Specified by:
dragToScreenPoint in interface IGraphical
Since:
RFT1.0

nClickDragToScreenPoint

public void nClickDragToScreenPoint(int clickCount,
                                    MouseModifiers modifiers,
                                    java.awt.Point objectPt,
                                    java.awt.Point screenPt)
Performs a mouse n-click drag action on the specified coordinates, relative to the associated TestObject.

Specified by:
nClickDragToScreenPoint in interface IGraphical
Since:
RFT1.0

mouseMove

public void mouseMove(java.awt.Point pt)
Performs a MOUSE_LEFT move action on the associated TestObject. The action is performed from (x1, y1) to (x2, y2) coordinates, relative to this TestObject.

Specified by:
mouseMove in interface IGraphical
Since:
RFT1.0

mouseMove

public void mouseMove(MouseModifiers modifiers,
                      java.awt.Point pt)
Performs a move action against the associated TestObject. The action is performed from (x1, y1) to (x2, y2) coordinates, relative to this TestObject.

Specified by:
mouseMove in interface IGraphical
Since:
RFT1.0

hover

public void hover(double secondDelay)
Hovers the mouse over the center of the associated TestObject. The mouse is moved to the center of the TestObject and stays there for at least the specified number of seconds.

You can record a hover action by moving the mouse over an object and hitting the shift key.

Specified by:
hover in interface IGraphical
Since:
RFT1.0

hover

public void hover(double secondDelay,
                  java.awt.Point pt)
Hovers the mouse over the specified coordinates of the associated TestObject. The mouse is moved to the object-relative coordinates of the TestObject and stays there for at least the specified number of seconds.

You can record a hover action by moving the mouse over an object and hitting the shift key.

Specified by:
hover in interface IGraphical
Since:
RFT1.0

hover

public void hover()
Hovers the mouse over the center of the associated TestObject. The mouse is moved to the center of the TestObject and stays there for the default length of time.

You can record a hover action by moving the mouse over an object and hitting the shift key.

Specified by:
hover in interface IGraphical
Since:
RFT1.0

hover

public void hover(java.awt.Point pt)
Hovers the mouse over the specified coordinates of the associated TestObject. The mouse is moved to the object-relative coordinates of the TestObject and stays there for the default length of time.

You can record a hover action by moving the mouse over an object and hitting the shift key.

Specified by:
hover in interface IGraphical
Since:
RFT1.0

clickRadio

public void clickRadio(Subitem childProperties)
Locate a radiobutton child with the supplied properties and click on it.

Since:
RFT2.0

getScreenSnapshot

public java.awt.image.BufferedImage getScreenSnapshot()
Takes a snapshot (screen capture) of the visible GuiTestObject

Since:
RFT2.1