T-Plan Robot Enterprise 4.0
Build No. 4.0-20140924.1

com.tplan.robot.scripting
Class DefaultJavaTestScript

java.lang.Object
  extended by com.tplan.robot.scripting.AbstractJavaTestScript
      extended by com.tplan.robot.scripting.DefaultJavaTestScript
All Implemented Interfaces:
JavaTestScript, TestWrapper

public class DefaultJavaTestScript
extends AbstractJavaTestScript

Default Java test script. Users wishing to write Java test scripts are recommended to extend this class and override the test() method with their own sequence of automated testing command calls. See the Developing Java Test Scripts document for an introduction and overview of the T-Plan Robot Enterprise Java Test Script Framework.

Let's have a simple test script which types "Hello world" on the remote desktop. Let's suppose that there's already connection to a desktop and all we have to do is to type the text. The script in the TPR language would then look as follows:

 Type "Hello word"
 

The same script in Java based on this class:

 import com.tplan.robot.scripting.DefaultJavaTestScript;
 import com.tplan.robot.scripting.JavaTestScript;
 import java.io.IOException;

 public class MyTest extends DefaultJavaTestScript {

    public void test() {
       try {
          type("Hello world");
       } catch (IOException ex) {
          ex.printStackTrace();
       }
    }
 }
 

To execute the script either:

T-Plan Robot Enterprise in fact supports execution of Java test scripts the same way as the TPR language ones. The tool is able to compile the Java code (.java) into byte code (.class) internally and execute it on the fly provided that you run a Java Development Kit (JDK). If you run T-Plan Robot Enterprise through a Java Runtime Environment (JRE), the tool will report an error because JRE is a limited version of Java and does not include the necessary Java Compiler binary javac.

A Java test script may be controlled the same way as the TPR test scripts - it may be executed, paused or stopped from the GUI or CLI. The only limitation is that the pause or stop requests get noticed and applied only inside the methods provided by this class. Though the GUI even provides some limited support of Java test script development, such as simple Java editor and reporting of javac compilation errors, it is recommended to use an IDE such as NetBeans or Eclipse to develop Java classes. This tool is not designed to support editing of complex Java projects.

Java test scripts may be also executed as standalone processes through their own main() method. As test scripts are executed as threads, one simple Java program can create and start any number of test instances. This allows to run multiple automated testing tasks simultaneously or even to use the tool for load testing through simulation of multiple users accessing the tested service or application.

Our "Hello world" example enhanced with the main() method would look as follows:

 import com.tplan.robot.*;
 import com.tplan.robot.scripting.DefaultJavaTestScript;
 import com.tplan.robot.scripting.JavaTestScript;
 import java.io.IOException;

 public class MyTest extends DefaultJavaTestScript {

    public void test() {
       try {
          type("Hello world");
       } catch (IOException ex) {
          ex.printStackTrace();
       }
    }

    public static void main(String args[]) {
       MyTest test = new MyTest();
       ApplicationSupport robot = new ApplicationSupport();
       AutomatedRunnable t = robot.createAutomatedRunnable(test, "javatest", args, System.out, false);
       new Thread(t).start();
    }
 }
 

The point is to let the ApplicationSupport class to create a test runnable (AutomatedRunnable) from an instance of our Java test class. As the resulting object implements the Runnable interface, it is possible to execute it through a Thread. Another important feature to notice is that the createAutomatedRunnable() method accepts a String array of input arguments. This makes it possible to customize any single test script runnable with any command line options specified in the T-Plan Robot Enterprise CLI Options document.

If you for some reason can not extend this class but you need to access its methods, you may create an instance and call its methods instead. Your class however must implement at least the JavaTestScript interface which is the bare minimum for a test script to be able to execute through the T-Plan Robot Enterprise framework. You must also make sure that the JavaTestScript.setContext(com.tplan.robot.scripting.ScriptingContext) and JavaTestScript.setInterpret(com.tplan.robot.scripting.interpret.TestScriptInterpret) methods get called correctly on this class instance. An example follows:

 import com.tplan.robot.scripting.*;
 import com.tplan.robot.scripting.interpret.TestScriptInterpret;
 import java.io.IOException;

 public class MyCustomTest implements JavaTestScript {
    ScriptingContext context;
    TestScriptInterpret interpret;

    public void setContext(ScriptingContext context) {
       this.context = context;
    }

    public void setInterpret(TestScriptInterpret interpret) {
       this.interpret = interpret;
    }

    public void test() {
       try {
          DefaultJavaTestScript defaultScript = new DefaultJavaTestScript();
          defaultScript.setContext(context);
          defaultScript.type("Hello world");
       } catch (IOException ex) {
          ex.printStackTrace();
       }
    }
 }
 

This way may be also efficiently used to create libraries of test tasks or routines similar to the functionality provided by the Run and Include commands.

Since version 2.2 Java test scripts may be easily called from regular ones. The Include command is capable of putting the JAR files or class paths with compiled Java code onto the Robot's Java class path in a dynamic way. The Run command was enhanced to support instantiation of such Java test scripts by class name. The Run command is also able to accept a set of parameters on the command line and pass them to the Java code.

For example, a call of a Java test script class test.DummyTest from the C:\tests\MyTests.jar JAR file with parameters of 'count' and 'wait' equal to '2' and '500' would look as follows:

As the parameters are stored by the Run command into the table of local variables, the Java test script may retrieve them inside their test() method through the context methods such as the getContext().getVariable(<parameterName>) one. To get the 'wait' parameter value from our example as int one would call getContext().getVariableAsInt("wait").

The list of parameters is by default not validated in any way. Java test scripts may optionally declare the parameters they support through implementing the ExtendedParamsObject interface (except the setParameters() method which is not used in this case). As the mechanism of parameter declaration takes advantage of the framework created originally for user preferences, the terminology might be misleading, especially in case of the ExtendedParamsObject.getVisualParameters() method where each parameter must be encapsulated in a Preference instance. The Preference object requires by default the configuration key (in our case the parameter name), the value type (INT, FLOAT, STRING, ...), label (short description) and description. The object allows to define various value restrictions and dependencies, for example minimum and maximum values for numeric parameters etc. See the Preference class documentation for a complete list.

If the parameters are declared properly the GUI will support the following features. To read more about the discussed GUI components see the Script Editor help topic in the GUI Reference document collection.

As is already indicated by the examples above, this class contains methods which provide almost the same functionality as elements of the T-Plan Robot Enterprise TPR language defined by the T-Plan Robot Enterprise Scripting Language Specification. The following table summarizes compatibility of this Java class with the specification and the existing limitations. Use this table as a reference of how to implement the same functionality both in the scripting language and Java as well as which limitations apply to conversion of TPR test scripts into Java.

Spec Command/Element Supported By Java Comments
Code comments Yes Java supports code comments similar to the scripting language ones.
Labels No Labels define places in the script code to jump to. As Java doesn't support a "goto" command, labels are not supported. A workaround is to use Java language elements to implement conditional execution blocks, such as methods, if/else and switch statements.
Time values Yes Time values are supported as arguments of methods corresponding to the scripting commands. Examples are "1s" (one second) or 5m (5 minutes
Procedures Yes Procedures correspond with Java void methods.
Numeric expressions Yes Numeric expressions specified by the TPR language are fully supported in Java.
Boolean expressions Yes Boolean expressions specified by the TPR language are fully supported in Java.
If/else statement Yes If/else statement specified by the TPR language is fully supported in Java.
For statement Yes For statement specified by the TPR language is supported in Java, just the for statement iterating over a set of enumerated values must be implemented indirectly with the help of a String array or Java Collections.
Local variables Yes Java supports the same concept of local variables as the TPR language. Global variables may be implemented in Java either as class member variables or stored to the variable list in the context through the ScriptingContext.setVariable(String, Object) method.
Return values Yes Java methods return exit values of the scripting language commands.
Connect command Yes Provided through the set of connect() methods.
Disconnect command Yes Provided through the disconnect() method.
Press command Yes Provided through the set of press() methods.
Type and Typeline commands Yes Provided through the set of type() and typeLine() methods.
Mouse command Yes Provided through the set of mouseEvent(), mouseMove(), mouseClick(), mouseRightClick(), mouseDoubleClick(), mouseDrag(), mouseRightDrag(), mouseWheelUp() and mouseWheelDown() methods.
Var and Eval commands Yes (indirectly) There is no direct method corresponding to the Var/Eval commands. Script variables populated by the commands or the automated testing framework (so called predefined or implicit variables) can be accessed through the context methods ScriptingContext.getVariable(String) and ScriptingContext.setVariable(String, Object). Other user variables may be implemented either as Java local or member variables or through the context as well.

Dynamically populated variables are present in the context but they will return just dummy values populated at the time of context creation. To get the desired variable value use appropriate Java code as follows:
  • To get the current time in milliseconds (variable _CURTIME) use System.currentTimeMillis().
  • To get the formatted current time and date (variable _CURDATE) use new java.util.Date().toString(). If you want to apply the format specified in the user preferences, load it through String format = UserConfiguration.getInstance().getString("scripting.curdateFormat") and format the Date object through new java.text.SimpleDateFormat(format).format(new Date()).
  • To get a random number (variable _RANDOM) use java.util.Random.
  • To get RGB of a pixel on the desktop use ((BufferedImage) getContext().getClient().getImage()).getRGB(x,y). This will yield the RGB value as integer which may be used in constructor of java.awt.Color. Should you want to convert the color to the HTML-style format, call getContext().getParser().colorToString(Color).
  • To get the current mouse coordinates (variables _MOUSE_X and _MOUSE_Y) call getContext().getClient().getLastMouseEvent().getPoint(). Don't forget to test whether the client is not null and connected and whether the mouse event is not null. Be aware that when the client connects to a desktop it doesn't know the initial mouse pointer location. To start tracking of the last mouse event you have to perform at least one mouse() call

Variables passed through the -v/--variable CLI option may be accessed through the getContext().getCommandLineVariables() method. The overriding mechanism known from TPR test script is not applied in case of Java test scripts which are free to decide whether to use or ignore the CLI value.
Run and Include commands Yes Version 2.3 and newer supports direct calls of .tpr scripts through the run(java.lang.String) and include(java.lang.String) methods. These have the same functionality as the corresponding Run and Include commands. Procedures imported through the include() method can be called (executed) through callProcedure(java.lang.String, java.lang.String[]). The run() method is also capable of running Java source code files (*.java); the tool must however run on a JDK to have access to the Java compiler. The method may also instantiate and run a Java test script specified by a fully qualified class name. For example, a call like run("mypackage.MyTestScript") will make an attempt to instantiate the mypackage.MyTestScript class and execute its test() method provided that the class is available on the class path (or has been put onto the class path through a include([JAR_file_or_class_path]) method call) and it implements at least the JavaTestScript interface

Versions prior to 2.3 provide no direct method corresponding to the Run/Include commands. It is not possible to execute a script in the TPR format directly from a Java test script (only as a separate independent automated process created through the mechanism described in theAutomatedRunnable interface). In cases where Java is used as an exclusive automation language and no mixing of Java and TPR scripts is needed it is recommended to use capabilities of the Java language to create libraries with test script routines. The Include command corresponds to instantiation of another Java class and accessing its methods and member variables. The Run command is equivalent to calling of test() method of another Java test script instance.
Pause command Yes Provided through the set of pause() methods.
Exit command Yes (indirectly) To exit a script execution (scope=process) use the System.exit(int) method. Other exit scopes such as procedure, block and file must be implemented indirectly using Java language capabilities.
Log command Yes Provided through the log(java.lang.String, java.util.logging.Level) method.
Wait command Yes Provided through the wait(java.lang.String) method.
WaitFor command Yes Provided through the waitForBell(), waitForUpdate(), waitForMatch(), waitForMismatch() and waitForClipboard() methods.
CompareTo command Yes Provided through the compareTo() methods.
Exec command Yes Provided through the exec() methods.
Screenshot command Yes Provided through the screenshot() methods.
Report command Yes (partially) Provided through the report() methods. There's however one limitation. Though the scope parameter is among the method arguments, it is present just for the sake of backward compatibility and should be considered as obsolete. Its value will be ignored and the method will always execute with the scope fixed to all (include all outputs created by the test scripts in the report).
Warning command Yes Provided through the warning() methods.
Sendmail command Yes Provided through the sendMail() methods.
Script command Yes Provided through the script() and similar methods.
Step command Yes Provided through the step() methods.
File command No Users are advised to take advantage of standard Java I/O APIs to implement plain text file input/output. To parse CSV it is possible to use the FileCommand.parseCSV(java.lang.CharSequence, int, char, char, boolean, boolean, int[]) method or employ any public CSV parsing Java library.
Excel command Yes Provided through the excelOpen(java.io.File, java.io.File, java.lang.String, java.lang.String) and other excel-prefixed methods.
Timer command Yes Provided through the timer(java.lang.String, java.lang.String, long, long, java.lang.String, java.lang.String, java.io.File) method and other timer-prefixed methods.

Methods representing commands of the TPR scripting language share the following design principles:

Most methods of this class are annotated. The goal is to provide information allowing to map these methods and their arguments onto commands and parameters of the TPR scripting language. This data is retrieved through Java Reflection API by the converter which provides conversion of TPR test scripts into Java classes. Should you want to extend both the TPR language and the Java test script class with a new command/method, you have to annotate the method in a similar way to make the command calls convertible to Java code.


T-Plan Robot Enterprise, (C) 2009-2014 T-Plan Limited. All rights reserved.


Nested Class Summary
static interface DefaultJavaTestScript.Command
           
static interface DefaultJavaTestScript.Param
           
 
Field Summary
 
Fields inherited from interface com.tplan.robot.scripting.TestWrapper
WRAPPER_TYPE_BLOCK, WRAPPER_TYPE_INCLUDE, WRAPPER_TYPE_JAVA, WRAPPER_TYPE_PROCEDURE, WRAPPER_TYPE_RUN, WRAPPER_TYPE_SCRIPT, WRAPPER_TYPE_UNKNOWN
 
Constructor Summary
DefaultJavaTestScript()
           
 
Method Summary
 int callProcedure(java.lang.String procedureName, java.lang.String... args)
          Call a stored procedure which was previously imported from a .tpr script through the call of run(java.lang.String) or include(java.lang.String).
 int compareTo(java.io.File[] templates)
          Compare the current remote desktop image to one or more template images using the default histogram based image comparison (code "default") and default numeric pass rate (95% unless the user modified the value in user preferences).
 int compareTo(java.io.File[] templates, float passRate)
          Compare the current remote desktop image to one or more template images using the default histogram based image comparison (code "default") and numeric pass rate.
 int compareTo(java.io.File[] templates, float passRate, java.awt.Rectangle cmpArea, boolean removeBg, java.lang.String bgColor, java.lang.Integer minAlpha)
          Search the current remote desktop image for one or more template images using the "search" image comparison module (method), numeric pass rate and an optional comparison rectangle.
 int compareTo(java.io.File[] templates, float passRate, java.awt.Rectangle cmpArea, boolean removeBg, java.lang.String bgColor, java.lang.Integer minAlpha, java.lang.Integer rgbTolerance)
          Search the current remote desktop image for one or more template images using the "search" image comparison module (method), numeric pass rate and an optional comparison rectangle.
 int compareTo(java.io.File[] templates, float passRate, java.awt.Rectangle cmpArea, java.lang.String sort)
          Search the current remote desktop image for one or more template images using the "search2" image comparison module (method), numeric pass rate and an optional comparison rectangle.
 int compareTo(java.io.File[] templates, float passRate, java.awt.Rectangle cmpArea, java.lang.String sort, float[] scale)
          Search the current remote desktop image for one or more template images using the "search2" image comparison module (method), numeric pass rate and an optional comparison rectangle.
 int compareTo(java.io.File[] templates, float passRate, java.awt.Rectangle cmpArea, java.lang.String text, int distance, java.lang.String pattern)
          Recognize the text on the screen by a character image collection using the Image Based Text Recognition comparison method.
 int compareTo(java.io.File[] template, java.lang.String method)
          Compare the current remote desktop image to one or more template images using the specified image comparison module and default numeric pass rate (100% for "search", 95% for "default" unless the user modified these values in user preferences).
 int compareTo(java.io.File[] templates, java.lang.String method, float passRate)
          Compare the current remote desktop image to one or more template images using the specified image comparison module instance and numeric pass rate.
 int compareTo(java.io.File[] templates, java.lang.String method, float passRate, java.lang.Integer rgbTolerance)
          Compare the current remote desktop image to one or more template images using the specified image comparison module instance and numeric pass rate.
 int compareTo(java.io.File[] templates, java.lang.String method, float passRate, java.awt.Rectangle cmpArea)
          Compare the current remote desktop image to one or more template images using the specified image comparison module instance, numeric pass rate and an optional comparison rectangle.
 int compareTo(java.io.File[] templates, java.lang.String method, float passRate, java.awt.Rectangle cmpArea, java.lang.Integer rgbTolerance)
          Compare the current remote desktop image to one or more template images using the specified image comparison module instance, numeric pass rate and an optional comparison rectangle.
 int compareTo(java.io.File[] templates, java.lang.String method, java.lang.String methodParams, float passRate, java.awt.Rectangle cmpArea)
          Compare the current remote desktop image to one or more template images using the specified image comparison module instance, numeric pass rate and an optional comparison rectangle.
 int compareTo(java.io.File template, java.lang.Float passRate, java.awt.Rectangle cmpArea, java.awt.Color color, java.awt.Color[] bridgeColors, java.lang.Integer rgbTolerance, java.lang.Integer rotations, java.lang.Boolean draw, java.lang.Boolean clear)
          Analyze the current remote desktop image using the Object Search Method.
 int compareTo(java.awt.Image[] templates, ImageComparisonModule module, float passRate, java.awt.Rectangle cmpArea)
          Compare the current remote desktop image to one or more template images using the specified image comparison module instance, numeric pass rate and an optional comparison rectangle.
 int compareTo(java.awt.Image[] templates, ImageComparisonModule module, float passRate, java.awt.Rectangle cmpArea, java.lang.Boolean removeBg, java.awt.Color bgColor, java.lang.Integer minAlpha)
          Compare the current remote desktop image to one or more template images using the specified image comparison module instance, numeric pass rate and an optional comparison rectangle.
 int compareTo(java.awt.Image[] templates, ImageComparisonModule module, float passRate, java.awt.Rectangle cmpArea, java.lang.Boolean removeBg, java.awt.Color bgColor, java.lang.Integer minAlpha, java.lang.Integer rgbTolerance)
          Compare the current remote desktop image to one or more template images using the specified image comparison module instance, numeric pass rate and an optional comparison rectangle.
 int compareTo(java.awt.Image[] templates, ImageComparisonModule module, float passRate, java.awt.Rectangle cmpArea, java.lang.Integer rgbTolerance)
          Compare the current remote desktop image to one or more template images using the specified image comparison module instance, numeric pass rate and an optional comparison rectangle.
 int compareTo(java.awt.Image template, java.lang.Float passRate, java.awt.Rectangle cmpArea, java.awt.Color color, java.awt.Color[] bridgeColors, java.lang.Integer rgbTolerance, java.lang.Integer rotations, java.lang.Boolean draw, java.lang.Boolean clear)
          Analyze the current remote desktop image using the Object Search Method.
 int compareTo(java.awt.Rectangle cmpArea, java.lang.String language)
          Perform Optical Character Recognition (OCR) using the Tesseract engine.
 int compareTo(java.awt.Rectangle cmpArea, java.lang.String language, float scale, java.lang.String text, int distance, java.lang.String pattern)
          Perform Optical Character Recognition (OCR) using the Tesseract engine.
 int compareTo(java.awt.Rectangle cmpArea, java.lang.String language, float scale, java.lang.String text, int distance, java.lang.String pattern, int mode, int filter, int fontSize)
          Perform Optical Character Recognition (OCR) using the Tesseract engine.
 int compareTo(java.awt.Rectangle cmpArea, java.lang.String language, java.lang.String text, java.lang.String pattern)
          Perform Optical Character Recognition (OCR) using the Tesseract engine.
 int connect(java.lang.String host)
          Connect to a server which requires no authentication (for example a Java client or an RFB/VNC server which is configured this way).
 int connect(java.lang.String host, boolean force)
          Connect to a server which requires no authentication (for example a Java client or an RFB/VNC server which is configured this way).
 int connect(java.lang.String host, java.lang.String password)
          Connect to a server which may or may not require a password.
 int connect(java.lang.String host, java.lang.String user, java.lang.String password, boolean force)
          Connect to a server using the specified user and password.
 int connect(java.lang.String host, java.lang.String user, java.lang.String password, java.util.Map<java.lang.String,java.lang.Object> params, boolean force)
          Connect to a desktop.
 int connect(java.lang.String host, java.lang.String user, java.lang.String password, java.lang.String params, java.lang.String paramSeparator, boolean force)
          Connect to a desktop.
 int disconnect()
          Disconnect from a desktop.
 int excelClose(java.lang.String id, boolean save)
          Close and eventually save the specified Excel document.
 int excelCreate(java.io.File outputFile, java.lang.String sheetName, java.lang.String id)
          Create a new Microsoft Excel document for reading and writing.
 int excelCreate(java.io.OutputStream outputStream, java.lang.String sheetName, java.lang.String id)
          Create a Microsoft Excel document and associate it with an output stream.
 int excelCreate(java.lang.String sheetName, java.lang.String id)
          Create and select a new sheet in the current or specified Excel document.
 int excelFind(java.lang.Object value, java.lang.String type, boolean evaluate, java.lang.Object sheet, java.lang.String id)
          Search the specified sheet for a cell of the given type and/or value.
 int excelFind(java.lang.String pattern, boolean evaluate, java.lang.String type, java.lang.Object sheet, java.lang.String id)
          Search the specified sheet for a cell whose value (and optionally also type) matches the given regular expression.
 int excelOpen(java.io.File inputFile, java.io.File outputFile, java.lang.String sheet, java.lang.String id)
          Open a Microsoft Excel file for reading and writing.
 int excelOpen(java.io.File inputFile, java.lang.String id)
          Open a Microsoft Excel file for reading and writing and select automatically the first sheet.
 int excelOpen(java.io.InputStream inputStream, java.io.OutputStream outputStream, java.lang.String sheet, java.lang.String id)
          Open a Microsoft Excel file.
 int excelSelect(int row, java.lang.String column, boolean evaluate, java.lang.String id)
          Select a cell from the current sheet and retrieve its coordinates (row/column, reference), type and value to the context variables of _EXCEL_CELL_ROW, _EXCEL_CELL_COLUMN, _EXCEL_CELL_REF, _EXCEL_CELL_TYPE and _EXCEL_CELL_VALUE.
 int excelSelect(int row, java.lang.String column, java.lang.String sheet, boolean evaluate, java.lang.String id)
          Select a cell and retrieve its value and type to the context variables.
 int excelSelect(java.lang.String ref, boolean evaluate, java.lang.String id)
          Select a cell from the current sheet and retrieve its value and type to the context variables.
 int excelSelect(java.lang.String sheet, java.lang.String id)
          Select (open) a sheet.
 int excelSelect(java.lang.String ref, java.lang.String sheet, boolean evaluate, java.lang.String id)
          Select a cell and retrieve its value and type to the context variables.
 int excelSet(int row, java.lang.String column, java.lang.Object value, java.lang.Object sheet, java.lang.String type, java.lang.String id)
          Set value and/or type of the specified cell.
 int excelSet(int row, java.lang.String column, java.lang.Object value, java.lang.String id)
          Set value of the specified cell in the currently selected sheet.
 int excelSet(int row, java.lang.String column, java.lang.Object value, java.lang.String type, java.lang.String id)
          Set value and/or type of the specified cell in the currently selected sheet.
 int excelSet(java.lang.Object value, java.lang.String id)
          Set value of the currently selected (previously used) cell in the currently selected sheet.
 int excelSet(java.lang.String ref, java.lang.Object value, java.lang.Object sheet, java.lang.String type, java.lang.String id)
          Set value and/or type of the specified cell.
 int excelSet(java.lang.String ref, java.lang.Object value, java.lang.String id)
          Set value of the specified cell in the currently selected sheet.
 int excelSet(java.lang.String ref, java.lang.Object value, java.lang.String type, java.lang.String id)
          Set value and/or type of the specified cell in the currently selected sheet.
 int exec(java.lang.String command)
          Convenience method employing the exec(java.lang.String, java.io.OutputStream, int, java.lang.String) method to execute a command without any further options.
 int exec(java.lang.String command, boolean nowait)
          Convenience method employing the exec(java.lang.String, java.io.OutputStream, int, java.lang.String) method to execute a command without any further options.
 int exec(java.lang.String command, java.io.OutputStream out)
          Convenience method employing the exec(java.lang.String, java.io.OutputStream, int, java.lang.String) method to execute a command once (count=1) with no waiting period specified (wait=null).
 int exec(java.lang.String command, java.io.OutputStream out, boolean nowait, int count, java.lang.String wait)
          Execute a command of the local operating system.
 int exec(java.lang.String command, java.io.OutputStream out, int count, java.lang.String wait)
          Execute a command of the local operating system.
 int exec(java.lang.String command, java.lang.String wait)
          Convenience method employing the exec(java.lang.String, java.io.OutputStream, int, java.lang.String) method to execute a command once (count=1) with no output stream (out=null) and no waiting period (wait=null).
 int exec(java.lang.String command, java.io.Writer out)
          Convenience method employing the exec(java.lang.String, java.io.Writer, int, java.lang.String) method to execute a command once (count=1) with no waiting period specified (wait=null).
 int exec(java.lang.String command, java.io.Writer out, boolean nowait, int count, java.lang.String wait)
          Convenience method employing the exec(java.lang.String, java.io.OutputStream, int, java.lang.String) method with the command output redirected to a Writer rather than to an OutputStream.
 int exec(java.lang.String command, java.io.Writer out, int count, java.lang.String wait)
          Convenience method employing the exec(java.lang.String, java.io.OutputStream, int, java.lang.String) method with the command output redirected to a Writer rather than to an OutputStream.
 int execBrowser(java.lang.String url)
          A convenience method to open a web browser on the local operating system.
 int exit(java.lang.Integer exitCode)
          Exit the test script.
 int exit(java.lang.Integer exitCode, java.lang.String description)
          Exit the test script.
 int fileAppend(java.lang.String text, java.lang.String id)
          Append text to the end of the text file.
 int fileClose(java.lang.String id, boolean save)
          Close and eventually save the specified text/CSV file.
 int fileCreate(java.io.File outputFile, java.lang.String id)
          Create a new text or CSV file for reading and writing.
 int fileCreate(java.io.OutputStream outputStream, java.lang.String id)
          Create a text or CSV file and associate it with an output stream.
 int fileDelete(int line, int column, int length, java.lang.String id)
          Delete the text specified by the line/column numbers and length..
 int fileFind(java.lang.String text, int line, int column, java.lang.String direction, java.lang.String scope, java.lang.String id)
          Find the first position of the specified text in the file..
 int fileInsert(java.lang.String text, int line, int column, java.lang.String id)
          Insert text to the position specified by the line and column parameters.
 int fileOpen(java.io.File inputFile, java.io.File outputFile, java.lang.String id)
          Open a text or CSV file for reading and writing.
 int fileOpen(java.io.InputStream inputStream, java.io.OutputStream outputStream, java.lang.String id)
          Open a text or CSV file.
 int fileParse(int line, java.lang.String id)
          Parse the specified CSV line into values using the rules defined by the RFC 4180.
 int fileParse(int line, java.lang.String pattern, boolean trim, java.lang.String id)
          Parse the specified line into values by the given java.util.regex.Pattern compatible regular expression.
 int fileParse(int line, java.lang.String separator, java.lang.String delimeter, boolean trim, java.lang.String id)
          Parse the specified line into values by the given separator and delimeter.
 int fileRead(int line, int column, int length, java.lang.String id)
          Read text of a single line from the position specified by line, column and length parameters.
 int getExitCode()
          Return result of the last executed command (method).
 TestWrapper getRootWrapper()
           
 UserConfiguration getUserConfiguration()
          Convenience method for quick access to the user configuration.
 int imageDoctorOff()
          Set off the Image Doctor wizard.
 int imageDoctorOn()
          Set on the Image Doctor wizard.
 int imageDoctorSkip()
          Set on an internal flag which will make the Image Doctor wizard ignore result of the next comparison command (method call).
 int include(java.lang.String file)
          Include a TPR test script (.tpr).
 boolean isPass()
          Return result of the last executed command (method).
 int log(java.lang.String message, java.util.logging.Level level)
          Log a message to the script execution log.
 int mouseClick(int x, int y)
          Perform a single left mouse click on the currently connected desktop.
 int mouseClick(int x, int y, int count)
          Perform left mouse click(s) on the currently connected desktop.
 int mouseClick(int x, int y, int count, java.lang.String wait)
          Perform left mouse click(s) on the currently connected desktop.
 int mouseClick(java.awt.Point to)
          Perform a single left mouse click on the currently connected desktop.
 int mouseClick(java.awt.Point to, int count)
          Perform left mouse click(s) on the currently connected desktop.
 int mouseClick(java.awt.Point to, int modifiers, int button, int count, java.lang.String wait)
          Perform left mouse click(s) on the currently connected desktop.
 int mouseClick(java.awt.Point to, int count, java.lang.String wait)
          Perform left mouse click(s) on the currently connected desktop.
 int mouseClick(java.awt.Point to, java.lang.String wait)
          Perform a single left mouse click on the currently connected desktop.
 int mouseDoubleClick(int x, int y)
          Perform a double left mouse click on the currently connected desktop.
 int mouseDoubleClick(int x, int y, java.lang.String wait)
          Perform a double left mouse click on the currently connected desktop.
 int mouseDoubleClick(java.awt.Point to)
          Perform a double left mouse click on the current desktop client.
 int mouseDoubleClick(java.awt.Point to, java.lang.String wait)
          Perform a double left mouse click on the current desktop client.
 int mouseDrag(java.awt.Point from, java.awt.Point to, int modifiers, int button, java.lang.String wait)
          Perform a left button mouse drag on the currently connected desktop.
 int mouseEvent(java.lang.String action, int modifiers, int button, java.awt.Point from, java.awt.Point to, int count, java.lang.String wait)
          Perform a generic mouse action on the currently connected desktop.
 int mouseEvent(java.lang.String action, java.awt.Point center, int start, int end, int count, java.lang.String wait)
          Perform a pinch or zoom action on the currently connected desktop.
 int mouseMove(int x, int y)
          Perform a mouse move on the currently connected desktop.
 int mouseMove(int x, int y, int modifiers, java.lang.String wait)
          Perform a mouse move on the currently connected desktop with optional modifier key(s) pressed.
 int mouseMove(int x, int y, java.lang.String wait)
          Perform a mouse move on the currently connected desktop.
 int mouseMove(java.awt.Point to)
          Perform a mouse move on the currently connected desktop.
 int mouseMove(java.awt.Point to, int modifiers, java.lang.String wait)
          Perform a mouse move on the currently connected desktop with optional modifier key(s) pressed.
 int mouseMove(java.awt.Point to, java.lang.String wait)
          Perform a mouse move on the currently connected desktop.
 int mousePinch()
          Perform a pinch action with the default center point and the start/end distances on the currently connected desktop.
 int mousePinch(int count, java.lang.String wait)
          Perform a pinch action with the default center point and the start/end distances on the currently connected desktop.
 int mousePinch(java.awt.Point center, int start, int end, int count, java.lang.String wait)
          Perform a pinch action on the currently connected desktop.
 int mouseRightClick(int x, int y)
          Perform a single right mouse click on the currently connected desktop.
 int mouseRightClick(int x, int y, int count)
          Perform right mouse click(s) on the currently connected desktop.
 int mouseRightClick(int x, int y, int count, java.lang.String wait)
          Perform right mouse click(s) on the currently connected desktop.
 int mouseRightClick(java.awt.Point to)
          Perform a single right mouse click on the currently connected desktop.
 int mouseRightClick(java.awt.Point to, int count)
          Perform right mouse click(s) on the currently connected desktop.
 int mouseRightClick(java.awt.Point to, int modifiers, int count, java.lang.String wait)
          Perform right mouse click(s) on the currently connected desktop.
 int mouseRightClick(java.awt.Point to, int count, java.lang.String wait)
          Perform right mouse click(s) on the currently connected desktop.
 int mouseRightDrag(java.awt.Point from, java.awt.Point to, int modifiers, java.lang.String wait)
          Perform a right button mouse drag on the currently connected desktop.
 int mouseWheelDown(int x, int y, int modifiers, int count, java.lang.String wait)
          Scroll down the mouse wheel on the current desktop.
 int mouseWheelDown(java.awt.Point to, int modifiers, int count, java.lang.String wait)
          Scroll down the mouse wheel on the current desktop.
 int mouseWheelUp(int x, int y, int modifiers, int count, java.lang.String wait)
          Scroll up the mouse wheel on the current desktop.
 int mouseWheelUp(java.awt.Point to, int modifiers, int count, java.lang.String wait)
          Scroll up the mouse wheel on the current desktop.
 int mouseZoom()
          Perform a zoom action with the default center point and the start/end distances on the currently connected desktop.
 int mouseZoom(int count, java.lang.String wait)
          Perform a zoom action with the default center point and the start/end distances on the currently connected desktop.
 int mouseZoom(java.awt.Point center, int start, int end, int count, java.lang.String wait)
          Perform a zoom action on the currently connected desktop.
 int pause()
          Pause execution of the test script until the user manually resumes it.
 int pause(java.lang.String reason)
          Pause execution of the test script until the user manually resumes it with an optional description for report providers.
 int press(char c, int location, int count, java.lang.String wait)
          Press a character with optional modifiers on the current desktop once or more times.
 int press(char c, int location, int count, java.lang.String delay, java.lang.String wait)
          Press a character with optional modifiers on the current desktop once or more times.
 int press(java.lang.String key)
          Press a key with optional modifiers on the current desktop.
 int press(java.lang.String key, int location)
          Press a key with optional modifiers on the current desktop.
 int press(java.lang.String key, int location, int count, java.lang.Boolean release, java.lang.String delay, java.lang.String wait)
          Press a key with optional modifiers on the current desktop once or more times.
 int press(java.lang.String key, int location, int count, java.lang.String wait)
          Press a key with optional modifiers on the current desktop once or more times.
 int press(java.lang.String key, int location, int count, java.lang.String delay, java.lang.String wait)
          Press a key with optional modifiers on the current desktop once or more times.
 int press(java.lang.String key, int location, java.lang.String wait)
          Press a key with optional modifiers on the current desktop.
 int press(java.lang.String key, java.lang.String wait)
          Press a key with optional modifiers on the current desktop.
 int press(java.lang.String key, java.lang.String wait, int count)
          Press a key with optional modifiers on the current desktop once or more times.
 int report(java.io.File out)
          Start the default report provider to generate a report on test script execution.
 int report(java.io.File out, java.lang.String description)
          Start the default report provider to generate a report on test script execution.
 int report(java.io.File out, java.lang.String provider, java.lang.String description)
          Start the specified report provider to generate a report on test script execution.
 int report(java.io.File out, java.lang.String provider, java.lang.String description, java.lang.String scope)
          Start the specified report provider to generate a report on test script execution.
 int run(java.lang.String script)
          Execute a TPR test script (.tpr) or a source Java file (.java) or instantiate & execute a Java test script specified by a fully qualified class name (with package).
 int run(java.lang.String script, java.lang.Object... parameters)
          Execute a test script with optional parameters.
 int screenshot(java.io.File file)
          Take a screen shot of the remote desktop and save it to a file.
 int screenshot(java.io.File file, java.awt.Rectangle area)
          Take a screen shot of the remote desktop or its part and save it to a file.
 int screenshot(java.io.File file, java.lang.String description)
          Take a screen shot of the remote desktop and save it to a file.
 int screenshot(java.io.File file, java.lang.String description, java.awt.Rectangle area)
          Take a screen shot of the remote desktop or its part and save it to a file.
 int screenshot(java.io.File file, java.lang.String description, java.awt.Rectangle area, java.io.File[] templates, float passRate, java.awt.Rectangle cmpArea, boolean removeBg, java.lang.String bgColor, java.lang.Integer minAlpha, boolean drawResults)
          Take a screen shot of the remote desktop or its part, save it to a file and perform image search using the "search" comparison method with the support of filtering background from the template image(s).
 int screenshot(java.io.File file, java.lang.String description, java.awt.Rectangle area, java.io.File[] templates, float passRate, java.awt.Rectangle cmpArea, boolean removeBg, java.lang.String bgColor, java.lang.Integer minAlpha, java.lang.Integer rgbTolerance, boolean drawResults)
          Take a screen shot of the remote desktop or its part, save it to a file and perform image search using the "search" comparison method with the support of filtering background from the template image(s).
 int screenshot(java.io.File file, java.lang.String description, java.awt.Rectangle area, java.io.File[] templates, float passRate, java.awt.Rectangle cmpArea, boolean removeBg, java.lang.String bgColor, java.lang.Integer minAlpha, java.lang.Integer rgbTolerance, boolean drawResults, boolean drawDiff)
          Take a screen shot of the remote desktop or its part, save it to a file and perform image search using the "search" comparison method with the support of filtering background from the template image(s).
 int screenshot(java.io.File file, java.lang.String description, java.awt.Rectangle area, java.io.File[] templates, float passRate, java.awt.Rectangle cmpArea, java.lang.String sort, boolean drawResults)
          Take a screen shot of the remote desktop or its part, save it to a file and perform image comparison with the given template(s) using the Enterprise Image Search v2 method (code "search2").
 int screenshot(java.io.File file, java.lang.String description, java.awt.Rectangle area, java.io.File[] templates, float passRate, java.awt.Rectangle cmpArea, java.lang.String sort, boolean drawResults, boolean drawDiff)
          Take a screen shot of the remote desktop or its part, save it to a file and perform image comparison with the given template(s) using the Enterprise Image Search v2 method (code "search2").
 int screenshot(java.io.File file, java.lang.String description, java.awt.Rectangle area, java.io.File[] templates, float passRate, java.awt.Rectangle cmpArea, java.lang.String sort, float[] scale, boolean drawResults, boolean drawDiff)
          Take a screen shot of the remote desktop or its part, save it to a file and perform image comparison with the given template(s) using the Enterprise Image Search v2 method (code "search2").
 int screenshot(java.io.File file, java.lang.String description, java.awt.Rectangle area, java.io.File[] templates, float passRate, java.awt.Rectangle cmpArea, java.lang.String text, int distance, java.lang.String pattern, boolean drawResults)
          Take a screen shot of the remote desktop or its part, save it to a file and call the Image Based Text Recognition comparison method to recognize text from the desktop image or its part.
 int screenshot(java.io.File file, java.lang.String description, java.awt.Rectangle area, java.io.File[] templates, java.lang.String method, float passRate)
          Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template.
 int screenshot(java.io.File file, java.lang.String description, java.awt.Rectangle area, java.io.File[] templates, java.lang.String method, float passRate, java.lang.Integer rgbTolerance)
          Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template.
 int screenshot(java.io.File file, java.lang.String description, java.awt.Rectangle area, java.io.File[] templates, java.lang.String method, float passRate, java.awt.Rectangle cmpArea)
          Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template.
 int screenshot(java.io.File file, java.lang.String description, java.awt.Rectangle area, java.io.File[] templates, java.lang.String method, java.lang.String methodParams, float passRate, java.awt.Rectangle cmpArea)
          Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template.
 int screenshot(java.io.File file, java.lang.String description, java.awt.Rectangle area, java.io.File[] templates, java.lang.String method, java.lang.String methodParams, float passRate, java.awt.Rectangle cmpArea, boolean drawResults)
          Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template.
 int screenshot(java.io.File file, java.lang.String description, java.awt.Rectangle area, java.io.File[] templates, java.lang.String method, java.lang.String methodParams, float passRate, java.awt.Rectangle cmpArea, boolean drawResults, boolean drawDiff)
          Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template.
 int screenshot(java.io.File file, java.lang.String description, java.awt.Rectangle area, java.io.File[] templates, java.lang.String method, java.lang.String methodParams, float passRate, java.awt.Rectangle cmpArea, java.lang.Integer rgbTolerance, boolean drawResults)
          Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template.
 int screenshot(java.io.File file, java.lang.String description, java.awt.Rectangle area, java.io.File[] templates, java.lang.String method, java.lang.String methodParams, float passRate, java.awt.Rectangle cmpArea, java.lang.Integer rgbTolerance, boolean drawResults, boolean drawDiff)
          Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template.
 int screenshot(java.io.File file, java.lang.String description, java.awt.Rectangle area, java.io.File template, float passRate, java.awt.Rectangle cmpArea, java.awt.Color color, java.awt.Color[] bridgeColors, java.lang.Integer rgbTolerance, java.lang.Integer rotations, java.lang.Boolean draw, java.lang.Boolean clear)
          Take a screen shot of the remote desktop or its part, save it to a file and perform image comparison using the Object Search method.
 int screenshot(java.io.File file, java.lang.String description, java.awt.Rectangle area, java.awt.Image[] templates, float passRate, java.awt.Rectangle cmpArea, boolean removeBg, java.lang.String bgColor, java.lang.Integer minAlpha, boolean drawResults)
          Take a screen shot of the remote desktop or its part, save it to a file and perform image search using the "search" comparison method with the support of filtering background from the template image(s).
 int screenshot(java.io.File file, java.lang.String description, java.awt.Rectangle area, java.awt.Image[] templates, float passRate, java.awt.Rectangle cmpArea, boolean removeBg, java.lang.String bgColor, java.lang.Integer minAlpha, java.lang.Integer rgbTolerance, boolean drawResults)
          Take a screen shot of the remote desktop or its part, save it to a file and perform image search using the "search" comparison method with the support of filtering background from the template image(s).
 int screenshot(java.io.File file, java.lang.String description, java.awt.Rectangle area, java.awt.Image[] templates, float passRate, java.awt.Rectangle cmpArea, boolean removeBg, java.lang.String bgColor, java.lang.Integer minAlpha, java.lang.Integer rgbTolerance, boolean drawResults, boolean drawDiff)
          Take a screen shot of the remote desktop or its part, save it to a file and perform image search using the "search" comparison method with the support of filtering background from the template image(s).
 int screenshot(java.io.File file, java.lang.String description, java.awt.Rectangle area, java.awt.Image[] templates, java.lang.String method, java.lang.String methodParams, float passRate, java.awt.Rectangle cmpArea)
          Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template.
 int screenshot(java.io.File file, java.lang.String description, java.awt.Rectangle area, java.awt.Image[] templates, java.lang.String method, java.lang.String methodParams, float passRate, java.awt.Rectangle cmpArea, boolean drawResults)
          Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template.
 int screenshot(java.io.File file, java.lang.String description, java.awt.Rectangle area, java.awt.Image[] templates, java.lang.String method, java.lang.String methodParams, float passRate, java.awt.Rectangle cmpArea, boolean drawResults, boolean drawDiff)
          Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template.
 int screenshot(java.io.File file, java.lang.String description, java.awt.Rectangle area, java.awt.Rectangle cmpArea, java.lang.String language, float scale, java.lang.String text, int distance, java.lang.String pattern)
          Take a screen shot of the remote desktop or its part, save it to a file and perform Tesseract OCR to recognize text from the desktop image or its part.
 int screenshot(java.io.File file, java.lang.String description, java.awt.Rectangle area, java.awt.Rectangle cmpArea, java.lang.String language, float scale, java.lang.String text, int distance, java.lang.String pattern, int mode, int filter, int fontSize)
          Take a screen shot of the remote desktop or its part, save it to a file and perform Tesseract OCR to recognize text from the desktop image or its part.
 int screenshot(java.io.File file, java.lang.String description, java.awt.Rectangle area, java.awt.Rectangle cmpArea, java.lang.String language, java.lang.String text, java.lang.String pattern)
          Take a screen shot of the remote desktop or its part, save it to a file and perform Tesseract OCR to recognize text from the desktop image or its part.
 int script(java.lang.String number, boolean isEnd, java.lang.String name)
          Define start or end of a script (test case).
 int scriptEnd(java.lang.String number)
          Define end of a script (test case).
 int scriptEnd(java.lang.String number, java.lang.String name)
          Define end of a script (test case).
 int scriptStart(java.lang.String number)
          Define start of a script (test case).
 int scriptStart(java.lang.String number, java.lang.String name)
          Define start of a script (test case).
 int sendMail(java.lang.String subject, java.lang.String text)
          Send an E-mail of the specified subject and text to one or more recipients through an SMTP server which requires no authentication.
 int sendMail(java.lang.String subject, java.lang.String text, java.io.File[] attachments)
          Send an E-mail of the specified subject, text and optional file attachments to one or more recipients through an SMTP server which requires no authentication.
 int sendMail(java.lang.String password, java.lang.String subject, java.lang.String text)
          Send an E-mail of the specified subject and text to one or more recipients through an SMTP server.
 int sendMail(java.lang.String password, java.lang.String subject, java.lang.String text, java.io.File[] attachments, boolean debug)
          Send an E-mail of the specified subject, text and optional file attachments to one or more recipients through an SMTP server.
 int sendMail(java.lang.String server, java.lang.String user, java.lang.String password, java.lang.String from, java.lang.String to, java.lang.String subject, java.lang.String text, java.io.File[] attachments, boolean debug)
          Send an E-mail of the specified subject, text and optional file attachments to one or more recipients through an SMTP server.
 void setOutputDir(java.lang.String dir)
          Set the output path.
 void setTemplateDir(java.lang.String dir)
          Set the template path.
 int setVariable(java.lang.String... params)
           Set one or more context variables.
 int step(java.lang.String name, java.lang.String result, java.lang.String instructions, java.lang.String expected, java.lang.String actual, java.lang.String notes)
          Define result of a particular test step.
 int stepFail(java.lang.String name, java.lang.String instructions)
          Define a failed (unsuccessful) test step.
 int stepFailed(java.lang.String name, java.lang.String instructions, java.lang.String expected, java.lang.String actual, java.lang.String notes)
          Define a failed (unsuccessful) test step.
 int stepNotAvailable(java.lang.String name, java.lang.String instructions, java.lang.String expected, java.lang.String actual, java.lang.String notes)
          Define a test step whose result is not available.
 int stepNotTested(java.lang.String name, java.lang.String instructions, java.lang.String expected, java.lang.String actual, java.lang.String notes)
          Define a test step which was not (yet) tested.
 int stepPassed(java.lang.String name, java.lang.String instructions)
          Define a passed (successful) test step.
 int stepPassed(java.lang.String name, java.lang.String instructions, java.lang.String expected, java.lang.String actual, java.lang.String notes)
          Define a passed (successful) test step.
 int stringIndexOf(java.lang.String text, java.lang.String string)
          The method provides access to functionality of the String indexof command.
 int stringIndexOf(java.lang.String text, java.lang.String string, int start, int end, java.lang.String variableName)
          The method provides access to functionality of the String indexof command.
 int stringIndexOf(java.lang.String text, java.lang.String string, java.lang.String variableName)
          The method provides access to functionality of the String indexof command.
 int stringLength(java.lang.String text)
          The method provides access to functionality of the String length command.
 int stringLength(java.lang.String text, java.lang.String variableName)
          The method provides access to functionality of the String length command.
 int stringMatches(java.lang.String text, java.lang.String pattern)
          The method provides access to functionality of the String matches command.
 int stringMatches(java.lang.String text, java.lang.String pattern, java.lang.String variableName)
          The method provides access to functionality of the String matches command.
 int stringReplace(java.lang.String text, java.lang.String string, java.lang.String replacement)
          The method provides access to functionality of the String replace command.
 int stringReplace(java.lang.String text, java.lang.String string, java.lang.String replacement, java.lang.String variableName)
          The method provides access to functionality of the String replace command.
 int stringReplacePattern(java.lang.String text, java.lang.String pattern, java.lang.String replacement)
          The method provides access to functionality of the String replace command.
 int stringReplacePattern(java.lang.String text, java.lang.String pattern, java.lang.String replacement, java.lang.String variableName)
          The method provides access to functionality of the String replace command.
 int stringSplit(java.lang.String text, java.lang.String delimeter)
          The method provides access to functionality of the String split command.
 int stringSplit(java.lang.String text, java.lang.String delimeter, java.lang.String variableName)
          The method provides access to functionality of the String split command.
 int stringSplitByPattern(java.lang.String text, java.lang.String pattern)
          The method provides access to functionality of the String split command.
 int stringSplitByPattern(java.lang.String text, java.lang.String pattern, java.lang.String variableName)
          The method provides access to functionality of the String split command.
 int stringSubstring(java.lang.String text, java.lang.Integer start, java.lang.Integer end)
          The method provides access to functionality of the String substring command.
 int stringSubstring(java.lang.String text, java.lang.Integer start, java.lang.Integer end, java.lang.String variableName)
          The method provides access to functionality of the String substring command.
 int stringToString(java.lang.String codeList)
          The method provides access to functionality of the String tostring command.
 int stringToString(java.lang.String codeList, java.lang.String variableName)
          The method provides access to functionality of the String tostring command.
 int stringTrim(java.lang.String text, java.lang.String variableName)
          The method provides access to functionality of the String trim command.
 void test()
          Empty test method implementing the JavaTestScript interface.
 int timer(java.lang.String names, java.lang.String description)
          Create and/or configure timer(s).
 int timer(java.lang.String names, java.lang.String description, long value, long referenceValue)
          Create and/or configure timer(s).
 int timer(java.lang.String names, java.lang.String description, long value, long referenceValue, java.lang.String group, java.lang.String ungroup, java.io.File referenceFile)
          Create and/or configure timer(s) and/or timer groups.
 int timerGroup(java.lang.String names, java.lang.String group)
          Associate timer(s) with a timer group or groups.
 int timerLoad(java.io.File referenceFile)
          The method loads Timer reference data from an XML file previously generated through the Report command (see also report(java.io.File)).
 int timerStart(java.lang.String names)
          Start timer(s).
 int timerStart(java.lang.String names, java.lang.String description, long value, long referenceValue, java.lang.String group, java.lang.String ungroup)
          Create and/or configure timer(s) and/or timer groups and start it (them).
 int timerStop(java.lang.String names)
          Stop timer(s) and/or timer groups.
 int timerStop(java.lang.String names, java.lang.String description, long value, long referenceValue, java.lang.String group, java.lang.String ungroup)
          Stop timer(s) and/or timer groups.
 int timerUngroup(java.lang.String names, java.lang.String ungroup)
          Remove timer(s) from a timer group or groups.
 int type(java.lang.String text)
          Type a text on the current desktop.
 int type(java.lang.String text, int count, int location, java.lang.String wait)
          Type a text on the current desktop.
 int type(java.lang.String text, int count, java.lang.String wait)
          Type a text on the current desktop.
 int type(java.lang.String text, java.lang.String wait)
          Type a text on the current desktop.
 int typeLine(java.lang.String text)
          Type a text and press an Enter key on the current desktop.
 int typeLine(java.lang.String text, int count, int location, java.lang.String wait)
          Type a text and press an Enter key on the current desktop once or more times.
 int typeLine(java.lang.String text, int count, java.lang.String wait)
          Type a text and press an Enter key on the current desktop once or more times.
 int typeLine(java.lang.String text, java.lang.String wait)
          Type a text and press an Enter key on the current desktop.
 int wait(java.lang.String time)
          Postpone execution of the test script for the specified time period.
 int waitForBell(int count, java.lang.String timeout, java.lang.String wait)
          Wait until the remote desktop emits one or more beeps (bells).
 int waitForBell(java.lang.String timeout)
          Wait until the remote desktop beeps (rings a bell).
 int waitForBell(java.lang.String timeout, java.lang.String wait)
          Wait until the remote desktop beeps (rings a bell).
 int waitForClipboard(java.lang.String timeout)
           
 int waitForClipboard(java.lang.String timeout, java.lang.String wait)
          
 int waitForMatch(java.io.File[] templates)
          Pause the script indefinitely until the default image comparison method produces a positive result for at least one of the template.
 int waitForMatch(java.io.File[] templates, float passRate, java.awt.Rectangle cmpArea, java.lang.String interval, java.lang.String timeout, java.lang.String text, int distance, java.lang.String pattern, java.lang.String wait)
          Pause the script until the text recognized through the Image Based Text Recognition comparison method contains a string or matches a regular expression or until the time out limit is reached.
 int waitForMatch(java.io.File[] templates, float passRate, java.lang.String interval, java.awt.Rectangle cmpArea, java.lang.String timeout, boolean removeBg, java.lang.String bgColor, java.lang.Integer minAlpha, java.lang.Integer rgbTolerance, java.lang.String wait)
          Pause the script until the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached.
 int waitForMatch(java.io.File[] templates, float passRate, java.lang.String interval, java.awt.Rectangle cmpArea, java.lang.String timeout, boolean removeBg, java.lang.String bgColor, java.lang.Integer minAlpha, java.lang.String wait)
          Pause the script until the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached.
 int waitForMatch(java.io.File[] templates, float passRate, java.lang.String method, java.awt.Rectangle cmpArea, java.lang.String timeout, java.lang.String wait)
           
 int waitForMatch(java.io.File[] templates, float passRate, java.lang.String interval, java.awt.Rectangle cmpArea, java.lang.String timeout, java.lang.String sort, float[] scale, java.lang.String wait)
          Pause the script until the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached.
 int waitForMatch(java.io.File[] templates, float passRate, java.lang.String interval, java.awt.Rectangle cmpArea, java.lang.String timeout, java.lang.String sort, java.lang.String wait)
          Pause the script until the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached.
 int waitForMatch(java.io.File[] templates, float passRate, java.lang.String method, java.lang.String timeout)
           
 int waitForMatch(java.io.File[] templates, float passRate, java.lang.String interval, java.lang.String method, java.lang.String methodParams, java.awt.Rectangle cmpArea, java.lang.String timeout, java.lang.String wait)
          Pause the script until the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached.
 int waitForMatch(java.io.File[] templates, java.lang.String timeout)
           
 int waitForMatch(java.io.File[] templates, java.lang.String method, java.lang.String timeout)
           
 int waitForMatch(java.io.File template, float passRate, java.lang.String interval, java.awt.Rectangle cmpArea, java.lang.String timeout, java.awt.Color color, java.awt.Color[] bridgeColors, java.lang.Integer rgbTolerance, java.lang.Integer rotations, java.lang.Boolean draw, java.lang.Boolean clear, java.lang.String wait)
          Pause the script until the current remote desktop contains at least one object located by the Object Search image comparison method.
 int waitForMatch(java.awt.Image[] templates, float passRate, java.lang.String interval, java.awt.Rectangle cmpArea, java.lang.String timeout, boolean removeBg, java.lang.String bgColor, java.lang.Integer minAlpha, java.lang.Integer rgbTolerance, java.lang.String wait)
          Pause the script until the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached.
 int waitForMatch(java.awt.Image[] templates, float passRate, java.lang.String interval, java.awt.Rectangle cmpArea, java.lang.String timeout, boolean removeBg, java.lang.String bgColor, java.lang.Integer minAlpha, java.lang.String wait)
          Pause the script until the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached.
 int waitForMatch(java.awt.Image[] templates, float passRate, java.lang.String interval, java.lang.String method, java.lang.String methodParams, java.awt.Rectangle cmpArea, java.lang.String timeout, java.lang.String wait)
          Pause the script until the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached.
 int waitForMatch(java.awt.Image template, float passRate, java.lang.String interval, java.awt.Rectangle cmpArea, java.lang.String timeout, java.awt.Color color, java.awt.Color[] bridgeColors, java.lang.Integer rgbTolerance, java.lang.Integer rotations, java.lang.Boolean draw, java.lang.Boolean clear, java.lang.String wait)
          Pause the script until the current remote desktop contains at least one object located by the Object Search image comparison method.
 int waitForMatch(java.lang.String interval, java.awt.Rectangle cmpArea, java.lang.String timeout, java.lang.String language, float scale, java.lang.String text, int distance, java.lang.String pattern, int mode, int filter, int fontSize, java.lang.String wait)
          Pause the script until the text recognized through Tesseract OCR contains a string or matches a regular expression or until the time out limit is reached.
 int waitForMatch(java.lang.String interval, java.awt.Rectangle cmpArea, java.lang.String timeout, java.lang.String language, float scale, java.lang.String text, int distance, java.lang.String pattern, java.lang.String wait)
          Pause the script until the text recognized through Tesseract OCR contains a string or matches a regular expression or until the time out limit is reached.
 int waitForMatch(java.lang.String interval, java.awt.Rectangle cmpArea, java.lang.String timeout, java.lang.String language, java.lang.String text, java.lang.String pattern, java.lang.String wait)
          Pause the script until the text recognized through Tesseract OCR contains a string or matches a regular expression or until the time out limit is reached.
 int waitForMismatch(java.io.File[] templates)
          Wait as long as at least one of the specified template images matches the screen.
 int waitForMismatch(java.io.File[] templates, float passRate, java.awt.Rectangle cmpArea, java.lang.String interval, java.lang.String timeout, java.lang.String text, int distance, java.lang.String pattern, java.lang.String wait)
          Pause the script as long as the text recognized through the Image Based Text Recognition comparison method contains a string or matches a regular expression or until the time out limit is reached.
 int waitForMismatch(java.io.File[] templates, float passRate, java.lang.String interval, java.awt.Rectangle cmpArea, java.lang.String timeout, boolean removeBg, java.lang.String bgColor, java.lang.Integer minAlpha, java.lang.Integer rgbTolerance, java.lang.String wait)
          Pause the script as long as the specified image comparison method produces a positive result for at least one of the templates or until the time out limit is reached.
 int waitForMismatch(java.io.File[] templates, float passRate, java.lang.String interval, java.awt.Rectangle cmpArea, java.lang.String timeout, boolean removeBg, java.lang.String bgColor, java.lang.Integer minAlpha, java.lang.String wait)
          Pause the script as long as the specified image comparison method produces a positive result for at least one of the templates or until the time out limit is reached.
 int waitForMismatch(java.io.File[] templates, float passRate, java.lang.String method, java.awt.Rectangle cmpArea, java.lang.String timeout, java.lang.String wait)
           
 int waitForMismatch(java.io.File[] templates, float passRate, java.lang.String interval, java.awt.Rectangle cmpArea, java.lang.String timeout, java.lang.String sort, float[] scale, java.lang.String wait)
          Pause the script as long as the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached.
 int waitForMismatch(java.io.File[] templates, float passRate, java.lang.String interval, java.awt.Rectangle cmpArea, java.lang.String timeout, java.lang.String sort, java.lang.String wait)
          Pause the script as long as the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached.
 int waitForMismatch(java.io.File[] templates, float passRate, java.lang.String method, java.lang.String timeout)
           
 int waitForMismatch(java.io.File[] templates, float passRate, java.lang.String interval, java.lang.String method, java.lang.String methodParams, java.awt.Rectangle cmpArea, java.lang.String timeout, java.lang.String wait)
          Pause the script as long as the specified image comparison method produces a positive result for at least one of the templates or until the time out limit is reached.
 int waitForMismatch(java.io.File[] templates, java.lang.String timeout)
           
 int waitForMismatch(java.io.File[] templates, java.lang.String method, java.lang.String timeout)
           
 int waitForMismatch(java.io.File template, float passRate, java.lang.String interval, java.awt.Rectangle cmpArea, java.lang.String timeout, java.awt.Color color, java.awt.Color[] bridgeColors, java.lang.Integer rgbTolerance, java.lang.Integer rotations, java.lang.Boolean draw, java.lang.Boolean clear, java.lang.String wait)
          Pause the script as long as the current remote desktop contains at least one object located by the Object Search image comparison method.
 int waitForMismatch(java.awt.Image[] templates, float passRate, java.lang.String interval, java.awt.Rectangle cmpArea, java.lang.String timeout, boolean removeBg, java.lang.String bgColor, java.lang.Integer minAlpha, java.lang.Integer rgbTolerance, java.lang.String wait)
          Pause the script as long as the specified image comparison method produces a positive result for at least one of the templates or until the time out limit is reached.
 int waitForMismatch(java.awt.Image[] templates, float passRate, java.lang.String interval, java.awt.Rectangle cmpArea, java.lang.String timeout, boolean removeBg, java.lang.String bgColor, java.lang.Integer minAlpha, java.lang.String wait)
          Pause the script as long as the specified image comparison method produces a positive result for at least one of the templates or until the time out limit is reached.
 int waitForMismatch(java.awt.Image[] templates, float passRate, java.lang.String interval, java.lang.String method, java.lang.String methodParams, java.awt.Rectangle cmpArea, java.lang.String timeout, java.lang.String wait)
          Pause the script as long as the specified image comparison method produces a positive result for at least one of the templates or until the time out limit is reached.
 int waitForMismatch(java.awt.Image template, float passRate, java.lang.String interval, java.awt.Rectangle cmpArea, java.lang.String timeout, java.awt.Color color, java.awt.Color[] bridgeColors, java.lang.Integer rgbTolerance, java.lang.Integer rotations, java.lang.Boolean draw, java.lang.Boolean clear, java.lang.String wait)
          Pause the script as long as the current remote desktop contains at least one object located by the Object Search image comparison method.
 int waitForMismatch(java.lang.String interval, java.awt.Rectangle cmpArea, java.lang.String timeout, java.lang.String language, float scale, java.lang.String text, int distance, java.lang.String pattern, int mode, int filter, int fontSize, java.lang.String wait)
          Pause the script as long as the text recognized through Tesseract OCR contains a string or matches a regular expression or until the time out limit is reached.
 int waitForMismatch(java.lang.String interval, java.awt.Rectangle cmpArea, java.lang.String timeout, java.lang.String language, float scale, java.lang.String text, int distance, java.lang.String pattern, java.lang.String wait)
          Pause the script as long as the text recognized through Tesseract OCR contains a string or matches a regular expression or until the time out limit is reached.
 int waitForMismatch(java.lang.String interval, java.awt.Rectangle cmpArea, java.lang.String timeout, java.lang.String language, java.lang.String text, java.lang.String pattern, java.lang.String wait)
          Pause the script as long as the text recognized through Tesseract OCR contains a string or matches a regular expression or until the time out limit is reached.
 int waitForUpdate(java.awt.Rectangle area, java.lang.String extent, boolean cumulative, java.lang.String timeout, java.lang.String wait)
          Wait until the remote desktop refreshes the screen or its particular area.
 int waitForUpdate(java.awt.Rectangle area, java.lang.String extent, java.lang.String timeout)
          Wait until the remote desktop refreshes the screen or its particular area.
 int waitForUpdate(java.awt.Rectangle area, java.lang.String extent, java.lang.String timeout, java.lang.String wait)
          Wait until the remote desktop refreshes the screen or its particular area.
 int waitForUpdate(java.lang.String extent, java.lang.String timeout)
          Wait until the remote desktop refreshes the whole screen.
 int warning(java.lang.String text)
          Add a warning to be picked up by a report provider.
 int warning(java.lang.String text, java.io.File image)
          Add a warning to be picked up by a report provider.
 
Methods inherited from class com.tplan.robot.scripting.AbstractJavaTestScript
callByName, getContext, getDocument, getLineNumber, getLineNumber, getOutputDir, getParentWrapper, getScriptFile, getScriptManager, getTemplateDir, getTestSource, getVariable, getVariableAsBoolean, getVariableAsColor, getVariableAsFloat, getVariableAsInt, getVariableAsPoint, getVariableAsRectangle, getVariableAsString, getWrapperType, importVariables, isDebug, isPaused, mouseEvent, resume, runScriptCommand, setContext, setDebug, setDocument, setInterpret, setTestSource, setVariable, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

DefaultJavaTestScript

public DefaultJavaTestScript()
Method Detail

test

public void test()
Empty test method implementing the JavaTestScript interface. Override this method with your own test code to create a Java test script.


getRootWrapper

public TestWrapper getRootWrapper()

connect

public int connect(java.lang.String host,
                   java.lang.String user,
                   java.lang.String password,
                   java.util.Map<java.lang.String,java.lang.Object> params,
                   boolean force)
            throws java.io.IOException

Connect to a desktop. This method has the same functionality as the connect(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, boolean) one save that it allows to specify custom parameters through a map of objects. This is useful for programmatic connections to a desktop whose client requires a custom parameter which has other than String value.

Parameters:
host - host connection URI. It can not be null. See the method description for information about its format.
user - user name for plain text password authentication. It may be null for servers which do not require this authentication scheme.
password - password for plain text password authentication. It may be null for servers which do not require this authentication scheme.
params - custom client parameters in form of a map with [param_name, param_value] pairs. Note that this is a generic mechanism to allow future plugins of clients which use custom ways of authentication and login parameters. The two built in RFB and Java clients do not support at the moment any custom parameters.
force - true will force reconnection even if the tool is already connected to the same server. A value of false will cause the method to check whether a connection to the specified server already exists and connect only in case it is not so. Default value is false.
Returns:
command exit code as is specified in the Connect specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

connect

public int connect(java.lang.String host,
                   java.lang.String user,
                   java.lang.String password,
                   java.lang.String params,
                   java.lang.String paramSeparator,
                   boolean force)
            throws java.io.IOException

Connect to a desktop. The method provides access to functionality of the Connect scripting language command. The host argument must be a valid URL in form of <protocol>://<host_or_IP>[:<port>] where the protocol must be equal to one of the installed client plugin codes. If port is not explicitly specified, it defaults to the default protocol-specific port provided by the RemoteDesktopClient.getDefaultPort() method. For more information on host string format see documentation of particular desktop clients.

If protocol is omitted in the URL, the host defaults to the RFB (VNC) protocol to provide backward compatibility with VNCRobot 1.x. Port number is in this case considered to be a display number rather than real port. To get a real port take the display number and add it to 5900 which is the default RFB port. Direct port can be in this mode specified through double colon, for example both "localhost:1" and "localhost::5901" refer to the same local VNC server running on port 5901. To specify the same address in the standard URL form one has to list the real port specifically and the equivalent URL is "rfb://localhost:5901".

The connect method supports by default just servers with either none or plain user/password authentication. Both user and password parameters may be also passed through CLI or programmatically among parameters of the ApplicationSupport.createAutomatedRunnable(com.tplan.robot.scripting.JavaTestScript, java.lang.String, java.lang.String[], java.io.PrintStream, boolean) method. Clients which use custom authentication schemes must use a different ways of passing custom connection parameters to the script, such as script variables (specified from CLI using -v/--variable and available during script execution through getContext().getVariable()). An alternative way is to use the framework of user preferences together with the -o/--option CLI switch.

As the connection mechanism was enhanced with connection pooling since version 2.2, the method may but doesn't necessarily have to create a new client and go through the connection sequence depending on whether the pooling mode is on and there's a free already connected client available. Read more about connection pooling in the RemoteDesktopClientFactory class.

Note that the method doesn't throw any exception on standard situations, such as failures to connect or authenticate. These cases are reported through the return value which should be checked by the script. If a value other than zero is returned to report failure, the connect exception may be obtained through the ScriptingContext.getConnectError() method. The IOException declared by this method is thrown only on unrecognized I/O errors which may happen during the initialization of the connection, for example an intermittent network failure.

Examples:

Parameters:
host - host connection URI. It can not be null. See the method description for information about its format.
user - user name for plain text password authentication. It may be null for servers which do not require this authentication scheme.
password - password for plain text password authentication. It may be null for servers which do not require this authentication scheme.
params - custom client parameters. Through the client framework supports by default just URI (protocol+host+port), user name and password parameters, this parameter allows to pass any custom parameter to a custom client. The list may contain any number of parameter name and value pairs separated by comma (',') or a custom separator specified by the paramSeparator argument. For example, to specify two parameters PARAM_A=value_A and PARAM_B=valueB the argument should look like "PARAM_A,valueA,PARAM_B,valueB". Note that this is a generic mechanism to allow future plugins of clients which use custom ways of authentication and login parameters. The two built in RFB and Java clients do not support at the moment any custom parameters.
paramSeparator - optional separator for the list of parameter names and values specified by the params argument. If it is null, it defaults to comma (",").
force - true will force reconnection even if the tool is already connected to the same server. A value of false will cause the method to check whether a connection to the specified server already exists and connect only in case it is not so. Default value is false.
Returns:
command exit code as is specified in the Connect specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

connect

public int connect(java.lang.String host,
                   java.lang.String user,
                   java.lang.String password,
                   boolean force)
            throws java.io.IOException

Connect to a server using the specified user and password. As this is just a convenience method calling the connect(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, boolean) one, see its documentation for a complete description of the method behavior.

Parameters:
host - host connection URI. It can not be null. See the connect(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, boolean) method description for information about its format.
user - user name for plain text password authentication. It may be null for servers which do not require this authentication scheme.
password - password for plain text password authentication. It may be null for servers which do not require this authentication scheme.
force - true will force reconnection even if the tool is already connected to the same server. A value of false will cause the method to check whether a connection to the specified server already exists and connect only in case it is not so. Default value is false.
Returns:
command exit code as is specified in the Connect specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

connect

public int connect(java.lang.String host,
                   java.lang.String password)
            throws java.io.IOException

Connect to a server which may or may not require a password. This is typical for RFB (VNC) servers which support none or just password (without user name) authentication schemes. If the connection already exists, do not reconnect (force=false).

As this is just a convenience method calling the connect(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, boolean) one, see its documentation for a complete description of the method behavior.

Parameters:
host - host connection URI. It can not be null. See the connect(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, boolean) method description for information about its format.
password - password for plain text password authentication. It may be null for servers which do not require this authentication scheme.
Returns:
command exit code as is specified in the Connect specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

connect

public int connect(java.lang.String host,
                   boolean force)
            throws java.io.IOException

Connect to a server which requires no authentication (for example a Java client or an RFB/VNC server which is configured this way).

As this is just a convenience method calling the connect(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, boolean) one, see its documentation for a complete description of the method behavior.

Parameters:
host - host connection URI. It can not be null. See the connect(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, boolean) method description for information about its format.
force - true will force reconnection even if the tool is already connected to the same server. A value of false will cause the method to check whether a connection to the specified server already exists and connect only in case it is not so. Default value is false.
Returns:
command exit code as is specified in the Connect specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

connect

public int connect(java.lang.String host)
            throws java.io.IOException

Connect to a server which requires no authentication (for example a Java client or an RFB/VNC server which is configured this way). If the connection already exists, do not reconnect (force=false).

As this is just a convenience method calling the connect(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, boolean) one, see its documentation for a complete description of the method behavior.

Parameters:
host - host connection URI. It can not be null. See the connect(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, boolean) method description for information about its format.
Returns:
command exit code as is specified in the Connect specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

disconnect

public int disconnect()
               throws java.io.IOException

Disconnect from a desktop. The method provides access to functionality of the Disconnect scripting language command. If there's a connection to a desktop, it gets closed through RemoteDesktopClient.close(). If the tool is not connected to any desktop the method does nothing.

Returns:
command exit code as is specified in the Disconnect specification.
Throws:
java.io.IOException - if an I/O error happens during the connection shutdown.

mouseEvent

public int mouseEvent(java.lang.String action,
                      int modifiers,
                      int button,
                      java.awt.Point from,
                      java.awt.Point to,
                      int count,
                      java.lang.String wait)
               throws java.io.IOException

Perform a generic mouse action on the currently connected desktop. The method provides access to functionality of the Mouse scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
action - mouse action string as is defined in the Mouse command specification. Supported values are move, click, drag, press, release, wheelup and wheeldown. The action codes are not case sensitive.
modifiers - modifier mask as specified in the InputEvent. For example, to specify Ctrl+Alt use InputEvent.CTRL_MASK | InputEvent.ALT_MASK
button - mouse button ID as specified in MouseEvent. Supported values are MouseEvent.BUTTON1 (left button), MouseEvent.BUTTON2 (middle button) and MouseEvent.BUTTON3 (right button). If any other value is used, the argument defaults to the left button. This argument applies only to mouse events which involve buttons, such as mouse click, press, release and drag.
from - start point of a mouse move or drag event. If the argument is null, it defaults to the current desktop mouse pointer position. The value is ignored by other actions.
to - location or target point of the mouse event. If the argument is null, it defaults to the current desktop mouse pointer position.
count - how many times to repeat the event. It applies only to mouse clicks and wheel events and it is ignored by other ones. Default value is 1 (one). Delays among multiple clicks are defined by a value in the Mouse command user preferences.
wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication or if no desktop is connected.

mouseMove

public int mouseMove(java.awt.Point to,
                     java.lang.String wait)
              throws java.io.IOException

Perform a mouse move on the currently connected desktop. The method provides access to functionality of the Mouse move scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
to - location or target point of the mouse event. If the argument is null, it defaults to the current desktop mouse pointer position.
wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

mouseMove

public int mouseMove(java.awt.Point to,
                     int modifiers,
                     java.lang.String wait)
              throws java.io.IOException

Perform a mouse move on the currently connected desktop with optional modifier key(s) pressed. The method provides access to functionality of the Mouse move scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
to - location or target point of the mouse event. If the argument is null, it defaults to the current desktop mouse pointer position.
modifiers - modifier mask as specified in the InputEvent. For example, to specify Ctrl+Alt use InputEvent.CTRL_MASK | InputEvent.ALT_MASK
wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

mouseMove

public int mouseMove(java.awt.Point to)
              throws java.io.IOException

Perform a mouse move on the currently connected desktop. The method provides access to functionality of the Mouse move scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
to - location or target point of the mouse event. If the argument is null, it defaults to the current desktop mouse pointer position.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

mouseMove

public int mouseMove(int x,
                     int y,
                     java.lang.String wait)
              throws java.io.IOException

Perform a mouse move on the currently connected desktop. The method provides access to functionality of the Mouse move scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
x - X-coordinate of location or target point of the mouse event. If the argument is negative, it defaults to the current desktop mouse pointer X-coordinate value.
y - Y-coordinate of location or target point of the mouse event. If the argument is negative, it defaults to the current desktop mouse pointer Y-coordinate value.
wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

mouseMove

public int mouseMove(int x,
                     int y,
                     int modifiers,
                     java.lang.String wait)
              throws java.io.IOException

Perform a mouse move on the currently connected desktop with optional modifier key(s) pressed. The method provides access to functionality of the Mouse move scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
x - X-coordinate of location or target point of the mouse event. If the argument is negative, it defaults to the current desktop mouse pointer X-coordinate value.
y - Y-coordinate of location or target point of the mouse event. If the argument is negative, it defaults to the current desktop mouse pointer Y-coordinate value.
modifiers - modifier mask as specified in the InputEvent. For example, to specify Ctrl+Alt use InputEvent.CTRL_MASK | InputEvent.ALT_MASK
wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

mouseMove

public int mouseMove(int x,
                     int y)
              throws java.io.IOException

Perform a mouse move on the currently connected desktop. The method provides access to functionality of the Mouse move scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
x - X-coordinate of location or target point of the mouse event. If the argument is negative, it defaults to the current desktop mouse pointer X-coordinate value.
y - Y-coordinate of location or target point of the mouse event. If the argument is negative, it defaults to the current desktop mouse pointer Y-coordinate value.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

mouseClick

public int mouseClick(java.awt.Point to,
                      int modifiers,
                      int button,
                      int count,
                      java.lang.String wait)
               throws java.io.IOException

Perform left mouse click(s) on the currently connected desktop. The method provides access to functionality of the Mouse click button=left scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
to - mouse click point. If the argument is null, it defaults to the current desktop mouse pointer position.
modifiers - modifier mask as specified in the InputEvent. For example, to specify Ctrl+Alt use InputEvent.CTRL_MASK | InputEvent.ALT_MASK
button - mouse button ID as specified in MouseEvent. Supported values are MouseEvent.BUTTON1 (left button), MouseEvent.BUTTON2 (middle button) and MouseEvent.BUTTON3 (right button). If any other value is used, the argument defaults to the left button. This argument applies only to mouse events which involve buttons, such as mouse click, press, release and drag.
count - how many times to click. Default value is 1 (one click). Delays among multiple clicks are defined by a value in the Mouse command user preferences.
wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

mouseClick

public int mouseClick(java.awt.Point to,
                      int count,
                      java.lang.String wait)
               throws java.io.IOException

Perform left mouse click(s) on the currently connected desktop. The method provides access to functionality of the Mouse click button=left scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

The method was introduced in the 3.0 release to allow the script recorder to produce shorter and better readable code.

Parameters:
to - location or target point of the mouse event. If the argument is null, it defaults to the current desktop mouse pointer position.
count - how many times to click. Default value is 1 (one click). Delays among multiple clicks are defined by a value in the Mouse command user preferences.
wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.
Since:
3.0

mouseClick

public int mouseClick(java.awt.Point to,
                      int count)
               throws java.io.IOException

Perform left mouse click(s) on the currently connected desktop. The method provides access to functionality of the Mouse click button=left scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
to - location or target point of the mouse event. If the argument is null, it defaults to the current desktop mouse pointer position.
count - how many times to click. Default value is 1 (one click). Delays among multiple clicks are defined by a value in the Mouse command user preferences.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

mouseClick

public int mouseClick(java.awt.Point to,
                      java.lang.String wait)
               throws java.io.IOException

Perform a single left mouse click on the currently connected desktop. The method provides access to functionality of the Mouse click button=left scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
to - location or target point of the mouse event. If the argument is null, it defaults to the current desktop mouse pointer position.
wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

mouseClick

public int mouseClick(java.awt.Point to)
               throws java.io.IOException

Perform a single left mouse click on the currently connected desktop. The method provides access to functionality of the Mouse click button=left scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
to - location or target point of the mouse event. If the argument is null, it defaults to the current desktop mouse pointer position.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

mouseClick

public int mouseClick(int x,
                      int y,
                      int count,
                      java.lang.String wait)
               throws java.io.IOException

Perform left mouse click(s) on the currently connected desktop. The method provides access to functionality of the Mouse click button=left scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
x - X-coordinate of location or target point of the mouse event. If the argument is negative, it defaults to the current desktop mouse pointer X-coordinate value.
y - Y-coordinate of location or target point of the mouse event. If the argument is negative, it defaults to the current desktop mouse pointer Y-coordinate value.
count - how many times to click. Default value is 1 (one click). Delays among multiple clicks are defined by a value in the Mouse command user preferences.
wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

mouseClick

public int mouseClick(int x,
                      int y,
                      int count)
               throws java.io.IOException

Perform left mouse click(s) on the currently connected desktop. The method provides access to functionality of the Mouse click button=left scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
x - X-coordinate of location or target point of the mouse event. If the argument is negative, it defaults to the current desktop mouse pointer X-coordinate value.
y - Y-coordinate of location or target point of the mouse event. If the argument is negative, it defaults to the current desktop mouse pointer Y-coordinate value.
count - how many times to click. Default value is 1 (one click). Delays among multiple clicks are defined by a value in the Mouse command user preferences.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

mouseClick

public int mouseClick(int x,
                      int y)
               throws java.io.IOException

Perform a single left mouse click on the currently connected desktop. The method provides access to functionality of the Mouse click button=left scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
x - X-coordinate of location or target point of the mouse event. If the argument is negative, it defaults to the current desktop mouse pointer X-coordinate value.
y - Y-coordinate of location or target point of the mouse event. If the argument is negative, it defaults to the current desktop mouse pointer Y-coordinate value.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

mouseRightClick

public int mouseRightClick(java.awt.Point to,
                           int modifiers,
                           int count,
                           java.lang.String wait)
                    throws java.io.IOException

Perform right mouse click(s) on the currently connected desktop. The method provides access to functionality of the Mouse click btn=right scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
to - mouse click point. If the argument is null, it defaults to the current desktop mouse pointer position.
modifiers - modifier mask as specified in the InputEvent. For example, to specify Ctrl+Alt use InputEvent.CTRL_MASK | InputEvent.ALT_MASK
count - how many times to click. Default value is 1 (one click). Delays among multiple clicks are defined by a value in the Mouse command user preferences.
wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

mouseRightClick

public int mouseRightClick(java.awt.Point to,
                           int count,
                           java.lang.String wait)
                    throws java.io.IOException

Perform right mouse click(s) on the currently connected desktop. The method provides access to functionality of the Mouse click btn=right scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
to - mouse click point. If the argument is null, it defaults to the current desktop mouse pointer position.
count - how many times to click. Default value is 1 (one click). Delays among multiple clicks are defined by a value in the Mouse command user preferences.
wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

mouseRightClick

public int mouseRightClick(java.awt.Point to,
                           int count)
                    throws java.io.IOException

Perform right mouse click(s) on the currently connected desktop. The method provides access to functionality of the Mouse click btn=right scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
to - mouse click point. If the argument is null, it defaults to the current desktop mouse pointer position.
count - how many times to click. Default value is 1 (one click). Delays among multiple clicks are defined by a value in the Mouse command user preferences.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

mouseRightClick

public int mouseRightClick(java.awt.Point to)
                    throws java.io.IOException

Perform a single right mouse click on the currently connected desktop. The method provides access to functionality of the Mouse click btn=right scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
to - mouse click point. If the argument is null, it defaults to the current desktop mouse pointer position.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

mouseRightClick

public int mouseRightClick(int x,
                           int y,
                           int count,
                           java.lang.String wait)
                    throws java.io.IOException

Perform right mouse click(s) on the currently connected desktop. The method provides access to functionality of the Mouse click btn=right scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
x - X-coordinate of the click point. If the argument is negative, it defaults to the current desktop mouse pointer X-coordinate value.
y - Y-coordinate of the click point. If the argument is negative, it defaults to the current desktop mouse pointer Y-coordinate value.
count - how many times to click. Default value is 1 (one click). Delays among multiple clicks are defined by a value in the Mouse command user preferences.
wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

mouseRightClick

public int mouseRightClick(int x,
                           int y,
                           int count)
                    throws java.io.IOException

Perform right mouse click(s) on the currently connected desktop. The method provides access to functionality of the Mouse click btn=right scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
x - X-coordinate of the click point. If the argument is negative, it defaults to the current desktop mouse pointer X-coordinate value.
y - Y-coordinate of the click point. If the argument is negative, it defaults to the current desktop mouse pointer Y-coordinate value.
count - how many times to click. Default value is 1 (one click). Delays among multiple clicks are defined by a value in the Mouse command user preferences.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

mouseRightClick

public int mouseRightClick(int x,
                           int y)
                    throws java.io.IOException

Perform a single right mouse click on the currently connected desktop. The method provides access to functionality of the Mouse click btn=right scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
x - X-coordinate of the click point. If the argument is negative, it defaults to the current desktop mouse pointer X-coordinate value.
y - Y-coordinate of the click point. If the argument is negative, it defaults to the current desktop mouse pointer Y-coordinate value.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

mouseDoubleClick

public int mouseDoubleClick(java.awt.Point to,
                            java.lang.String wait)
                     throws java.io.IOException
Perform a double left mouse click on the current desktop client. The method provides access to functionality of the Mouse click button=left count=2 scripting language command.

Perform a double left mouse click on the currently connected desktop. The method provides access to functionality of the Mouse click button=left count=2 scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
to - mouse click point. If the argument is null, it defaults to the current desktop mouse pointer position.
wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

mouseDoubleClick

public int mouseDoubleClick(java.awt.Point to)
                     throws java.io.IOException
Perform a double left mouse click on the current desktop client. The method provides access to functionality of the Mouse click button=left count=2 scripting language command.

Perform a double left mouse click on the currently connected desktop. The method provides access to functionality of the Mouse click button=left count=2 scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
to - mouse click point. If the argument is null, it defaults to the current desktop mouse pointer position.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

mouseDoubleClick

public int mouseDoubleClick(int x,
                            int y,
                            java.lang.String wait)
                     throws java.io.IOException

Perform a double left mouse click on the currently connected desktop. The method provides access to functionality of the Mouse click button=left count=2 scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
x - X-coordinate of the click point. If the argument is negative, it defaults to the current desktop mouse pointer X-coordinate value.
y - Y-coordinate of the click point. If the argument is negative, it defaults to the current desktop mouse pointer Y-coordinate value.
wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

mouseDoubleClick

public int mouseDoubleClick(int x,
                            int y)
                     throws java.io.IOException

Perform a double left mouse click on the currently connected desktop. The method provides access to functionality of the Mouse click button=left count=2 scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
x - X-coordinate of the click point. If the argument is negative, it defaults to the current desktop mouse pointer X-coordinate value.
y - Y-coordinate of the click point. If the argument is negative, it defaults to the current desktop mouse pointer Y-coordinate value.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

mouseDrag

public int mouseDrag(java.awt.Point from,
                     java.awt.Point to,
                     int modifiers,
                     int button,
                     java.lang.String wait)
              throws java.io.IOException

Perform a left button mouse drag on the currently connected desktop. The method provides access to functionality of the Mouse drag button=left scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
modifiers - modifier mask as specified in the InputEvent. For example, to specify Ctrl+Alt use InputEvent.CTRL_MASK | InputEvent.ALT_MASK
button - mouse button ID as specified in MouseEvent. Supported values are MouseEvent.BUTTON1 (left button), MouseEvent.BUTTON2 (middle button) and MouseEvent.BUTTON3 (right button). If any other value is used, the argument defaults to the left button. This argument applies only to mouse events which involve buttons, such as mouse click, press, release and drag.
from - start point of the drag. If the argument is null, it defaults to the current desktop mouse pointer position. The value is ignored by other actions.
to - target drag point (drop location). If the argument is null, it defaults to the current desktop mouse pointer position.
wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

mouseRightDrag

public int mouseRightDrag(java.awt.Point from,
                          java.awt.Point to,
                          int modifiers,
                          java.lang.String wait)
                   throws java.io.IOException

Perform a right button mouse drag on the currently connected desktop. The method provides access to functionality of the Mouse drag btn=right scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
modifiers - modifier mask as specified in the InputEvent. For example, to specify Ctrl+Alt use InputEvent.CTRL_MASK | InputEvent.ALT_MASK
from - start point of the drag. If the argument is null, it defaults to the current desktop mouse pointer position. The value is ignored by other actions.
to - target drag point (drop location). If the argument is null, it defaults to the current desktop mouse pointer position.
wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

mouseWheelUp

public int mouseWheelUp(java.awt.Point to,
                        int modifiers,
                        int count,
                        java.lang.String wait)
                 throws java.io.IOException

Scroll up the mouse wheel on the current desktop. The method provides access to functionality of the Mouse wheelup scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
modifiers - modifier mask as specified in the InputEvent. For example, to specify Ctrl+Alt use InputEvent.CTRL_MASK | InputEvent.ALT_MASK
to - location to move the mouse pointer to before performing the wheel scroll. If the argument is null, it defaults to the current desktop mouse pointer position.
count - how many wheel steps to scroll up. Default value is 1 (one mouse wheel step). Delays among multiple steps are defined by a value in the Mouse command user preferences.
wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

mouseWheelUp

public int mouseWheelUp(int x,
                        int y,
                        int modifiers,
                        int count,
                        java.lang.String wait)
                 throws java.io.IOException

Scroll up the mouse wheel on the current desktop. The method provides access to functionality of the Mouse wheelup scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
modifiers - modifier mask as specified in the InputEvent. For example, to specify Ctrl+Alt use InputEvent.CTRL_MASK | InputEvent.ALT_MASK
x - X-coordinate of the mouse pointer to move to before scrolling the wheel. If the argument is negative, it defaults to the current desktop mouse pointer X-coordinate value.
y - Y-coordinate of the mouse pointer to move to before scrolling the wheel. If the argument is negative, it defaults to the current desktop mouse pointer Y-coordinate value.
count - how many wheel steps to scroll up. Default value is 1 (one mouse wheel step). Delays among multiple steps are defined by a value in the Mouse command user preferences.
wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

mouseWheelDown

public int mouseWheelDown(java.awt.Point to,
                          int modifiers,
                          int count,
                          java.lang.String wait)
                   throws java.io.IOException

Scroll down the mouse wheel on the current desktop. The method provides access to functionality of the Mouse wheeldown scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
modifiers - modifier mask as specified in the InputEvent. For example, to specify Ctrl+Alt use InputEvent.CTRL_MASK | InputEvent.ALT_MASK
to - location to move the mouse pointer to before performing the wheel scroll. If the argument is null, it defaults to the current desktop mouse pointer position.
count - how many wheel steps to scroll up. Default value is 1 (one mouse wheel step). Delays among multiple steps are defined by a value in the Mouse command user preferences.
wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

mouseWheelDown

public int mouseWheelDown(int x,
                          int y,
                          int modifiers,
                          int count,
                          java.lang.String wait)
                   throws java.io.IOException

Scroll down the mouse wheel on the current desktop. The method provides access to functionality of the Mouse wheeldown scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
modifiers - modifier mask as specified in the InputEvent. For example, to specify Ctrl+Alt use InputEvent.CTRL_MASK | InputEvent.ALT_MASK
x - X-coordinate of the mouse pointer to move to before scrolling the wheel. If the argument is negative, it defaults to the current desktop mouse pointer X-coordinate value.
y - Y-coordinate of the mouse pointer to move to before scrolling the wheel. If the argument is negative, it defaults to the current desktop mouse pointer Y-coordinate value.
count - how many wheel steps to scroll up. Default value is 1 (one mouse wheel step). Delays among multiple steps are defined by a value in the Mouse command user preferences.
wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

mouseEvent

public int mouseEvent(java.lang.String action,
                      java.awt.Point center,
                      int start,
                      int end,
                      int count,
                      java.lang.String wait)
               throws java.io.IOException

Perform a pinch or zoom action on the currently connected desktop. The method provides access to functionality of the pinch and zoom actions of the Mouse scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface) or the connection does not support pinch and zoom, the method throws an IllegalArgumentException.

Parameters:
action - mouse action string as is defined in the Mouse command specification. Values supported by this method are pinch and zoom. The action codes are not case sensitive.
center - the pinch/zoom center point (optional). If the argument is null the action will default to the screen center.
start - the pinch/zoom start and end distances. The parameters must be always specified together. If they are set to a negative number the action will calculate default values based on the center point position and the current screen size.

The distances specify how many pixels the fingers are apart at the beginning ("start") and the end ("end") of the gesture. When the event is "pinch" the start distance must be naturally greater than the end one because the fingers move closer to each other. The "zoom" event requires the opposite setting. The distances must be specified in a way that the fingers don't get too close to each other (30 pixels at a minimum) or closer than 10 pixels to the screen borders.

end - see start.
count - how many times to repeat the event. The default value is 1 (one).
wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication or if no desktop is connected.
Since:
3.5

mousePinch

public int mousePinch(java.awt.Point center,
                      int start,
                      int end,
                      int count,
                      java.lang.String wait)
               throws java.io.IOException

Perform a pinch action on the currently connected desktop. The method provides access to functionality of the pinch action of the Mouse scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface) or the connection does not support pinch and zoom, the method throws an IllegalArgumentException.

Parameters:
center - the pinch center point (optional). If the argument is null the action will default to the screen center.
start - the pinch start and end distances. The parameters must be always specified together. If they are set to a negative number the action will calculate default values based on the center point position and the current screen size.

The distances specify how many pixels the fingers are apart at the beginning ("start") and the end ("end") of the gesture. When the event is "pinch" the start distance must be naturally greater than the end one because the fingers move closer to each other. The "zoom" event requires the opposite setting. The distances must be specified in a way that the fingers don't get too close to each other (30 pixels at a minimum) or closer than 10 pixels to the screen borders.

end - see start.
count - how many times to repeat the event. The default value is 1 (one).
wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication or if no desktop is connected.
Since:
3.5

mousePinch

public int mousePinch(int count,
                      java.lang.String wait)
               throws java.io.IOException

Perform a pinch action with the default center point and the start/end distances on the currently connected desktop. The method provides access to functionality of the pinch action of the Mouse scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface) or the connection does not support pinch and zoom, the method throws an IllegalArgumentException.

Parameters:
count - how many times to repeat the event. The default value is 1 (one).
wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication or if no desktop is connected.
Since:
3.5

mousePinch

public int mousePinch()
               throws java.io.IOException

Perform a pinch action with the default center point and the start/end distances on the currently connected desktop. The method provides access to functionality of the pinch action of the Mouse scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface) or the connection does not support pinch and zoom, the method throws an IllegalArgumentException.

Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication or if no desktop is connected.
Since:
3.5

mouseZoom

public int mouseZoom(java.awt.Point center,
                     int start,
                     int end,
                     int count,
                     java.lang.String wait)
              throws java.io.IOException

Perform a zoom action on the currently connected desktop. The method provides access to functionality of the zoom action of the Mouse scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface) or the connection does not support pinch and zoom, the method throws an IllegalArgumentException.

Parameters:
center - the zoom center point (optional). If the argument is null the action will default to the screen center.
start - the zoom start and end distances. The parameters must be always specified together. If they are set to a negative number the action will calculate default values based on the center point position and the current screen size.

The distances specify how many pixels the fingers are apart at the beginning ("start") and the end ("end") of the gesture. When the event is "pinch" the start distance must be naturally greater than the end one because the fingers move closer to each other. The "zoom" event requires the opposite setting. The distances must be specified in a way that the fingers don't get too close to each other (30 pixels at a minimum) or closer than 10 pixels to the screen borders.

end - see start.
count - how many times to repeat the event. The default value is 1 (one).
wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication or if no desktop is connected.
Since:
3.5

mouseZoom

public int mouseZoom(int count,
                     java.lang.String wait)
              throws java.io.IOException

Perform a zoom action with the default center point and the start/end distances on the currently connected desktop. The method provides access to functionality of the zoom action of the Mouse scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface) or the connection does not support pinch and zoom, the method throws an IllegalArgumentException.

Parameters:
count - how many times to repeat the event. The default value is 1 (one).
wait - how long to wait after the event is sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication or if no desktop is connected.
Since:
3.5

mouseZoom

public int mouseZoom()
              throws java.io.IOException

Perform a zoom action with the default center point and the start/end distances on the currently connected desktop. The method provides access to functionality of the zoom action of the Mouse scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of pointer event transfer (its client doesn't implement the PointerTransferCapable interface) or the connection does not support pinch and zoom, the method throws an IllegalArgumentException.

Returns:
command exit code as is specified in the Mouse specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication or if no desktop is connected.
Since:
3.5

type

public int type(java.lang.String text,
                int count,
                int location,
                java.lang.String wait)
         throws java.io.IOException

Type a text on the current desktop. The method provides access to functionality of the Type scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of text transfer (its client doesn't implement the KeyTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
text - a text to type. Interpretation of the text is fully dependent on the desktop client and it is subject to limitations applied by the client protocol. For example, the RFB (VNC) protocol cannot transfer characters outside of the Latin-1 (ISO 8859-1) character set. On the other hand the native Java client can transfer any characters which can be typed on the local keyboard.
count - how many times to repeat typing of the text. Default value is 1 (type the text once). Delays among multiple typings are defined by a value in the Type command user preferences.
location - key location as is defined in the java.awt.event.KeyEvent class. Acceptable values are KeyEvent.KEY_LOCATION_STANDARD, KeyEvent.KEY_LOCATION_LEFT, KeyEvent.KEY_LOCATION_RIGHT and KeyEvent.KEY_LOCATION_NUMPAD. If the argument is null, the method defaults to KeyEvent.KEY_LOCATION_STANDARD. Note that the method doesn't verify whether the [key,location] pair makes sense. For example, alphabet characters are present on most keyboard just once and the only logically valid location is the default standard one. Most clients however use the location only as a hint and ignore it by keys where it is not applicable.
wait - how long to wait after the text is typed to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Type specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

type

public int type(java.lang.String text,
                int count,
                java.lang.String wait)
         throws java.io.IOException

Type a text on the current desktop. The method provides access to functionality of the Type scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of text transfer (its client doesn't implement the KeyTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
text - a text to type. Interpretation of the text is fully dependent on the desktop client and it is subject to limitations applied by the client protocol. For example, the RFB (VNC) protocol cannot transfer characters outside of the Latin-1 (ISO 8859-1) character set. On the other hand the native Java client can transfer any characters which can be typed on the local keyboard.
count - how many times to repeat typing of the text. Default value is 1 (type the text once). Delays among multiple typings are defined by a value in the Type command user preferences.
wait - how long to wait after the text is typed to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Type specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

type

public int type(java.lang.String text,
                java.lang.String wait)
         throws java.io.IOException

Type a text on the current desktop. The method provides access to functionality of the Type scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of text transfer (its client doesn't implement the KeyTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
text - a text to type. Interpretation of the text is fully dependent on the desktop client and it is subject to limitations applied by the client protocol. For example, the RFB (VNC) protocol cannot transfer characters outside of the Latin-1 (ISO 8859-1) character set. On the other hand the native Java client can transfer any characters which can be typed on the local keyboard.
wait - how long to wait after the text is typed to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Type specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

type

public int type(java.lang.String text)
         throws java.io.IOException

Type a text on the current desktop. The method provides access to functionality of the Type scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of text transfer (its client doesn't implement the KeyTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
text - a text to type. Interpretation of the text is fully dependent on the desktop client and it is subject to limitations applied by the client protocol. For example, the RFB (VNC) protocol cannot transfer characters outside of the Latin-1 (ISO 8859-1) character set. On the other hand the native Java client can transfer any characters which can be typed on the local keyboard.
Returns:
command exit code as is specified in the Type specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

typeLine

public int typeLine(java.lang.String text,
                    int count,
                    int location,
                    java.lang.String wait)
             throws java.io.IOException

Type a text and press an Enter key on the current desktop once or more times. It is equivalent to a Type command followed by a Press Enter. The method provides access to functionality of the Typeline scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of text transfer (its client doesn't implement the KeyTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
text - a text to type. Interpretation of the text is fully dependent on the desktop client and it is subject to limitations applied by the client protocol. For example, the RFB (VNC) protocol cannot transfer characters outside of the Latin-1 (ISO 8859-1) character set. On the other hand the native Java client can transfer any characters which can be typed on the local keyboard.
count - how many times to repeat typing of the text. Default value is 1 (type the text once). Delays among multiple typings are defined by a value in the Type command user preferences.
location - key location as is defined in the java.awt.event.KeyEvent class. Acceptable values are KeyEvent.KEY_LOCATION_STANDARD, KeyEvent.KEY_LOCATION_LEFT, KeyEvent.KEY_LOCATION_RIGHT and KeyEvent.KEY_LOCATION_NUMPAD. If the argument is null, the method defaults to KeyEvent.KEY_LOCATION_STANDARD. Note that the method doesn't verify whether the [key,location] pair makes sense. For example, alphabet characters are present on most keyboard just once and the only logically valid location is the default standard one. Most clients however use the location only as a hint and ignore it by keys where it is not applicable.
wait - how long to wait after the text is typed to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Typeline specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

typeLine

public int typeLine(java.lang.String text,
                    int count,
                    java.lang.String wait)
             throws java.io.IOException

Type a text and press an Enter key on the current desktop once or more times. It is equivalent to a Type command followed by a Press Enter. The method provides access to functionality of the Typeline scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of text transfer (its client doesn't implement the KeyTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
text - a text to type. Interpretation of the text is fully dependent on the desktop client and it is subject to limitations applied by the client protocol. For example, the RFB (VNC) protocol cannot transfer characters outside of the Latin-1 (ISO 8859-1) character set. On the other hand the native Java client can transfer any characters which can be typed on the local keyboard.
count - how many times to repeat typing of the text. Default value is 1 (type the text once). Delays among multiple typings are defined by a value in the Type command user preferences.
wait - how long to wait after the text is typed to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Typeline specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

typeLine

public int typeLine(java.lang.String text,
                    java.lang.String wait)
             throws java.io.IOException

Type a text and press an Enter key on the current desktop. It is equivalent to a Type command followed by a Press Enter. The method provides access to functionality of the Typeline scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of text transfer (its client doesn't implement the KeyTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
text - a text to type. Interpretation of the text is fully dependent on the desktop client and it is subject to limitations applied by the client protocol. For example, the RFB (VNC) protocol cannot transfer characters outside of the Latin-1 (ISO 8859-1) character set. On the other hand the native Java client can transfer any characters which can be typed on the local keyboard.
wait - how long to wait after the text is typed to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Typeline specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

typeLine

public int typeLine(java.lang.String text)
             throws java.io.IOException

Type a text and press an Enter key on the current desktop. It is equivalent to a Type command followed by a Press Enter. The method provides access to functionality of the Typeline scripting language command.

If no desktop is connected, the method throws an IOException. If the connected desktop is not capable of text transfer (its client doesn't implement the KeyTransferCapable interface), the method throws an IllegalArgumentException.

Parameters:
text - a text to type. Interpretation of the text is fully dependent on the desktop client and it is subject to limitations applied by the client protocol. For example, the RFB (VNC) protocol cannot transfer characters outside of the Latin-1 (ISO 8859-1) character set. On the other hand the native Java client can transfer any characters which can be typed on the local keyboard.
Returns:
command exit code as is specified in the Typeline specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

press

public int press(java.lang.String key,
                 int location,
                 int count,
                 java.lang.Boolean release,
                 java.lang.String delay,
                 java.lang.String wait)
          throws java.io.IOException

Press a key with optional modifiers on the current desktop once or more times. The method provides access to functionality of the Press scripting language command.

The method supports any key identifier derived from the VK_ key code constants declared in the java.awt.event.KeyEvent class where the identifier itself is the string which follows the VK_ prefix. For example, as there is a VK_ENTER constant, the method supports any key like "ENTER", "Enter" or "enter".

As the key identifiers are in fact extracted from the KeyEvent class at runtime using Java Reflection API, the range of supported keys may differ depending on the version of Java used to execute this program. A complete map of the supported key identifiers may be obtained through the Utils.getKeyCodeTable() method.

Transferable keys and key combinations are further on subject to limitations applied by the desktop client. For example the RFB (VNC) protocol cannot transfer characters outside of the Latin-1 (ISO 8859-1) character set. On contrary the native Java client can transfer only characters which can be generated on the local keyboard regardless of the character set they belong to.

Parameters:
key - a key to press. The argument must consist of a key identifier which may be optionally prefixed with one or more supported modifiers ("Ctrl", "Alt", "Shift" and "Meta") separated by the plus character '+', for example "Ctrl+C" or "Alt+Ctrl+Delete". The method also accepts arguments consisting only of modifiers. None of the components is case sensitive and both the keys and modifiers may be specified in any character case.
location - key location as is defined in the java.awt.event.KeyEvent class. Acceptable values are KeyEvent.KEY_LOCATION_STANDARD, KeyEvent.KEY_LOCATION_LEFT, KeyEvent.KEY_LOCATION_RIGHT and KeyEvent.KEY_LOCATION_NUMPAD. If the argument is null, the method defaults to KeyEvent.KEY_LOCATION_STANDARD. Note that the method doesn't verify whether the [key,location] pair makes sense. For example, alphabet characters are present on most keyboard just once and the only logically valid location is the default standard one. Most clients however use the location only as a hint and ignore it by keys where it is not applicable.
count - how many times to repeat the key press. Default value is 1 (press the key once). Delays among multiple press actions are defined by a value in the Press Command user preferences.
release - if this argument is null the method performs the standard key press-release sequence automating typing of a key on the keyboard. When the argument is populated the command performs just a key press (release=false) or a key release (release=true). This allows to automate long key presses and/or composed press and mouse events. If you use this parameter make sure that each key press is paired with a later key release.
delay - how long to wait between the key press and release. This value is by default loaded from the Press command configuration. This parameter allows to customize it for a single command call. It is handy for example on mobile devices where certain functionality gets activated through a longer key press. Value of this parameter must be a valid time value specified by the Time Values chapter of the language specification. Use null to apply the default value.
wait - how long to wait after all the key press events are sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Press specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

press

public int press(java.lang.String key,
                 int location,
                 int count,
                 java.lang.String delay,
                 java.lang.String wait)
          throws java.io.IOException

Press a key with optional modifiers on the current desktop once or more times. The method provides access to functionality of the Press scripting language command.

The method supports any key identifier derived from the VK_ key code constants declared in the java.awt.event.KeyEvent class where the identifier itself is the string which follows the VK_ prefix. For example, as there is a VK_ENTER constant, the method supports any key like "ENTER", "Enter" or "enter".

As the key identifiers are in fact extracted from the KeyEvent class at runtime using Java Reflection API, the range of supported keys may differ depending on the version of Java used to execute this program. A complete map of the supported key identifiers may be obtained through the Utils.getKeyCodeTable() method.

Transferable keys and key combinations are further on subject to limitations applied by the desktop client. For example the RFB (VNC) protocol cannot transfer characters outside of the Latin-1 (ISO 8859-1) character set. On contrary the native Java client can transfer only characters which can be generated on the local keyboard regardless of the character set they belong to.

Parameters:
key - a key to press. The argument must consist of a key identifier which may be optionally prefixed with one or more supported modifiers ("Ctrl", "Alt", "Shift" and "Meta") separated by the plus character '+', for example "Ctrl+C" or "Alt+Ctrl+Delete". The method also accepts arguments consisting only of modifiers. None of the components is case sensitive and both the keys and modifiers may be specified in any character case.
location - key location as is defined in the java.awt.event.KeyEvent class. Acceptable values are KeyEvent.KEY_LOCATION_STANDARD, KeyEvent.KEY_LOCATION_LEFT, KeyEvent.KEY_LOCATION_RIGHT and KeyEvent.KEY_LOCATION_NUMPAD. If the argument is null, the method defaults to KeyEvent.KEY_LOCATION_STANDARD. Note that the method doesn't verify whether the [key,location] pair makes sense. For example, alphabet characters are present on most keyboard just once and the only logically valid location is the default standard one. Most clients however use the location only as a hint and ignore it by keys where it is not applicable.
count - how many times to repeat the key press. Default value is 1 (press the key once). Delays among multiple press actions are defined by a value in the Press Command user preferences.
delay - how long to wait between the key press and release. This value is by default loaded from the Press command configuration. This parameter allows to customize it for a single command call. It is handy for example on mobile devices where certain functionality gets activated through a longer key press. Value of this parameter must be a valid time value specified by the Time Values chapter of the language specification. Use null to apply the default value.
wait - how long to wait after all the key press events are sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Press specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

press

public int press(java.lang.String key,
                 int location,
                 int count,
                 java.lang.String wait)
          throws java.io.IOException

Press a key with optional modifiers on the current desktop once or more times. The method provides access to functionality of the Press scripting language command.

The method supports any key identifier derived from the VK_ key code constants declared in the java.awt.event.KeyEvent class where the identifier itself is the string which follows the VK_ prefix. For example, as there is a VK_ENTER constant, the method supports any key like "ENTER", "Enter" or "enter".

As the key identifiers are in fact extracted from the KeyEvent class at runtime using Java Reflection API, the range of supported keys may differ depending on the version of Java used to execute this program. A complete map of the supported key identifiers may be obtained through the Utils.getKeyCodeTable() method.

Transferable keys and key combinations are further on subject to limitations applied by the desktop client. For example the RFB (VNC) protocol cannot transfer characters outside of the Latin-1 (ISO 8859-1) character set. On contrary the native Java client can transfer only characters which can be generated on the local keyboard regardless of the character set they belong to.

Parameters:
key - a key to press. The argument must consist of a key identifier which may be optionally prefixed with one or more supported modifiers ("Ctrl", "Alt", "Shift" and "Meta") separated by the plus character '+', for example "Ctrl+C" or "Alt+Ctrl+Delete". The method also accepts arguments consisting only of modifiers. None of the components is case sensitive and both the keys and modifiers may be specified in any character case.
location - key location as is defined in the java.awt.event.KeyEvent class. Acceptable values are KeyEvent.KEY_LOCATION_STANDARD, KeyEvent.KEY_LOCATION_LEFT, KeyEvent.KEY_LOCATION_RIGHT and KeyEvent.KEY_LOCATION_NUMPAD. If the argument is null, the method defaults to KeyEvent.KEY_LOCATION_STANDARD. Note that the method doesn't verify whether the [key,location] pair makes sense. For example, alphabet characters are present on most keyboard just once and the only logically valid location is the default standard one. Most clients however use the location only as a hint and ignore it by keys where it is not applicable.
count - how many times to repeat the key press. Default value is 1 (press the key once). Delays among multiple press actions are defined by a value in the Press Command user preferences.
wait - how long to wait after all the key press events are sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Press specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

press

public int press(java.lang.String key,
                 java.lang.String wait,
                 int count)
          throws java.io.IOException

Press a key with optional modifiers on the current desktop once or more times. The method provides access to functionality of the Press scripting language command.

The method supports any key identifier derived from the VK_ key code constants declared in the java.awt.event.KeyEvent class where the identifier itself is the string which follows the VK_ prefix. For example, as there is a VK_ENTER constant, the method supports any key like "ENTER", "Enter" or "enter".

As the key identifiers are in fact extracted from the KeyEvent class at runtime using Java Reflection API, the range of supported keys may differ depending on the version of Java used to execute this program. A complete map of the supported key identifiers may be obtained through the Utils.getKeyCodeTable() method.

Transferable keys and key combinations are further on subject to limitations applied by the desktop client. For example the RFB (VNC) protocol cannot transfer characters outside of the Latin-1 (ISO 8859-1) character set. On contrary the native Java client can transfer only characters which can be generated on the local keyboard regardless of the character set they belong to.

Parameters:
key - a key to press. The argument must consist of a key identifier which may be optionally prefixed with one or more supported modifiers ("Ctrl", "Alt", "Shift" and "Meta") separated by the plus character '+', for example "Ctrl+C" or "Alt+Ctrl+Delete". The method also accepts arguments consisting only of modifiers. None of the components is case sensitive and both the keys and modifiers may be specified in any character case.
count - how many times to repeat the key press. Default value is 1 (press the key once). Delays among multiple press actions are defined by a value in the Press Command user preferences.
wait - how long to wait after all the key press events are sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Press specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

press

public int press(char c,
                 int location,
                 int count,
                 java.lang.String delay,
                 java.lang.String wait)
          throws java.io.IOException

Press a character with optional modifiers on the current desktop once or more times. The method provides access to functionality of the Press scripting language command.

Transferable characters and key combinations are further on subject to limitations applied by the desktop client. For example the RFB (VNC) protocol cannot transfer characters outside of the Latin-1 (ISO 8859-1) character set. On contrary the native Java client can transfer only characters which can be generated on the local keyboard regardless of the character set they belong to.

Parameters:
c - a character to press. This method doesn't support modifiers.
location - key location as is defined in the java.awt.event.KeyEvent class. Acceptable values are KeyEvent.KEY_LOCATION_STANDARD, KeyEvent.KEY_LOCATION_LEFT, KeyEvent.KEY_LOCATION_RIGHT and KeyEvent.KEY_LOCATION_NUMPAD. If the argument is null, the method defaults to KeyEvent.KEY_LOCATION_STANDARD. Note that the method doesn't verify whether the [key,location] pair makes sense. For example, alphabet characters are present on most keyboard just once and the only logically valid location is the default standard one. Most clients however use the location only as a hint and ignore it by keys where it is not applicable.
count - how many times to repeat the character press. Default value is 1 (press the key once). Delays among multiple press actions are defined by a value in the Press Command user preferences.
delay - how long to wait between the key press and release. This value is by default loaded from the Press command configuration. This parameter allows to customize it for a single command call. It is handy for example on mobile devices where certain functionality gets activated through a longer key press. Value of this parameter must be a valid time value specified by the Time Values chapter of the language specification. Use null to apply the default value.
wait - how long to wait after all the key press events are sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Press specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

press

public int press(char c,
                 int location,
                 int count,
                 java.lang.String wait)
          throws java.io.IOException

Press a character with optional modifiers on the current desktop once or more times. The method provides access to functionality of the Press scripting language command.

Transferable characters and key combinations are further on subject to limitations applied by the desktop client. For example the RFB (VNC) protocol cannot transfer characters outside of the Latin-1 (ISO 8859-1) character set. On contrary the native Java client can transfer only characters which can be generated on the local keyboard regardless of the character set they belong to.

Parameters:
c - a character to press. This method doesn't support modifiers.
location - key location as is defined in the java.awt.event.KeyEvent class. Acceptable values are KeyEvent.KEY_LOCATION_STANDARD, KeyEvent.KEY_LOCATION_LEFT, KeyEvent.KEY_LOCATION_RIGHT and KeyEvent.KEY_LOCATION_NUMPAD. If the argument is null, the method defaults to KeyEvent.KEY_LOCATION_STANDARD. Note that the method doesn't verify whether the [key,location] pair makes sense. For example, alphabet characters are present on most keyboard just once and the only logically valid location is the default standard one. Most clients however use the location only as a hint and ignore it by keys where it is not applicable.
count - how many times to repeat the character press. Default value is 1 (press the key once). Delays among multiple press actions are defined by a value in the Press Command user preferences.
wait - how long to wait after all the key press events are sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Press specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

press

public int press(java.lang.String key,
                 int location,
                 java.lang.String wait)
          throws java.io.IOException

Press a key with optional modifiers on the current desktop. The method provides access to functionality of the Press scripting language command.

The method supports any key identifier derived from the VK_ key code constants declared in the java.awt.event.KeyEvent class where the identifier itself is the string which follows the VK_ prefix. For example, as there is a VK_ENTER constant, the method supports any key like "ENTER", "Enter" or "enter".

As the key identifiers are in fact extracted from the KeyEvent class at runtime using Java Reflection API, the range of supported keys may differ depending on the version of Java used to execute this program. A complete map of the supported key identifiers may be obtained through the Utils.getKeyCodeTable() method.

Transferable keys and key combinations are further on subject to limitations applied by the desktop client. For example the RFB (VNC) protocol cannot transfer characters outside of the Latin-1 (ISO 8859-1) character set. On contrary the native Java client can transfer only characters which can be generated on the local keyboard regardless of the character set they belong to.

Parameters:
key - a key to press. The argument must consist of a key identifier which may be optionally prefixed with one or more supported modifiers ("Ctrl", "Alt", "Shift" and "Meta") separated by the plus character '+', for example "Ctrl+C" or "Alt+Ctrl+Delete". The method also accepts arguments consisting only of modifiers. None of the components is case sensitive and both the keys and modifiers may be specified in any character case.
location - key location as is defined in the java.awt.event.KeyEvent class. Acceptable values are KeyEvent.KEY_LOCATION_STANDARD, KeyEvent.KEY_LOCATION_LEFT, KeyEvent.KEY_LOCATION_RIGHT and KeyEvent.KEY_LOCATION_NUMPAD. If the argument is null, the method defaults to KeyEvent.KEY_LOCATION_STANDARD. Note that the method doesn't verify whether the [key,location] pair makes sense. For example, alphabet characters are present on most keyboard just once and the only logically valid location is the default standard one. Most clients however use the location only as a hint and ignore it by keys where it is not applicable.
wait - how long to wait after all the key press events are sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Press specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

press

public int press(java.lang.String key,
                 int location)
          throws java.io.IOException

Press a key with optional modifiers on the current desktop. The method provides access to functionality of the Press scripting language command.

The method supports any key identifier derived from the VK_ key code constants declared in the java.awt.event.KeyEvent class where the identifier itself is the string which follows the VK_ prefix. For example, as there is a VK_ENTER constant, the method supports any key like "ENTER", "Enter" or "enter".

As the key identifiers are in fact extracted from the KeyEvent class at runtime using Java Reflection API, the range of supported keys may differ depending on the version of Java used to execute this program. A complete map of the supported key identifiers may be obtained through the Utils.getKeyCodeTable() method.

Transferable keys and key combinations are further on subject to limitations applied by the desktop client. For example the RFB (VNC) protocol cannot transfer characters outside of the Latin-1 (ISO 8859-1) character set. On contrary the native Java client can transfer only characters which can be generated on the local keyboard regardless of the character set they belong to.

Parameters:
key - a key to press. The argument must consist of a key identifier which may be optionally prefixed with one or more supported modifiers ("Ctrl", "Alt", "Shift" and "Meta") separated by the plus character '+', for example "Ctrl+C" or "Alt+Ctrl+Delete". The method also accepts arguments consisting only of modifiers. None of the components is case sensitive and both the keys and modifiers may be specified in any character case.
location - key location as is defined in the java.awt.event.KeyEvent class. Acceptable values are KeyEvent.KEY_LOCATION_STANDARD, KeyEvent.KEY_LOCATION_LEFT, KeyEvent.KEY_LOCATION_RIGHT and KeyEvent.KEY_LOCATION_NUMPAD. If the argument is null, the method defaults to KeyEvent.KEY_LOCATION_STANDARD. Note that the method doesn't verify whether the [key,location] pair makes sense. For example, alphabet characters are present on most keyboard just once and the only logically valid location is the default standard one. Most clients however use the location only as a hint and ignore it by keys where it is not applicable.
Returns:
command exit code as is specified in the Press specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

press

public int press(java.lang.String key,
                 java.lang.String wait)
          throws java.io.IOException

Press a key with optional modifiers on the current desktop. The method provides access to functionality of the Press scripting language command.

The method supports any key identifier derived from the VK_ key code constants declared in the java.awt.event.KeyEvent class where the identifier itself is the string which follows the VK_ prefix. For example, as there is a VK_ENTER constant, the method supports any key like "ENTER", "Enter" or "enter".

As the key identifiers are in fact extracted from the KeyEvent class at runtime using Java Reflection API, the range of supported keys may differ depending on the version of Java used to execute this program. A complete map of the supported key identifiers may be obtained through the Utils.getKeyCodeTable() method.

Transferable keys and key combinations are further on subject to limitations applied by the desktop client. For example the RFB (VNC) protocol cannot transfer characters outside of the Latin-1 (ISO 8859-1) character set. On contrary the native Java client can transfer only characters which can be generated on the local keyboard regardless of the character set they belong to.

Parameters:
key - a key to press. The argument must consist of a key identifier which may be optionally prefixed with one or more supported modifiers ("Ctrl", "Alt", "Shift" and "Meta") separated by the plus character '+', for example "Ctrl+C" or "Alt+Ctrl+Delete". The method also accepts arguments consisting only of modifiers. None of the components is case sensitive and both the keys and modifiers may be specified in any character case.
wait - how long to wait after all the key press events are sent to the desktop. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Press specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

press

public int press(java.lang.String key)
          throws java.io.IOException

Press a key with optional modifiers on the current desktop. The method provides access to functionality of the Press scripting language command.

The method supports any key identifier derived from the VK_ key code constants declared in the java.awt.event.KeyEvent class where the identifier itself is the string which follows the VK_ prefix. For example, as there is a VK_ENTER constant, the method supports any key like "ENTER", "Enter" or "enter".

As the key identifiers are in fact extracted from the KeyEvent class at runtime using Java Reflection API, the range of supported keys may differ depending on the version of Java used to execute this program. A complete map of the supported key identifiers may be obtained through the Utils.getKeyCodeTable() method.

Transferable keys and key combinations are further on subject to limitations applied by the desktop client. For example the RFB (VNC) protocol cannot transfer characters outside of the Latin-1 (ISO 8859-1) character set. On contrary the native Java client can transfer only characters which can be generated on the local keyboard regardless of the character set they belong to.

Parameters:
key - a key to press. The argument must consist of a key identifier which may be optionally prefixed with one or more supported modifiers ("Ctrl", "Alt", "Shift" and "Meta") separated by the plus character '+', for example "Ctrl+C" or "Alt+Ctrl+Delete". The method also accepts arguments consisting only of modifiers. None of the components is case sensitive and both the keys and modifiers may be specified in any character case.
Returns:
command exit code as is specified in the Press specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

wait

public int wait(java.lang.String time)
Postpone execution of the test script for the specified time period. The method provides access to functionality of the Wait scripting language command.

Parameters:
time - how long to wait. The argument must be in format specified by the Time Values chapter of the language specification. If the argument is null or zero, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Wait specification.

screenshot

public int screenshot(java.io.File file,
                      java.lang.String description,
                      java.awt.Rectangle area,
                      java.awt.Image[] templates,
                      float passRate,
                      java.awt.Rectangle cmpArea,
                      boolean removeBg,
                      java.lang.String bgColor,
                      java.lang.Integer minAlpha,
                      java.lang.Integer rgbTolerance,
                      boolean drawResults,
                      boolean drawDiff)
               throws java.io.IOException

Take a screen shot of the remote desktop or its part, save it to a file and perform image search using the "search" comparison method with the support of filtering background from the template image(s). The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

If at least one of the image comparison parameters is specified (not null or positive in case of pass rate), such as the template, passRate or cmpArea, the command performs image comparison the same way a corresponding Compareto command would do. Even if none of the parameters is specified, the command searches the template directory for an image of the same name as the screen shot one and performs image comparison with default parameter values if such an image is found. This "auto comparison" may be switched off in the Screenshot preferences. Default parameter values may be configured there as well.

Each successful call of this method inserts a data structure (instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:
file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.
description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.
area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.
templates - list of template images to compare the remote desktop image to.
passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.
cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.
removeBg -

set on/off filtering of background color from the template image. It is a new 2.1 feature allowing to search for objects on varying background. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). The background filter is applied only to completely opaque template images which do not contain any translucent or transparent pixels introduced through third party image editors. When an existing translucency is detected the filter is switched off silently and only the eventual minAlpha parameter is applied.

The default value is null (equivalent to "false") meaning that background filtering is off. See the Compareto documentation for details.

bgColor - optional color for the background filter. The parameter is ignored when background filtering is off. If the color is not specified (is null), the background filter will use color of the very first image pixel at [0,0] (upper left image corner).
minAlpha - translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing translucent pixels. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). Alpha is a pixel color component between 0 (transparent) and 255 (opaque) which defines the level of pixel translucency. The default minalpha value of null or -1 (internally equal to 255) instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Other values between 0 and 254 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit. Comparison of such pixels is based on color similarity with a fixed threshold.
rgbTolerance - RGB tolerance value. This parameter may be populated only for "search" image comparison algorithm. It is a number between 0 and 100 and it specifies tolerance to color changes on the level of individual pixel R, G, B components. A value of 20 for example makes the search robust against color changes where any of the R, G, B components varies by 20 or less from the template image pixels. It is recommended to use higher values of this parameter or even the limit one of 100 for testing of environments with varying images (for example in Flash or Flex ones). To get best results it is also recommended avoid mixing of the RGB tolerance parameter with other tolerance mechanisms such as pass rate (should be set to 100%) and background filtering (should be off).

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

drawResults - indicates whether results of image comparison should be painted into the captured screen shot. The default value is false (meaning "do not paint any results"). If the command doesn't employ image comparison or the specified comparison method doesn't support result painting the parameter is ignored. In the default configuration, the "default" image comparison method doesn't support result painting because it doesn't make sense with regard to the algorithm nature. The"search" method does support result painting and draws rectangles corresponding to the match locations in the color specified in command configuration.
drawDiff - indicates whether the pixels differing from the template image should be painted in the configured color (green by default). The parameter was introduced in v3.3.1 to support image difference tracking in reports. The default value is false (meaning "do not paint the difference"). If the command doesn't employ image comparison or the specified comparison method doesn't support pixel difference tracking the parameter is ignored. This feature is supported only by the "search" and "search2" algorithms.
Returns:
command exit code as is specified in the Screenshot specification.
Throws:
java.io.IOException - when an I/O error occurs.
Since:
3.3.1

screenshot

public int screenshot(java.io.File file,
                      java.lang.String description,
                      java.awt.Rectangle area,
                      java.awt.Image[] templates,
                      float passRate,
                      java.awt.Rectangle cmpArea,
                      boolean removeBg,
                      java.lang.String bgColor,
                      java.lang.Integer minAlpha,
                      java.lang.Integer rgbTolerance,
                      boolean drawResults)
               throws java.io.IOException

Take a screen shot of the remote desktop or its part, save it to a file and perform image search using the "search" comparison method with the support of filtering background from the template image(s). The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

If at least one of the image comparison parameters is specified (not null or positive in case of pass rate), such as the template, passRate or cmpArea, the command performs image comparison the same way a corresponding Compareto command would do. Even if none of the parameters is specified, the command searches the template directory for an image of the same name as the screen shot one and performs image comparison with default parameter values if such an image is found. This "auto comparison" may be switched off in the Screenshot preferences. Default parameter values may be configured there as well.

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:
file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.
description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.
area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.
templates - list of template images to compare the remote desktop image to.
passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.
cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.
removeBg -

set on/off filtering of background color from the template image. It is a new 2.1 feature allowing to search for objects on varying background. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). The background filter is applied only to completely opaque template images which do not contain any translucent or transparent pixels introduced through third party image editors. When an existing translucency is detected the filter is switched off silently and only the eventual minAlpha parameter is applied.

The default value is null (equivalent to "false") meaning that background filtering is off. See the Compareto documentation for details.

bgColor - optional color for the background filter. The parameter is ignored when background filtering is off. If the color is not specified (is null), the background filter will use color of the very first image pixel at [0,0] (upper left image corner).
minAlpha - translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing translucent pixels. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). Alpha is a pixel color component between 0 (transparent) and 255 (opaque) which defines the level of pixel translucency. The default minalpha value of null or -1 (internally equal to 255) instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Other values between 0 and 254 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit. Comparison of such pixels is based on color similarity with a fixed threshold.
rgbTolerance - RGB tolerance value. This parameter may be populated only for "search" image comparison algorithm. It is a number between 0 and 100 and it specifies tolerance to color changes on the level of individual pixel R, G, B components. A value of 20 for example makes the search robust against color changes where any of the R, G, B components varies by 20 or less from the template image pixels. It is recommended to use higher values of this parameter or even the limit one of 100 for testing of environments with varying images (for example in Flash or Flex ones). To get best results it is also recommended avoid mixing of the RGB tolerance parameter with other tolerance mechanisms such as pass rate (should be set to 100%) and background filtering (should be off).

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

drawResults - indicates whether results of image comparison should be painted into the captured screen shot. The default value is false (meaning "do not paint any results"). If the command doesn't employ image comparison or the specified comparison method doesn't support result painting the parameter is ignored. In the default configuration, the "default" image comparison method doesn't support result painting because it doesn't make sense with regard to the algorithm nature. The"search" method does support result painting and draws rectangles corresponding to the match locations in the color specified in command configuration.
Returns:
command exit code as is specified in the Screenshot specification.
Throws:
java.io.IOException - when an I/O error occurs.

screenshot

public int screenshot(java.io.File file,
                      java.lang.String description,
                      java.awt.Rectangle area,
                      java.awt.Image[] templates,
                      float passRate,
                      java.awt.Rectangle cmpArea,
                      boolean removeBg,
                      java.lang.String bgColor,
                      java.lang.Integer minAlpha,
                      boolean drawResults)
               throws java.io.IOException

Take a screen shot of the remote desktop or its part, save it to a file and perform image search using the "search" comparison method with the support of filtering background from the template image(s). The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

If at least one of the image comparison parameters is specified (not null or positive in case of pass rate), such as the template, passRate or cmpArea, the command performs image comparison the same way a corresponding Compareto command would do. Even if none of the parameters is specified, the command searches the template directory for an image of the same name as the screen shot one and performs image comparison with default parameter values if such an image is found. This "auto comparison" may be switched off in the Screenshot preferences. Default parameter values may be configured there as well.

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:
file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.
description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.
area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.
templates - list of template images to compare the remote desktop image to.
passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.
cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.
removeBg -

set on/off filtering of background color from the template image. It is a new 2.1 feature allowing to search for objects on varying background. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). The background filter is applied only to completely opaque template images which do not contain any translucent or transparent pixels introduced through third party image editors. When an existing translucency is detected the filter is switched off silently and only the eventual minAlpha parameter is applied.

The default value is null (equivalent to "false") meaning that background filtering is off. See the Compareto documentation for details.

bgColor - optional color for the background filter. The parameter is ignored when background filtering is off. If the color is not specified (is null), the background filter will use color of the very first image pixel at [0,0] (upper left image corner).
minAlpha - translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing translucent pixels. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). Alpha is a pixel color component between 0 (transparent) and 255 (opaque) which defines the level of pixel translucency. The default minalpha value of null or -1 (internally equal to 255) instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Other values between 0 and 254 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit. Comparison of such pixels is based on color similarity with a fixed threshold.
drawResults - indicates whether results of image comparison should be painted into the captured screen shot. The default value is false (meaning "do not paint any results"). If the command doesn't employ image comparison or the specified comparison method doesn't support result painting the parameter is ignored. In the default configuration, the "default" image comparison method doesn't support result painting because it doesn't make sense with regard to the algorithm nature. The"search" method does support result painting and draws rectangles corresponding to the match locations in the color specified in command configuration.
Returns:
command exit code as is specified in the Screenshot specification.
Throws:
java.io.IOException - when an I/O error occurs.

screenshot

public int screenshot(java.io.File file,
                      java.lang.String description,
                      java.awt.Rectangle area,
                      java.awt.Image[] templates,
                      java.lang.String method,
                      java.lang.String methodParams,
                      float passRate,
                      java.awt.Rectangle cmpArea,
                      boolean drawResults,
                      boolean drawDiff)
               throws java.io.IOException

Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template. The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

If at least one of the image comparison parameters is specified (not null or positive in case of pass rate), such as the template, method, methodParams, passRate or cmpArea, the command performs image comparison the same way a corresponding Compareto command would do. Even if none of the parameters is specified, the command searches the template directory for an image of the same name as the screen shot one and performs image comparison with default parameter values if such an image is found. This "auto comparison" may be switched off in the Screenshot preferences. Default parameter values may be configured there as well.

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:
file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.
description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.
area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.
templates - list of template images to compare the remote desktop image to.
method - image comparison method. The value must correspond to one of the plugin codes (Plugin.getCode() of the installed image comparison module plugins. T-Plan Robot Enterprise provides by default two built-in methods, "default" and "search". See the "Image Comparison With T-Plan Robot Enterprise" document for more information.
methodParams - method parameters. This is a legacy helper argument intended to give third parties an option to specify custom parameters to the custom image comparison plugins, for example in a form of comma separated values. This argument is not used by any of the built-in T-Plan Robot Enterprise image comparison methods and it should be specified as null.
passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.
cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.
drawResults - indicates whether results of image comparison should be painted into the captured screen shot. The default value is false (meaning "do not paint any results"). If the command doesn't employ image comparison or the specified comparison method doesn't support result painting the parameter is ignored. In the default configuration, the "default" image comparison method doesn't support result painting because it doesn't make sense with regard to the algorithm nature. The"search" method does support result painting and draws rectangles corresponding to the match locations in the color specified in command configuration.
drawDiff - indicates whether the pixels differing from the template image should be painted in the configured color (green by default). The parameter was introduced in v3.3.1 to support image difference tracking in reports. The default value is false (meaning "do not paint the difference"). If the command doesn't employ image comparison or the specified comparison method doesn't support pixel difference tracking the parameter is ignored. This feature is supported only by the "search" and "search2" algorithms.
Returns:
command exit code as is specified in the Screenshot specification.
Throws:
java.io.IOException - when an I/O error occurs.
Since:
3.3.1

screenshot

public int screenshot(java.io.File file,
                      java.lang.String description,
                      java.awt.Rectangle area,
                      java.awt.Image[] templates,
                      java.lang.String method,
                      java.lang.String methodParams,
                      float passRate,
                      java.awt.Rectangle cmpArea,
                      boolean drawResults)
               throws java.io.IOException

Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template. The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

If at least one of the image comparison parameters is specified (not null or positive in case of pass rate), such as the template, method, methodParams, passRate or cmpArea, the command performs image comparison the same way a corresponding Compareto command would do. Even if none of the parameters is specified, the command searches the template directory for an image of the same name as the screen shot one and performs image comparison with default parameter values if such an image is found. This "auto comparison" may be switched off in the Screenshot preferences. Default parameter values may be configured there as well.

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:
file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.
description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.
area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.
templates - list of template images to compare the remote desktop image to.
method - image comparison method. The value must correspond to one of the plugin codes (Plugin.getCode() of the installed image comparison module plugins. T-Plan Robot Enterprise provides by default two built-in methods, "default" and "search". See the "Image Comparison With T-Plan Robot Enterprise" document for more information.
methodParams - method parameters. This is a legacy helper argument intended to give third parties an option to specify custom parameters to the custom image comparison plugins, for example in a form of comma separated values. This argument is not used by any of the built-in T-Plan Robot Enterprise image comparison methods and it should be specified as null.
passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.
cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.
drawResults - indicates whether results of image comparison should be painted into the captured screen shot. The default value is false (meaning "do not paint any results"). If the command doesn't employ image comparison or the specified comparison method doesn't support result painting the parameter is ignored. In the default configuration, the "default" image comparison method doesn't support result painting because it doesn't make sense with regard to the algorithm nature. The"search" method does support result painting and draws rectangles corresponding to the match locations in the color specified in command configuration.
Returns:
command exit code as is specified in the Screenshot specification.
Throws:
java.io.IOException - when an I/O error occurs.

screenshot

public int screenshot(java.io.File file,
                      java.lang.String description,
                      java.awt.Rectangle area,
                      java.awt.Image[] templates,
                      java.lang.String method,
                      java.lang.String methodParams,
                      float passRate,
                      java.awt.Rectangle cmpArea)
               throws java.io.IOException

Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template. The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

If at least one of the image comparison parameters is specified (not null or positive in case of pass rate), such as the template, method, methodParams, passRate or cmpArea, the command performs image comparison the same way a corresponding Compareto command would do. Even if none of the parameters is specified, the command searches the template directory for an image of the same name as the screen shot one and performs image comparison with default parameter values if such an image is found. This "auto comparison" may be switched off in the Screenshot preferences. Default parameter values may be configured there as well.

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:
file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.
description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.
area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.
templates - list of template images to compare the remote desktop image to.
method - image comparison method. The value must correspond to one of the plugin codes (Plugin.getCode() of the installed image comparison module plugins. T-Plan Robot Enterprise provides by default two built-in methods, "default" and "search". See the "Image Comparison With T-Plan Robot Enterprise" document for more information.
methodParams - method parameters. This is a legacy helper argument intended to give third parties an option to specify custom parameters to the custom image comparison plugins, for example in a form of comma separated values. This argument is not used by any of the built-in T-Plan Robot Enterprise image comparison methods and it should be specified as null.
passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.
cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.
Returns:
command exit code as is specified in the Screenshot specification.
Throws:
java.io.IOException - when an I/O error occurs.

screenshot

public int screenshot(java.io.File file,
                      java.lang.String description,
                      java.awt.Rectangle area,
                      java.io.File[] templates,
                      java.lang.String method,
                      java.lang.String methodParams,
                      float passRate,
                      java.awt.Rectangle cmpArea,
                      java.lang.Integer rgbTolerance,
                      boolean drawResults,
                      boolean drawDiff)
               throws java.io.IOException

Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template. The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

If at least one of the image comparison parameters is specified (not null or positive in case of pass rate), such as the template, method, methodParams, passRate or cmpArea, the command performs image comparison the same way a corresponding Compareto command would do. Even if none of the parameters is specified, the command searches the template directory for an image of the same name as the screen shot one and performs image comparison with default parameter values if such an image is found. This "auto comparison" may be switched off in the Screenshot preferences. Default parameter values may be configured there as well.

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:
file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.
description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.
area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.
templates - list of template images to compare the remote desktop image to.
method - image comparison method. The value must correspond to one of the plugin codes (Plugin.getCode() of the installed image comparison module plugins. T-Plan Robot Enterprise provides by default two built-in methods, "default" and "search". See the "Image Comparison With T-Plan Robot Enterprise" document for more information.
methodParams - method parameters. This is a legacy helper argument intended to give third parties an option to specify custom parameters to the custom image comparison plugins, for example in a form of comma separated values. This argument is not used by any of the built-in T-Plan Robot Enterprise image comparison methods and it should be specified as null.
passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.
cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.
rgbTolerance - RGB tolerance value. This parameter may be populated only for "search" image comparison algorithm. It is a number between 0 and 100 and it specifies tolerance to color changes on the level of individual pixel R, G, B components. A value of 20 for example makes the search robust against color changes where any of the R, G, B components varies by 20 or less from the template image pixels. It is recommended to use higher values of this parameter or even the limit one of 100 for testing of environments with varying images (for example in Flash or Flex ones). To get best results it is also recommended avoid mixing of the RGB tolerance parameter with other tolerance mechanisms such as pass rate (should be set to 100%) and background filtering (should be off).

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

drawResults - indicates whether results of image comparison should be painted into the captured screen shot. The default value is false (meaning "do not paint any results"). If the command doesn't employ image comparison or the specified comparison method doesn't support result painting the parameter is ignored. In the default configuration, the "default" image comparison method doesn't support result painting because it doesn't make sense with regard to the algorithm nature. The"search" method does support result painting and draws rectangles corresponding to the match locations in the color specified in command configuration.
drawDiff - indicates whether the pixels differing from the template image should be painted in the configured color (green by default). The parameter was introduced in v3.3.1 to support image difference tracking in reports. The default value is false (meaning "do not paint the difference"). If the command doesn't employ image comparison or the specified comparison method doesn't support pixel difference tracking the parameter is ignored. This feature is supported only by the "search" and "search2" algorithms.
Returns:
command exit code as is specified in the Screenshot specification.
Throws:
java.io.IOException - when an I/O error occurs.
Since:
3.3.1

screenshot

public int screenshot(java.io.File file,
                      java.lang.String description,
                      java.awt.Rectangle area,
                      java.io.File[] templates,
                      java.lang.String method,
                      java.lang.String methodParams,
                      float passRate,
                      java.awt.Rectangle cmpArea,
                      java.lang.Integer rgbTolerance,
                      boolean drawResults)
               throws java.io.IOException

Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template. The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

If at least one of the image comparison parameters is specified (not null or positive in case of pass rate), such as the template, method, methodParams, passRate or cmpArea, the command performs image comparison the same way a corresponding Compareto command would do. Even if none of the parameters is specified, the command searches the template directory for an image of the same name as the screen shot one and performs image comparison with default parameter values if such an image is found. This "auto comparison" may be switched off in the Screenshot preferences. Default parameter values may be configured there as well.

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:
file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.
description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.
area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.
templates - list of template images to compare the remote desktop image to.
method - image comparison method. The value must correspond to one of the plugin codes (Plugin.getCode() of the installed image comparison module plugins. T-Plan Robot Enterprise provides by default two built-in methods, "default" and "search". See the "Image Comparison With T-Plan Robot Enterprise" document for more information.
methodParams - method parameters. This is a legacy helper argument intended to give third parties an option to specify custom parameters to the custom image comparison plugins, for example in a form of comma separated values. This argument is not used by any of the built-in T-Plan Robot Enterprise image comparison methods and it should be specified as null.
passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.
cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.
rgbTolerance - RGB tolerance value. This parameter may be populated only for "search" image comparison algorithm. It is a number between 0 and 100 and it specifies tolerance to color changes on the level of individual pixel R, G, B components. A value of 20 for example makes the search robust against color changes where any of the R, G, B components varies by 20 or less from the template image pixels. It is recommended to use higher values of this parameter or even the limit one of 100 for testing of environments with varying images (for example in Flash or Flex ones). To get best results it is also recommended avoid mixing of the RGB tolerance parameter with other tolerance mechanisms such as pass rate (should be set to 100%) and background filtering (should be off).

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

drawResults - indicates whether results of image comparison should be painted into the captured screen shot. The default value is false (meaning "do not paint any results"). If the command doesn't employ image comparison or the specified comparison method doesn't support result painting the parameter is ignored. In the default configuration, the "default" image comparison method doesn't support result painting because it doesn't make sense with regard to the algorithm nature. The"search" method does support result painting and draws rectangles corresponding to the match locations in the color specified in command configuration.
Returns:
command exit code as is specified in the Screenshot specification.
Throws:
java.io.IOException - when an I/O error occurs.

screenshot

public int screenshot(java.io.File file,
                      java.lang.String description,
                      java.awt.Rectangle area,
                      java.io.File[] templates,
                      float passRate,
                      java.awt.Rectangle cmpArea,
                      java.lang.String sort,
                      boolean drawResults,
                      boolean drawDiff)
               throws java.io.IOException

Take a screen shot of the remote desktop or its part, save it to a file and perform image comparison with the given template(s) using the Enterprise Image Search v2 method (code "search2"). The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

If at least one of the image comparison parameters is specified (not null or positive in case of pass rate), such as the template, method, methodParams, passRate or cmpArea, the command performs image comparison the same way a corresponding Compareto command would do. Even if none of the parameters is specified, the command searches the template directory for an image of the same name as the screen shot one and performs image comparison with default parameter values if such an image is found. This "auto comparison" may be switched off in the Screenshot preferences. Default parameter values may be configured there as well.

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:
file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.
description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.
area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.
templates - list of template images to compare the remote desktop image to.
passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.
cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.
sort - the sort order for the resulting match locations (Point/Rectangle). Supported modes:
  • "best" - Put the best matching location first (default mode).
  • "none" - Don't sort and leave the results in their natural "reading" order (left to right, top to bottom). This mode will produce the same order as the legacy "search" method.
  • "top" - Sort locations from the top to the bottom (topmost first).
  • "bottom" - Sort locations from the bottom to the top (bottommost first).
  • "left" - Sort locations from the left to the right (leftmost first).
  • "right" - Sort locations from the right to the left (rightmost first).
When the argument is null the sort mode defaults to the "best" one.
drawResults - indicates whether results of image comparison should be painted into the captured screen shot. The default value is false (meaning "do not paint any results"). The "search2" method does support result painting and draws rectangles corresponding to the match locations in the color specified in command configuration.
drawDiff - indicates whether the pixels differing from the template image should be painted in the configured color (green by default). The parameter was introduced in v3.3.1 to support image difference tracking in reports. The default value is false (meaning "do not paint the difference"). If the command doesn't employ image comparison or the specified comparison method doesn't support pixel difference tracking the parameter is ignored. This feature is supported only by the "search" and "search2" algorithms.
Returns:
command exit code as is specified in the Screenshot specification.
Throws:
java.io.IOException - when an I/O error occurs.
Since:
3.3.1

screenshot

public int screenshot(java.io.File file,
                      java.lang.String description,
                      java.awt.Rectangle area,
                      java.io.File[] templates,
                      float passRate,
                      java.awt.Rectangle cmpArea,
                      java.lang.String sort,
                      float[] scale,
                      boolean drawResults,
                      boolean drawDiff)
               throws java.io.IOException

Take a screen shot of the remote desktop or its part, save it to a file and perform image comparison with the given template(s) using the Enterprise Image Search v2 method (code "search2"). The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

If at least one of the image comparison parameters is specified (not null or positive in case of pass rate), such as the template, method, methodParams, passRate or cmpArea, the command performs image comparison the same way a corresponding Compareto command would do. Even if none of the parameters is specified, the command searches the template directory for an image of the same name as the screen shot one and performs image comparison with default parameter values if such an image is found. This "auto comparison" may be switched off in the Screenshot preferences. Default parameter values may be configured there as well.

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:
file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.
description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.
area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.
templates - list of template images to compare the remote desktop image to.
passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.
cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.
sort - the sort order for the resulting match locations (Point/Rectangle). Supported modes:
  • "best" - Put the best matching location first (default mode).
  • "none" - Don't sort and leave the results in their natural "reading" order (left to right, top to bottom). This mode will produce the same order as the legacy "search" method.
  • "top" - Sort locations from the top to the bottom (topmost first).
  • "bottom" - Sort locations from the bottom to the top (bottommost first).
  • "left" - Sort locations from the left to the right (leftmost first).
  • "right" - Sort locations from the right to the left (rightmost first).
When the argument is null the sort mode defaults to the "best" one.
scale - allows to search for scaled instances of the input image (supported since 4.0). To set off scaling use the value of 0 (ignore) or 1 (use original size). When the value is greater than zero it is being handled as a scale ratio. For example, the value of 2.0 will search for the component whose width and height are magnified twice.

There are two negative constants which can be specified to employ dynamic scaling. They will scale the input image(s) with regard to the difference between the current desktop resolution and size of the desktop the template (component) image was created from. As Robot 3.x and older did not save the desktop resolution to the template meta data, the image must be created or updated with Robot 4.0 to enable this operation. The supported scale modes are:

  • -1 ("stretch mode") will scale the input image following the desktop width and height changes independently. The resulting image may or may not have the same width and height proportions (the width/height ratio).
  • -2 ("proportional scale mode") will pick up the smaller relative change of the desktop width and height and use it for both width and height scaling. The resulting image will have the the same proportions (the width/height ratio).
drawResults - indicates whether results of image comparison should be painted into the captured screen shot. The default value is false (meaning "do not paint any results"). The "search2" method does support result painting and draws rectangles corresponding to the match locations in the color specified in command configuration.
drawDiff - indicates whether the pixels differing from the template image should be painted in the configured color (green by default). The parameter was introduced in v3.3.1 to support image difference tracking in reports. The default value is false (meaning "do not paint the difference"). If the command doesn't employ image comparison or the specified comparison method doesn't support pixel difference tracking the parameter is ignored. This feature is supported only by the "search" and "search2" algorithms.
Returns:
command exit code as is specified in the Screenshot specification.
Throws:
java.io.IOException - when an I/O error occurs.
Since:
4.0

screenshot

public int screenshot(java.io.File file,
                      java.lang.String description,
                      java.awt.Rectangle area,
                      java.io.File[] templates,
                      float passRate,
                      java.awt.Rectangle cmpArea,
                      java.lang.String sort,
                      boolean drawResults)
               throws java.io.IOException

Take a screen shot of the remote desktop or its part, save it to a file and perform image comparison with the given template(s) using the Enterprise Image Search v2 method (code "search2"). The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

If at least one of the image comparison parameters is specified (not null or positive in case of pass rate), such as the template, method, methodParams, passRate or cmpArea, the command performs image comparison the same way a corresponding Compareto command would do. Even if none of the parameters is specified, the command searches the template directory for an image of the same name as the screen shot one and performs image comparison with default parameter values if such an image is found. This "auto comparison" may be switched off in the Screenshot preferences. Default parameter values may be configured there as well.

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:
file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.
description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.
area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.
templates - list of template images to compare the remote desktop image to.
passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.
cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.
sort - the sort order for the resulting match locations (Point/Rectangle). Supported modes:
  • "best" - Put the best matching location first (default mode).
  • "none" - Don't sort and leave the results in their natural "reading" order (left to right, top to bottom). This mode will produce the same order as the legacy "search" method.
  • "top" - Sort locations from the top to the bottom (topmost first).
  • "bottom" - Sort locations from the bottom to the top (bottommost first).
  • "left" - Sort locations from the left to the right (leftmost first).
  • "right" - Sort locations from the right to the left (rightmost first).
When the argument is null the sort mode defaults to the "best" one.
drawResults - indicates whether results of image comparison should be painted into the captured screen shot. The default value is false (meaning "do not paint any results"). The "search2" method does support result painting and draws rectangles corresponding to the match locations in the color specified in command configuration.
Returns:
command exit code as is specified in the Screenshot specification.
Throws:
java.io.IOException - when an I/O error occurs.

screenshot

public int screenshot(java.io.File file,
                      java.lang.String description,
                      java.awt.Rectangle area,
                      java.awt.Rectangle cmpArea,
                      java.lang.String language,
                      java.lang.String text,
                      java.lang.String pattern)
               throws java.io.IOException

Take a screen shot of the remote desktop or its part, save it to a file and perform Tesseract OCR to recognize text from the desktop image or its part. The method provides access to functionality of the Screenshot scripting language command combined with image comparison method fixed to "tocr" and support of its specific parameters. See also the TesseractOCR class documentation for details on how to install and configure Tesseract.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Result of OCR is indicated by the return value where 0 usually means success, and 1 (one) indicates negative result. This method by default returns the value of 0 if the OCR is performed successfully and the value of 1 if the command fails, for example when the engine is not installed or misconfigured or the language code is not supported. If either 'text' or 'pattern' parameter is specified, the method returns 0 to indicate success only if the OCR performs successfully and the resulting text contains the string specified by 'text' or matches the 'pattern' regular expression.

The resulting text from OCR is stored in form of individual text lines to _TOCR_LINE[line_number] variables into the context. The number of resulting text lines is available from the _TOCR_LINE_COUNT variable. The whole text including the new line characters is also available as a String through the getContext().get(TesseractOCR.CONTEXT_TOCR_TEXT) method.

If the OCR throws an error caused by misconfiguration or an I/O error, the method returns the value of 1. Text of the errors is made available through the _TOCR_ERROR variable. Testing of existence of this variable is the only way to detect core OCR errors in test scripts.

Parameters:
file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.
description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.
area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.
cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.
language - target language (optional). It must be the 3-char lower case code of a properly installed Tesseract language data file set. For example, English code is "eng", German is "deu", Spanish is "spa" etc. This parameter will be passed as value of the "-l" argument to the engine. See the Tesseract's download page for the list of supported language files.
text - a string to look for in the recognized text (optional). If the parameter is specified (not null), the 'pattern' parameter must be null. If the string is found in the text resulting from OCR, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.
pattern - a Pattern compatible regular expression to match against the recognized text (optional). If the parameter is specified (not null), the 'text' parameter must be null. If the text resulting from OCR matches the regular expression, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.
Returns:
command exit code as is specified in the Screenshot specification.
Throws:
java.io.IOException - when an I/O error occurs.

screenshot

public int screenshot(java.io.File file,
                      java.lang.String description,
                      java.awt.Rectangle area,
                      java.awt.Rectangle cmpArea,
                      java.lang.String language,
                      float scale,
                      java.lang.String text,
                      int distance,
                      java.lang.String pattern)
               throws java.io.IOException

Take a screen shot of the remote desktop or its part, save it to a file and perform Tesseract OCR to recognize text from the desktop image or its part. The method provides access to functionality of the Screenshot scripting language command combined with image comparison method fixed to "tocr" and support of its specific parameters. See also the TesseractOCR class documentation for details on how to install and configure Tesseract.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Result of OCR is indicated by the return value where 0 usually means success, and 1 (one) indicates negative result. This method by default returns the value of 0 if the OCR is performed successfully and the value of 1 if the command fails, for example when the engine is not installed or misconfigured or the language code is not supported. If either 'text' or 'pattern' parameter is specified, the method returns 0 to indicate success only if the OCR performs successfully and the resulting text contains the string specified by 'text' or matches the 'pattern' regular expression.

The resulting text from OCR is stored in form of individual text lines to _TOCR_LINE[line_number] variables into the context. The number of resulting text lines is available from the _TOCR_LINE_COUNT variable. The whole text including the new line characters is also available as a String through the getContext().get(TesseractOCR.CONTEXT_TOCR_TEXT) method.

If the OCR throws an error caused by misconfiguration or an I/O error, the method returns the value of 1. Text of the errors is made available through the _TOCR_ERROR variable. Testing of existence of this variable is the only way to detect core OCR errors in test scripts.

Parameters:
file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.
description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.
area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.
cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the OCR will be performed on the full desktop image.
language - target language (optional). It must be the 3-char lower case code of a properly installed Tesseract language data file set. For example, English code is "eng", German is "deu", Spanish is "spa" etc. This parameter will be passed as value of the "-l" argument to the engine. See the Tesseract's download page for the list of supported language files. If the parameter is null, it will default to the English one ("eng").
scale - magnification factor. The method magnifies (enlarges) the image by the given factor to improve OCR accuracy. If this parameter is set to a value below 0, it defaults to the value configured in the Tesseract OCR Plugin preferences (the factory setting is 2 meaning that the image shall be enlarged to 200% of its original size).
text - a string to look for in the recognized text (optional). If the parameter is specified (not null), the 'pattern' parameter must be null. If the string is found in the text resulting from OCR, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.
distance - fuzzy string matching factor applied to comparison of the recognized text with value of the 'text' parameter. The distance is an integer based on the Levenshtein distance. It is defined as the minimum number of edits needed to transform one string into the other, with the allowable edit operations being insertion, deletion, or substitution of a single character. This metric is exposed as a new parameter called 'distance' which is an integer number specifying how many characters may be omitted or not recognized properly at a maximum to consider the sample text provided in the 'text' parameter equivalent.

Unlike the regular expressions the 'distance' parameter always searches the recognized text for any occurrence of a string matching the given text and distance. There's no need to specify that the string is preceded or trailed by another text. For example, the parameters of distance=1 and test=Apple will produce positive comparison result against recognized text of "The apple is red" because the text contains the word "apple" which may be converted to "Apple" in one character substitution.

pattern - a Pattern compatible regular expression to match against the recognized text (optional). If the parameter is specified (not null), the 'text' parameter must be null. If the text resulting from OCR matches the regular expression, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.
Returns:
command exit code as is specified in the Screenshot specification.
Throws:
java.io.IOException - when an I/O error occurs.

screenshot

public int screenshot(java.io.File file,
                      java.lang.String description,
                      java.awt.Rectangle area,
                      java.awt.Rectangle cmpArea,
                      java.lang.String language,
                      float scale,
                      java.lang.String text,
                      int distance,
                      java.lang.String pattern,
                      int mode,
                      int filter,
                      int fontSize)
               throws java.io.IOException

Take a screen shot of the remote desktop or its part, save it to a file and perform Tesseract OCR to recognize text from the desktop image or its part. The method provides access to functionality of the Screenshot scripting language command combined with image comparison method fixed to "tocr" and support of its specific parameters. See also the TesseractOCR class documentation for details on how to install and configure Tesseract.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Result of OCR is indicated by the return value where 0 usually means success, and 1 (one) indicates negative result. This method by default returns the value of 0 if the OCR is performed successfully and the value of 1 if the command fails, for example when the engine is not installed or misconfigured or the language code is not supported. If either 'text' or 'pattern' parameter is specified, the method returns 0 to indicate success only if the OCR performs successfully and the resulting text contains the string specified by 'text' or matches the 'pattern' regular expression.

The resulting text from OCR is stored in form of individual text lines to _TOCR_LINE[line_number] variables into the context. The number of resulting text lines is available from the _TOCR_LINE_COUNT variable. The whole text including the new line characters is also available as a String through the getContext().get(TesseractOCR.CONTEXT_TOCR_TEXT) method.

If the OCR throws an error caused by misconfiguration or an I/O error, the method returns the value of 1. Text of the errors is made available through the _TOCR_ERROR variable. Testing of existence of this variable is the only way to detect core OCR errors in test scripts.

Parameters:
file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.
description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.
area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.
cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the OCR will be performed on the full desktop image.
language - target language (optional). It must be the 3-char lower case code of a properly installed Tesseract language data file set. For example, English code is "eng", German is "deu", Spanish is "spa" etc. This parameter will be passed as value of the "-l" argument to the engine. See the Tesseract's download page for the list of supported language files. If the parameter is null, it will default to the English one ("eng").
scale - magnification factor. The method magnifies (enlarges) the image by the given factor to improve OCR accuracy. If this parameter is set to a value below 0, it defaults to the value configured in the Tesseract OCR Plugin preferences (the factory setting is 2 meaning that the image shall be enlarged to 200% of its original size).
text - a string to look for in the recognized text (optional). If the parameter is specified (not null), the 'pattern' parameter must be null. If the string is found in the text resulting from OCR, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.
distance - fuzzy string matching factor applied to comparison of the recognized text with value of the 'text' parameter. The distance is an integer based on the Levenshtein distance. It is defined as the minimum number of edits needed to transform one string into the other, with the allowable edit operations being insertion, deletion, or substitution of a single character. This metric is exposed as a new parameter called 'distance' which is an integer number specifying how many characters may be omitted or not recognized properly at a maximum to consider the sample text provided in the 'text' parameter equivalent.

Unlike the regular expressions the 'distance' parameter always searches the recognized text for any occurrence of a string matching the given text and distance. There's no need to specify that the string is preceded or trailed by another text. For example, the parameters of distance=1 and test=Apple will produce positive comparison result against recognized text of "The apple is red" because the text contains the word "apple" which may be converted to "Apple" in one character substitution.

pattern - a Pattern compatible regular expression to match against the recognized text (optional). If the parameter is specified (not null), the 'text' parameter must be null. If the text resulting from OCR matches the regular expression, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.
mode - the OCR mode (since 3.5). It allows to modify the engine behavior in special cases to get better results. This parameter is optional. To leave the mode on default specify any value equal to or less than 1. The supported modes are:
  1. Default Tesseract mode (the value of 1). It is the Tesseract's default mode of automatic page segmentation with no OSD (the "-psm 3" CLI switch). This value is compatible with the Robot releases prior to 3.5.
  2. High accuracy (mode 2). This is a Robot enhancement which splits the text on the screen into lines and reapplies the OCR separately in the line mode (-psm 7). This approach is several times slower but typically delivers more accurate results, especially where the OCR is applied to a smaller screen area such as an application window.
  3. Treat the image as a single word (mode 8). Use this mode when the recognized text is up to 3 characters long. This is Tesseract's native mode driven through the "-psm 8" CLI switch.
filter - optional image filter code (since 3.5). It removes certain artifacts on the screen in order to improve the OCR accuracy. The filter should be applied selectively where the target screen or its part contains text of dark color in rectangular areas with solid color background, such as for example application windows with standard solid gray or white buttons, drop downs and other components. White or bright color text and rich color graphics such as images or photographs are not suitable for filtering. Usage of the filter in such scenes may damage the text and decrease the OCR accuracy.

The supported filter codes are:
  1. 0 - No filter (default).
  2. 1 - Remove artefacts. It will remove typical application components consisting of horizontal and vertical solid color lines (borders).
  3. 2 - Remove artefacts and underlines will remove components and single character underlines typical for application menus.
  4. 3 - Remove artefacts, underlines and dashed lines will remove components, underlines and any dashed line borders which typically mark a selected component or the one that currently owns the focus. The dash line pattern must be populated properly in the 'tocr' method preferences in order to get recognized and removed properly.
The filter is optional. To leave this parameter on default provide any value equal to or less than 0.
fontSize - an approximate font size of the text to be recognized (since 3.5). The default value is 15. It is used only when the image filter is on. It tells the filter not to remove artifacts that are smaller than or equal to the font size. When the value is much smaller than the actual font size the filter may cripple some of the characters. When the value is too large the filter will fail to remove certain artifacts (components) from the screen which may result in lower accuracy.

The font size is optional. To leave this parameter on default provide any value equal to or less than 0.
Returns:
command exit code as is specified in the Screenshot specification.
Throws:
java.io.IOException - when an I/O error occurs.

screenshot

public int screenshot(java.io.File file,
                      java.lang.String description,
                      java.awt.Rectangle area,
                      java.io.File[] templates,
                      float passRate,
                      java.awt.Rectangle cmpArea,
                      java.lang.String text,
                      int distance,
                      java.lang.String pattern,
                      boolean drawResults)
               throws java.io.IOException

Take a screen shot of the remote desktop or its part, save it to a file and call the Image Based Text Recognition comparison method to recognize text from the desktop image or its part. The method provides access to functionality of the Screenshot scripting language command combined with image comparison method fixed to "text" and support of its specific parameters.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

The resulting text from the method is stored in form of individual text lines to _TEXT_LINE[line_number] variables into the context. The number of resulting text lines is available from the _TEXT_LINE_COUNT variable and can be retrieved using the getVariableAsInt("_TEXT_LINE_COUNT") method. The whole text including the new line characters as well as the map of text elements and their coordinates can be obtained directly from the context through the getContext().getRecognizedText(java.awt.Rectangle) and getContext().getRecognizedTextElements() methods.

If the method throws an error caused by misconfiguration or an I/O error, the method returns the value of 1. Text of the errors is made available through the _TEXT_ERROR variable.

Parameters:
cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the recognition will be performed on the full desktop image.
text - a string to look for in the recognized text (optional). If the parameter is specified (not null), the 'pattern' parameter must be null. If the string is found in the recognized text the method returns 0 to indicate success. Otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.
distance - fuzzy string matching factor applied to comparison of the recognized text with value of the 'text' parameter. The distance is an integer based on the Levenshtein distance. It is defined as the minimum number of edits needed to transform one string into the other, with the allowable edit operations being insertion, deletion, or substitution of a single character. This metric is exposed as a new parameter called 'distance' which is an integer number specifying how many characters may be omitted or not recognized properly at a maximum to consider the sample text provided in the 'text' parameter equivalent. The default value of this parameter is 0 which will force exact comparison with the specified text.

Unlike the regular expressions the 'distance' parameter always searches the recognized text for any occurrence of a string matching the given text and distance. There's no need to specify that the string is preceded or trailed by another text. For example, the parameters of distance=1 and test=Apple will produce positive comparison result against recognized text of "The apple is red" because the text contains the word "apple" which may be converted to "Apple" in one character substitution.

pattern - a Pattern compatible regular expression to match against the recognized text (optional). If the parameter is specified (not null), the 'text' parameter must be null. If the recognized text matches the regular expression, the method returns 0 to indicate success or 1 otherwise. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.
Returns:
the exit code as is specified in the Image Based Text Recognition specification. When none of the "text", "distance" and "pattern" parameters is specified the method returns 0 (success) to indicate a successful execution even when no text gets actually recognized. If the text matching parameters are used the method will return either success (0) or fail (non-zero value) depending on whether the recognized text matches or not.
Throws:
java.io.IOException - on an I/O error (can't read an image file and/or can't get image of the remote desktop).

screenshot

public int screenshot(java.io.File file,
                      java.lang.String description,
                      java.awt.Rectangle area,
                      java.io.File[] templates,
                      java.lang.String method,
                      java.lang.String methodParams,
                      float passRate,
                      java.awt.Rectangle cmpArea,
                      boolean drawResults,
                      boolean drawDiff)
               throws java.io.IOException

Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template. The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

If at least one of the image comparison parameters is specified (not null or positive in case of pass rate), such as the template, method, methodParams, passRate or cmpArea, the command performs image comparison the same way a corresponding Compareto command would do. Even if none of the parameters is specified, the command searches the template directory for an image of the same name as the screen shot one and performs image comparison with default parameter values if such an image is found. This "auto comparison" may be switched off in the Screenshot preferences. Default parameter values may be configured there as well.

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:
file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.
description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.
area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.
templates - list of template images to compare the remote desktop image to.
method - image comparison method. The value must correspond to one of the plugin codes (Plugin.getCode() of the installed image comparison module plugins. T-Plan Robot Enterprise provides by default two built-in methods, "default" and "search". See the "Image Comparison With T-Plan Robot Enterprise" document for more information.
methodParams - method parameters. This is a legacy helper argument intended to give third parties an option to specify custom parameters to the custom image comparison plugins, for example in a form of comma separated values. This argument is not used by any of the built-in T-Plan Robot Enterprise image comparison methods and it should be specified as null.
passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.
cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.
drawResults - indicates whether results of image comparison should be painted into the captured screen shot. The default value is false (meaning "do not paint any results"). If the command doesn't employ image comparison or the specified comparison method doesn't support result painting the parameter is ignored. In the default configuration, the "default" image comparison method doesn't support result painting because it doesn't make sense with regard to the algorithm nature. The"search" method does support result painting and draws rectangles corresponding to the match locations in the color specified in command configuration.
drawDiff - indicates whether the pixels differing from the template image should be painted in the configured color (green by default). The parameter was introduced in v3.3.1 to support image difference tracking in reports. The default value is false (meaning "do not paint the difference"). If the command doesn't employ image comparison or the specified comparison method doesn't support pixel difference tracking the parameter is ignored. This feature is supported only by the "search" and "search2" algorithms.
Returns:
command exit code as is specified in the Screenshot specification.
Throws:
java.io.IOException - when an I/O error occurs.
Since:
3.3.1

screenshot

public int screenshot(java.io.File file,
                      java.lang.String description,
                      java.awt.Rectangle area,
                      java.io.File[] templates,
                      java.lang.String method,
                      java.lang.String methodParams,
                      float passRate,
                      java.awt.Rectangle cmpArea,
                      boolean drawResults)
               throws java.io.IOException

Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template. The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

If at least one of the image comparison parameters is specified (not null or positive in case of pass rate), such as the template, method, methodParams, passRate or cmpArea, the command performs image comparison the same way a corresponding Compareto command would do. Even if none of the parameters is specified, the command searches the template directory for an image of the same name as the screen shot one and performs image comparison with default parameter values if such an image is found. This "auto comparison" may be switched off in the Screenshot preferences. Default parameter values may be configured there as well.

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:
file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.
description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.
area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.
templates - list of template images to compare the remote desktop image to.
method - image comparison method. The value must correspond to one of the plugin codes (Plugin.getCode() of the installed image comparison module plugins. T-Plan Robot Enterprise provides by default two built-in methods, "default" and "search". See the "Image Comparison With T-Plan Robot Enterprise" document for more information.
methodParams - method parameters. This is a legacy helper argument intended to give third parties an option to specify custom parameters to the custom image comparison plugins, for example in a form of comma separated values. This argument is not used by any of the built-in T-Plan Robot Enterprise image comparison methods and it should be specified as null.
passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.
cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.
drawResults - indicates whether results of image comparison should be painted into the captured screen shot. The default value is false (meaning "do not paint any results"). If the command doesn't employ image comparison or the specified comparison method doesn't support result painting the parameter is ignored. In the default configuration, the "default" image comparison method doesn't support result painting because it doesn't make sense with regard to the algorithm nature. The"search" method does support result painting and draws rectangles corresponding to the match locations in the color specified in command configuration.
Returns:
command exit code as is specified in the Screenshot specification.
Throws:
java.io.IOException - when an I/O error occurs.

screenshot

public int screenshot(java.io.File file,
                      java.lang.String description,
                      java.awt.Rectangle area,
                      java.io.File[] templates,
                      float passRate,
                      java.awt.Rectangle cmpArea,
                      boolean removeBg,
                      java.lang.String bgColor,
                      java.lang.Integer minAlpha,
                      java.lang.Integer rgbTolerance,
                      boolean drawResults,
                      boolean drawDiff)
               throws java.io.IOException

Take a screen shot of the remote desktop or its part, save it to a file and perform image search using the "search" comparison method with the support of filtering background from the template image(s). The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

If at least one of the image comparison parameters is specified (not null or positive in case of pass rate), such as the template, method, methodParams, passRate or cmpArea, the command performs image comparison the same way a corresponding Compareto command would do. Even if none of the parameters is specified, the command searches the template directory for an image of the same name as the screen shot one and performs image comparison with default parameter values if such an image is found. This "auto comparison" may be switched off in the Screenshot preferences. Default parameter values may be configured there as well.

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:
file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.
description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.
area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.
templates - list of template images to compare the remote desktop image to.
passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.
cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.
removeBg -

set on/off filtering of background color from the template image. It is a new 2.1 feature allowing to search for objects on varying background. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). The background filter is applied only to completely opaque template images which do not contain any translucent or transparent pixels introduced through third party image editors. When an existing translucency is detected the filter is switched off silently and only the eventual minAlpha parameter is applied.

The default value is null (equivalent to "false") meaning that background filtering is off. See the Compareto documentation for details.

bgColor - optional color for the background filter. The parameter is ignored when background filtering is off. If the color is not specified (is null), the background filter will use color of the very first image pixel at [0,0] (upper left image corner).
minAlpha - translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing translucent pixels. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). Alpha is a pixel color component between 0 (transparent) and 255 (opaque) which defines the level of pixel translucency. The default minalpha value of null or -1 (internally equal to 255) instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Other values between 0 and 254 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit. Comparison of such pixels is based on color similarity with a fixed threshold.
rgbTolerance - RGB tolerance value. This parameter may be populated only for "search" image comparison algorithm. It is a number between 0 and 100 and it specifies tolerance to color changes on the level of individual pixel R, G, B components. A value of 20 for example makes the search robust against color changes where any of the R, G, B components varies by 20 or less from the template image pixels. It is recommended to use higher values of this parameter or even the limit one of 100 for testing of environments with varying images (for example in Flash or Flex ones). To get best results it is also recommended avoid mixing of the RGB tolerance parameter with other tolerance mechanisms such as pass rate (should be set to 100%) and background filtering (should be off).

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

drawResults - indicates whether results of image comparison should be painted into the captured screen shot. The default value is false (meaning "do not paint any results"). If the command doesn't employ image comparison or the specified comparison method doesn't support result painting the parameter is ignored. In the default configuration, the "default" image comparison method doesn't support result painting because it doesn't make sense with regard to the algorithm nature. The"search" method does support result painting and draws rectangles corresponding to the match locations in the color specified in command configuration.
drawDiff - indicates whether the pixels differing from the template image should be painted in the configured color (green by default). The parameter was introduced in v3.3.1 to support image difference tracking in reports. The default value is false (meaning "do not paint the difference"). If the command doesn't employ image comparison or the specified comparison method doesn't support pixel difference tracking the parameter is ignored. This feature is supported only by the "search" and "search2" algorithms.
Returns:
command exit code as is specified in the Screenshot specification.
Throws:
java.io.IOException - when an I/O error occurs.
Since:
3.3.1

screenshot

public int screenshot(java.io.File file,
                      java.lang.String description,
                      java.awt.Rectangle area,
                      java.io.File[] templates,
                      float passRate,
                      java.awt.Rectangle cmpArea,
                      boolean removeBg,
                      java.lang.String bgColor,
                      java.lang.Integer minAlpha,
                      java.lang.Integer rgbTolerance,
                      boolean drawResults)
               throws java.io.IOException

Take a screen shot of the remote desktop or its part, save it to a file and perform image search using the "search" comparison method with the support of filtering background from the template image(s). The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

If at least one of the image comparison parameters is specified (not null or positive in case of pass rate), such as the template, method, methodParams, passRate or cmpArea, the command performs image comparison the same way a corresponding Compareto command would do. Even if none of the parameters is specified, the command searches the template directory for an image of the same name as the screen shot one and performs image comparison with default parameter values if such an image is found. This "auto comparison" may be switched off in the Screenshot preferences. Default parameter values may be configured there as well.

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:
file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.
description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.
area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.
templates - list of template images to compare the remote desktop image to.
passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.
cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.
removeBg -

set on/off filtering of background color from the template image. It is a new 2.1 feature allowing to search for objects on varying background. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). The background filter is applied only to completely opaque template images which do not contain any translucent or transparent pixels introduced through third party image editors. When an existing translucency is detected the filter is switched off silently and only the eventual minAlpha parameter is applied.

The default value is null (equivalent to "false") meaning that background filtering is off. See the Compareto documentation for details.

bgColor - optional color for the background filter. The parameter is ignored when background filtering is off. If the color is not specified (is null), the background filter will use color of the very first image pixel at [0,0] (upper left image corner).
minAlpha - translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing translucent pixels. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). Alpha is a pixel color component between 0 (transparent) and 255 (opaque) which defines the level of pixel translucency. The default minalpha value of null or -1 (internally equal to 255) instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Other values between 0 and 254 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit. Comparison of such pixels is based on color similarity with a fixed threshold.
rgbTolerance - RGB tolerance value. This parameter may be populated only for "search" image comparison algorithm. It is a number between 0 and 100 and it specifies tolerance to color changes on the level of individual pixel R, G, B components. A value of 20 for example makes the search robust against color changes where any of the R, G, B components varies by 20 or less from the template image pixels. It is recommended to use higher values of this parameter or even the limit one of 100 for testing of environments with varying images (for example in Flash or Flex ones). To get best results it is also recommended avoid mixing of the RGB tolerance parameter with other tolerance mechanisms such as pass rate (should be set to 100%) and background filtering (should be off).

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

drawResults - indicates whether results of image comparison should be painted into the captured screen shot. The default value is false (meaning "do not paint any results"). If the command doesn't employ image comparison or the specified comparison method doesn't support result painting the parameter is ignored. In the default configuration, the "default" image comparison method doesn't support result painting because it doesn't make sense with regard to the algorithm nature. The"search" method does support result painting and draws rectangles corresponding to the match locations in the color specified in command configuration.
Returns:
command exit code as is specified in the Screenshot specification.
Throws:
java.io.IOException - when an I/O error occurs.

screenshot

public int screenshot(java.io.File file,
                      java.lang.String description,
                      java.awt.Rectangle area,
                      java.io.File[] templates,
                      float passRate,
                      java.awt.Rectangle cmpArea,
                      boolean removeBg,
                      java.lang.String bgColor,
                      java.lang.Integer minAlpha,
                      boolean drawResults)
               throws java.io.IOException

Take a screen shot of the remote desktop or its part, save it to a file and perform image search using the "search" comparison method with the support of filtering background from the template image(s). The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

If at least one of the image comparison parameters is specified (not null or positive in case of pass rate), such as the template, method, methodParams, passRate or cmpArea, the command performs image comparison the same way a corresponding Compareto command would do. Even if none of the parameters is specified, the command searches the template directory for an image of the same name as the screen shot one and performs image comparison with default parameter values if such an image is found. This "auto comparison" may be switched off in the Screenshot preferences. Default parameter values may be configured there as well.

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:
file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.
description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.
area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.
templates - list of template images to compare the remote desktop image to.
passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.
cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.
removeBg -

set on/off filtering of background color from the template image. It is a new 2.1 feature allowing to search for objects on varying background. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). The background filter is applied only to completely opaque template images which do not contain any translucent or transparent pixels introduced through third party image editors. When an existing translucency is detected the filter is switched off silently and only the eventual minAlpha parameter is applied.

The default value is null (equivalent to "false") meaning that background filtering is off. See the Compareto documentation for details.

bgColor - optional color for the background filter. The parameter is ignored when background filtering is off. If the color is not specified (is null), the background filter will use color of the very first image pixel at [0,0] (upper left image corner).
minAlpha - translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing translucent pixels. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). Alpha is a pixel color component between 0 (transparent) and 255 (opaque) which defines the level of pixel translucency. The default minalpha value of null or -1 (internally equal to 255) instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Other values between 0 and 254 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit. Comparison of such pixels is based on color similarity with a fixed threshold.
drawResults - indicates whether results of image comparison should be painted into the captured screen shot. The default value is false (meaning "do not paint any results"). If the command doesn't employ image comparison or the specified comparison method doesn't support result painting the parameter is ignored. In the default configuration, the "default" image comparison method doesn't support result painting because it doesn't make sense with regard to the algorithm nature. The"search" method does support result painting and draws rectangles corresponding to the match locations in the color specified in command configuration.
Returns:
command exit code as is specified in the Screenshot specification.
Throws:
java.io.IOException - when an I/O error occurs.

screenshot

public int screenshot(java.io.File file,
                      java.lang.String description,
                      java.awt.Rectangle area,
                      java.io.File[] templates,
                      java.lang.String method,
                      java.lang.String methodParams,
                      float passRate,
                      java.awt.Rectangle cmpArea)
               throws java.io.IOException

Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template. The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

If at least one of the image comparison parameters is specified (not null or positive in case of pass rate), such as the template, method, methodParams, passRate or cmpArea, the command performs image comparison the same way a corresponding Compareto command would do. Even if none of the parameters is specified, the command searches the template directory for an image of the same name as the screen shot one and performs image comparison with default parameter values if such an image is found. This "auto comparison" may be switched off in the Screenshot preferences. Default parameter values may be configured there as well.

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:
file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.
description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.
area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.
templates - list of template images to compare the remote desktop image to.
method - image comparison method. The value must correspond to one of the plugin codes (Plugin.getCode() of the installed image comparison module plugins. T-Plan Robot Enterprise provides by default two built-in methods, "default" and "search". See the "Image Comparison With T-Plan Robot Enterprise" document for more information.
methodParams - method parameters. This is a legacy helper argument intended to give third parties an option to specify custom parameters to the custom image comparison plugins, for example in a form of comma separated values. This argument is not used by any of the built-in T-Plan Robot Enterprise image comparison methods and it should be specified as null.
passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.
cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.
Returns:
command exit code as is specified in the Screenshot specification.
Throws:
java.io.IOException - when an I/O error occurs.

screenshot

public int screenshot(java.io.File file,
                      java.lang.String description,
                      java.awt.Rectangle area,
                      java.io.File template,
                      float passRate,
                      java.awt.Rectangle cmpArea,
                      java.awt.Color color,
                      java.awt.Color[] bridgeColors,
                      java.lang.Integer rgbTolerance,
                      java.lang.Integer rotations,
                      java.lang.Boolean draw,
                      java.lang.Boolean clear)
               throws java.io.IOException

Take a screen shot of the remote desktop or its part, save it to a file and perform image comparison using the Object Search method. The method provides access to functionality of the Screenshot scripting language command.

The method requires a desktop connection and throws an IllegalArgumentException if not connected. The target format is guessed from the argument file extension and the method throws an IllegalArgumentException if it is not supported. Images can be saved in any of the format supported by the current Java. Java 6 Standard Edition supports at least JPG/JPEG, BMP, WBMP, PNG and GIF formats. To get a complete list of formats supported by your Java use ImageIO.getWriterFileSuffixes().

Each successful call of this method inserts a data structure (OutputObject instance) with the screen shot name, description and eventual image comparison parameters to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

The method further on analyzes the current remote desktop image using the Object Search Method. It searches the desktop image or its rectangular part for objects of a particular color or colors within the tolerated RGB variance. It also allows to filter the object list by an optional template image with detection of eventual object rotation. The method was designed to handle simple image analysis tasks such as "find all black triangles in any level of rotation on the screen".

As the method always locates the largest possible object and it doesn't search recursively for any other ones it may contain, this approach is not suitable for classic GUI components which are often framed, overlayed and merged together. The method however performs very well in testing of schemes, maps and images with low color scenes generated for example by Geographic Information System (GIS) applications or systems producing simple image data. The method can be also employed to check whether an object of a certain color or color range is present on the screen, for example to answer a question like "is there any red message in this particular area?".

The algorithm first scans the image for the first pixel which meets the input color criteria. Than it follows the outer shape of each such an object until the shape gets closed. The objects are internally stored as a list of java.awt.Shape instances in the context and may be retrieved through the through the ScriptingContext.getObjectSearchShapes() convenience method. Besides the raw shape data the method also stores bounding rectangle of each object into the context in form of four variables _OBJECT_X_[n], _OBJECT_Y_[n], _OBJECT_W_[n] and _OBJECT_H_[n] which represent the top left corner [x,y] coordinates, width and height. The [n] expression is the object ordinary number starting from 1. The number of objects available is stored under the _OBJECT_COUNT variable. These variables are the only data exposed to the standard scripting language.

Parameters:
template - an optional template image to filter the list of objects by (a File instance). It must contain just one shape of the specified color and/or tolerance in any level of rotation. When it is provided, the list of objects will be filtered to leave just shapes which are similar to the template image shape up to the ratio specified by the 'passrate' parameter. If the 'rotations' parameter is also specified and is greater than 1, the object list will be matched against the list of template shapes rotated the specified number of times.

If the template image is not specified, the algorithm locates all objects matching the color parameters regardless of their size or shape.
passRate - pass rate as percentage between 0 and 100. The pass rate makes sense only when the template is not null and specifies the percentage of acceptable pixel variance from the template image.
cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.
color - defines the object color.
bridgeColors - is optional list of additional admissible object colors. This allows to search for continuous objects which are expected to have other objects of known colors painted over them. Colors in this list are always compared using the exact RGB match and they do not work with the rgbTolerance parameter.
rgbTolerance - RGB tolerance value. It must be an integer number between 0 and 256. It indicates how much the Red, Green and Blue components of a pixel may differ at a maximum to consider the color be equivalent to the object color specified by the 'color' parameter. This value allows to deal with blurred images where the shapes are not formed by a solid color but rather a range of similar colors. Be however aware that the higher the tolerance value, the higher the probability of false shape detections is. In most scenarios the value should be in the [0, 100] range depending on the blurring level. If the parameter is not specified, it defaults to zero and the algorithm looks for solid color objects only.

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

rotations - makes only sense when a template image is provided. It defines rotation granularity. It basically says how many times to rotate the object extracted from the template for filtering purposes. For example, the value of 36 will rotate the shape in 10 degree steps. Obviously, a high number of rotations increases accuracy of recognition of rotated objects but decreases performance. Low rotation values may be compensated through lowering the 'passrate' parameter. This approach is somewhat better in terms of performance but raises the risk of wrong detection of objects similar enough to the template one.
clear - optional boolean flag dealing with result highlighting in the GUI. The clear parameter allows to clear up all drawings created by the previously called object searches. The drawings are also automatically reset when the script finishes.
draw - optional boolean flag dealing with result highlighting in the GUI. When the draw parameter is 'true', the algorithm draws the object rectangles over the desktop image in the desktop viewer GUI component.
file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.
description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.
area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.
Returns:
command exit code as is specified in the Screenshot specification.
Throws:
java.io.IOException - when an I/O error occurs.

screenshot

public int screenshot(java.io.File file,
                      java.lang.String description,
                      java.awt.Rectangle area,
                      java.io.File[] templates,
                      java.lang.String method,
                      float passRate,
                      java.awt.Rectangle cmpArea)
               throws java.io.IOException

Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template. The method provides access to functionality of the Screenshot scripting language command. As this is just a convenience method calling the screenshot(java.io.File, java.lang.String, java.awt.Rectangle, java.io.File[], java.lang.String, java.lang.String, float, java.awt.Rectangle) one, see its documentation for a complete description.

Parameters:
file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.
description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.
area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.
templates - list of template images to compare the remote desktop image to.
method - image comparison method. The value must correspond to one of the plugin codes (Plugin.getCode() of the installed image comparison module plugins. T-Plan Robot Enterprise provides by default two built-in methods, "default" and "search". See the "Image Comparison With T-Plan Robot Enterprise" document for more information.
passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.
cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the comparison will be performed on the full desktop image. Image comparison area should be used just where it makes sense with regard to the method algorithm, for example with the "search" method. See the "Image Comparison With T-Plan Robot Enterprise" document for more information.
Returns:
command exit code as is specified in the Screenshot specification.
Throws:
java.io.IOException - when an I/O error occurs.

screenshot

public int screenshot(java.io.File file,
                      java.lang.String description,
                      java.awt.Rectangle area,
                      java.io.File[] templates,
                      java.lang.String method,
                      float passRate)
               throws java.io.IOException

Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template. The method provides access to functionality of the Screenshot scripting language command. As this is just a convenience method calling the screenshot(java.io.File, java.lang.String, java.awt.Rectangle, java.io.File[], java.lang.String, java.lang.String, float, java.awt.Rectangle) one, see its documentation for a complete description.

Parameters:
file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.
description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.
area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.
templates - list of template images to compare the remote desktop image to.
method - image comparison method. The value must correspond to one of the plugin codes (Plugin.getCode() of the installed image comparison module plugins. T-Plan Robot Enterprise provides by default two built-in methods, "default" and "search". See the "Image Comparison With T-Plan Robot Enterprise" document for more information.
passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.
Returns:
command exit code as is specified in the Screenshot specification.
Throws:
java.io.IOException - when an I/O error occurs.

screenshot

public int screenshot(java.io.File file,
                      java.lang.String description,
                      java.awt.Rectangle area,
                      java.io.File[] templates,
                      java.lang.String method,
                      float passRate,
                      java.lang.Integer rgbTolerance)
               throws java.io.IOException

Take a screen shot of the remote desktop or its part, save it to a file and eventually perform image comparison with the given template. The method provides access to functionality of the Screenshot scripting language command. As this is just a convenience method calling the screenshot(java.io.File, java.lang.String, java.awt.Rectangle, java.io.File[], java.lang.String, java.lang.String, float, java.awt.Rectangle) one, see its documentation for a complete description.

Parameters:
file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.
description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.
area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.
templates - list of template images to compare the remote desktop image to.
method - image comparison method. The value must correspond to one of the plugin codes (Plugin.getCode() of the installed image comparison module plugins. T-Plan Robot Enterprise provides by default two built-in methods, "default" and "search". See the "Image Comparison With T-Plan Robot Enterprise" document for more information.
passRate - image comparison pass rate specified as percentage. It indicates how much the images must match to consider the comparison as "pass". Interpretation of this value is up to individual plugin implementations. Both built-in T-Plan Robot Enterprise image comparison methods calculate how many different pixels the two compared images contain and compare this figure in relative form to the pass rate. If the specified pass rate is negative, it is interpreted as if it is not specified and default pass rate from the user preferences is used instead.
rgbTolerance - RGB tolerance value. This parameter may be populated only for "search" image comparison algorithm. It is a number between 0 and 100 and it specifies tolerance to color changes on the level of individual pixel R, G, B components. A value of 20 for example makes the search robust against color changes where any of the R, G, B components varies by 20 or less from the template image pixels. It is recommended to use higher values of this parameter or even the limit one of 100 for testing of environments with varying images (for example in Flash or Flex ones). To get best results it is also recommended avoid mixing of the RGB tolerance parameter with other tolerance mechanisms such as pass rate (should be set to 100%) and background filtering (should be off).

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

Returns:
command exit code as is specified in the Screenshot specification.
Throws:
java.io.IOException - when an I/O error occurs.

screenshot

public int screenshot(java.io.File file,
                      java.lang.String description,
                      java.awt.Rectangle area)
               throws java.io.IOException

Take a screen shot of the remote desktop or its part and save it to a file. The method provides access to functionality of the Screenshot scripting language command. As this is just a convenience method calling the screenshot(java.io.File, java.lang.String, java.awt.Rectangle, java.io.File[], java.lang.String, java.lang.String, float, java.awt.Rectangle) one, see its documentation for a complete description.

Parameters:
file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.
description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.
area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.
Returns:
command exit code as is specified in the Screenshot specification.
Throws:
java.io.IOException - when an I/O error occurs.

screenshot

public int screenshot(java.io.File file,
                      java.lang.String description)
               throws java.io.IOException

Take a screen shot of the remote desktop and save it to a file. The method provides access to functionality of the Screenshot scripting language command. As this is just a convenience method calling the screenshot(java.io.File, java.lang.String, java.awt.Rectangle, java.io.File[], java.lang.String, java.lang.String, float, java.awt.Rectangle) one, see its documentation for a complete description.

Parameters:
file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.
description - screen shot description. It doesn't get written to the image file. It is saved only to the internal data structure where it may be picked up by report providers.
Returns:
command exit code as is specified in the Screenshot specification.
Throws:
java.io.IOException - when an I/O error occurs.

screenshot

public int screenshot(java.io.File file,
                      java.awt.Rectangle area)
               throws java.io.IOException

Take a screen shot of the remote desktop or its part and save it to a file. The method provides access to functionality of the Screenshot scripting language command. As this is just a convenience method calling the screenshot(java.io.File, java.lang.String, java.awt.Rectangle, java.io.File[], java.lang.String, java.lang.String, float, java.awt.Rectangle) one, see its documentation for a complete description.

Parameters:
file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.
area - a rectangle to cut from the desktop image. If the argument is null, the method will save the full size remote desktop image.
Returns:
command exit code as is specified in the Screenshot specification.
Throws:
java.io.IOException - when an I/O error occurs.

screenshot

public int screenshot(java.io.File file)
               throws java.io.IOException

Take a screen shot of the remote desktop and save it to a file. The method provides access to functionality of the Screenshot scripting language command. As this is just a convenience method calling the screenshot(java.io.File, java.lang.String, java.awt.Rectangle, java.io.File[], java.lang.String, java.lang.String, float, java.awt.Rectangle) one, see its documentation for a complete description.

Parameters:
file - a file to save the image to. The file can be either relative or absolute and it must have extension of one of the image formats supported by Java. Files with a relative path will be saved to the configured output directory. This path is by default set to the user home directory and its default location can be configured in the preferences. It may be also overridden for the current script through the ScriptingContext.setOutputDir(java.io.File) method. If the specified file exists, it gets overwritten. If the user has not sufficient permissions to create this file, the method throws an IllegalArgumentException.
Returns:
command exit code as is specified in the Screenshot specification.
Throws:
java.io.IOException - when an I/O error occurs.

sendMail

public int sendMail(java.lang.String server,
                    java.lang.String user,
                    java.lang.String password,
                    java.lang.String from,
                    java.lang.String to,
                    java.lang.String subject,
                    java.lang.String text,
                    java.io.File[] attachments,
                    boolean debug)
             throws java.io.IOException

Send an E-mail of the specified subject, text and optional file attachments to one or more recipients through an SMTP server. The method provides access to functionality of the Sendmail scripting language command.

The method and the underlying command handler take advantage of the Java Mail API. It is provided as a separate library, typically in form of a file called mail.jar together with its dependency Java Activation Framework (activation.jar). Should you experience any ClassNotFoundException problems, check whether these two libraries are correctly included in your Java class path.

As some of the arguments such as server name and port, sender and recipient addresses and SMTP user name are often static for a particular user, it is possible to define their default values in the user preferences. These arguments may be then omitted (meaning specified as null) in the sendmail method calls. Note that all this data gets saved to a plain text configuration file in the user home directory and it shouldn't contain anything considered sensitive. For this reason there's no configuration parameter for SMTP password which must be specified in each method call (provided that the SMTP server requires authentication).

Parameters:
server - address and eventually port of the SMTP server. The host may be specified both by a name or numeric IP address, with an optional port number specified after a colon (for example, "mysmtp.mydomain.com:1234"). If no port is specified, the method defaults to the well known SMTP port of 25.
user - optional user name for authentication to the SMTP server.
password - optional password for authentication to the SMTP server.
from - sender address, for example "john.doe@mydomain.com". The method itself doesn't validate the address. If it is however invalid, the underlying JavaMail API may refuse it.
to - one or more recipient address(es) separated by comma.
subject - E-mail subject. It should be just plain text without any new line characters.
text - message body. To insert a new line character use "\n". For example, a text of "test\ntest" will resolve in two lines containing word "test". If the text starts with "" (not case sensitive), the content type is set to "text/html". Otherwise the mail body is sent as plain text ("text/plain").
attachments - optional file attachments.
debug - true switches on verbose mode provided by the JavaMail API framework. The method then prints out detailed messages of the SMTP server connection, authentication and message transfer. Use this mode to debug why the command fails.
Returns:
command exit code as is specified in the Sendmail specification.
Throws:
java.io.IOException - when an I/O error occurs.

sendMail

public int sendMail(java.lang.String password,
                    java.lang.String subject,
                    java.lang.String text,
                    java.io.File[] attachments,
                    boolean debug)
             throws java.io.IOException

Send an E-mail of the specified subject, text and optional file attachments to one or more recipients through an SMTP server. The method provides access to functionality of the Sendmail scripting language command. The method works correctly only if there are valid default values of the SMTP server, port and user, sender and recipient address(es) in the user preferences. If any of these values is missing, the method throws an IllegalArgumentException.

As this is just a convenience method calling the sendMail(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.io.File[], boolean) one, see its documentation for a complete description.

Parameters:
password - optional password for authentication to the SMTP server.
subject - E-mail subject. It should be just plain text without any new line characters.
text - message body. To insert a new line character use "\n". For example, a text of "test\ntest" will resolve in two lines containing word "test". If the text starts with "" (not case sensitive), the content type is set to "text/html". Otherwise the mail body is sent as plain text ("text/plain").
attachments - optional file attachments.
debug - true switches on verbose mode provided by the JavaMail API framework. The method then prints out detailed messages of the SMTP server connection, authentication and message transfer. Use this mode to debug why the command fails.
Returns:
command exit code as is specified in the Sendmail specification.
Throws:
java.io.IOException - when an I/O error occurs.

sendMail

public int sendMail(java.lang.String password,
                    java.lang.String subject,
                    java.lang.String text)
             throws java.io.IOException

Send an E-mail of the specified subject and text to one or more recipients through an SMTP server. The method provides access to functionality of the Sendmail scripting language command. The method works correctly only if there are valid default values of the SMTP server, port and user, sender and recipient address(es) in the user preferences. If any of these values is missing, the method throws an IllegalArgumentException.

As this is just a convenience method calling the sendMail(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.io.File[], boolean) one, see its documentation for a complete description.

Parameters:
password - optional password for authentication to the SMTP server.
subject - E-mail subject. It should be just plain text without any new line characters.
text - message body. To insert a new line character use "\n". For example, a text of "test\ntest" will resolve in two lines containing word "test". If the text starts with "" (not case sensitive), the content type is set to "text/html". Otherwise the mail body is sent as plain text ("text/plain").
Returns:
command exit code as is specified in the Sendmail specification.
Throws:
java.io.IOException - when an I/O error occurs.

sendMail

public int sendMail(java.lang.String subject,
                    java.lang.String text,
                    java.io.File[] attachments)
             throws java.io.IOException

Send an E-mail of the specified subject, text and optional file attachments to one or more recipients through an SMTP server which requires no authentication. The method provides access to functionality of the Sendmail scripting language command. It works correctly only if there are valid default values of the SMTP server, port and user, sender and recipient address(es) in the user preferences. If any of these values is missing, the method throws an IllegalArgumentException.

As this is just a convenience method calling the sendMail(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.io.File[], boolean) one, see its documentation for a complete description.

Parameters:
subject - E-mail subject. It should be just plain text without any new line characters.
text - message body. To insert a new line character use "\n". For example, a text of "test\ntest" will resolve in two lines containing word "test". If the text starts with "" (not case sensitive), the content type is set to "text/html". Otherwise the mail body is sent as plain text ("text/plain").
attachments - optional file attachments.
Returns:
command exit code as is specified in the Sendmail specification.
Throws:
java.io.IOException - when an I/O error occurs.

sendMail

public int sendMail(java.lang.String subject,
                    java.lang.String text)
             throws java.io.IOException

Send an E-mail of the specified subject and text to one or more recipients through an SMTP server which requires no authentication. The method provides access to functionality of the Sendmail scripting language command. It works correctly only if there are valid default values of the SMTP server, port and user, sender and recipient address(es) in the user preferences. If any of these values is missing, the method throws an IllegalArgumentException.

As this is just a convenience method calling the sendMail(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.io.File[], boolean) one, see its documentation for a complete description.

Parameters:
subject - E-mail subject. It should be just plain text without any new line characters.
text - message body. To insert a new line character use "\n". For example, a text of "test\ntest" will resolve in two lines containing word "test". If the text starts with "" (not case sensitive), the content type is set to "text/html". Otherwise the mail body is sent as plain text ("text/plain").
Returns:
command exit code as is specified in the Sendmail specification.
Throws:
java.io.IOException - when an I/O error occurs.

exec

public int exec(java.lang.String command,
                java.io.OutputStream out,
                int count,
                java.lang.String wait)
         throws java.io.IOException
Execute a command of the local operating system. The method provides access to functionality of the Exec scripting language command.

Parameters:
command - a command to be executed. On most systems the commands have a few limitations, such as no redirections and pipes are allowed. See Java documentation on Runtime.exec() for more information.
out - an output stream to write the command output to. If the argument is null, the output is thrown away.
count - how many times to execute the command. Default value is 1;
wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Exec specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

exec

public int exec(java.lang.String command,
                java.io.OutputStream out,
                boolean nowait,
                int count,
                java.lang.String wait)
         throws java.io.IOException
Execute a command of the local operating system. The method provides access to functionality of the Exec scripting language command.

Parameters:
command - a command to be executed. On most systems the commands have a few limitations, such as no redirections and pipes are allowed. See Java documentation on Runtime.exec() for more information.
out - an output stream to write the command output to. If the argument is null, the output is thrown away.
count - how many times to execute the command. Default value is 1;
wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
nowait - a flag specifying whether method should make the test script wait until the OS command finishes. The default value is false which makes it wait. When the value is set to true the method does not wait for the result and the test script continues immediately after the process is started. The _EXEC_OUTPUT and _EXEC_ERROR variables are not populated because the output is not known when the method returns the control to the calling script. The _EXEC_ERROR variable may be created if the underlying OS fails to start the specified command and reports it immediately to Robot.
Returns:
command exit code as is specified in the Exec specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.
Since:
3.4

exec

public int exec(java.lang.String command,
                java.io.OutputStream out)
         throws java.io.IOException
Convenience method employing the exec(java.lang.String, java.io.OutputStream, int, java.lang.String) method to execute a command once (count=1) with no waiting period specified (wait=null).

Parameters:
command - a command to be executed. On Unix/Linux systems the commands have a few limitations. No redirections and pipes are allowed. See Java documentation on Runtime.exec() for more information.
out - an output stream to write the command output to. If the argument is null, the output is thrown away.
Returns:
command exit code as is specified in the Exec specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

exec

public int exec(java.lang.String command,
                java.io.Writer out,
                int count,
                java.lang.String wait)
         throws java.io.IOException
Convenience method employing the exec(java.lang.String, java.io.OutputStream, int, java.lang.String) method with the command output redirected to a Writer rather than to an OutputStream.

Parameters:
command - a command to be executed. On Unix/Linux systems the commands have a few limitations. No redirections and pipes are allowed. See Java documentation on Runtime.exec() for more information.
out - a writer to write the command console output to. If the argument is null, the output is thrown away.
count - how many times to execute the command. Default value is 1;
wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Exec specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

exec

public int exec(java.lang.String command,
                java.io.Writer out,
                boolean nowait,
                int count,
                java.lang.String wait)
         throws java.io.IOException
Convenience method employing the exec(java.lang.String, java.io.OutputStream, int, java.lang.String) method with the command output redirected to a Writer rather than to an OutputStream.

Parameters:
command - a command to be executed. On Unix/Linux systems the commands have a few limitations. No redirections and pipes are allowed. See Java documentation on Runtime.exec() for more information.
out - a writer to write the command console output to. If the argument is null, the output is thrown away.
count - how many times to execute the command. Default value is 1;
wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
nowait - a flag specifying whether method should make the test script wait until the OS command finishes. The default value is false which makes it wait. When the value is set to true the method does not wait for the result and the test script continues immediately after the process is started. The _EXEC_OUTPUT and _EXEC_ERROR variables are not populated because the output is not known when the method returns the control to the calling script. The _EXEC_ERROR variable may be created if the underlying OS fails to start the specified command and reports it immediately to Robot.
Returns:
command exit code as is specified in the Exec specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.
Since:
3.4

exec

public int exec(java.lang.String command,
                java.io.Writer out)
         throws java.io.IOException
Convenience method employing the exec(java.lang.String, java.io.Writer, int, java.lang.String) method to execute a command once (count=1) with no waiting period specified (wait=null).

Parameters:
command - a command to be executed. On Unix/Linux systems the commands have a few limitations. No redirections and pipes are allowed. See Java documentation on Runtime.exec() for more information.
out - a writer to write the command console output to. If the argument is null, the output is thrown away.
Returns:
command exit code as is specified in the Exec specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

exec

public int exec(java.lang.String command,
                java.lang.String wait)
         throws java.io.IOException
Convenience method employing the exec(java.lang.String, java.io.OutputStream, int, java.lang.String) method to execute a command once (count=1) with no output stream (out=null) and no waiting period (wait=null).

Parameters:
command - a command to be executed. On Unix/Linux systems the commands have a few limitations. No redirections and pipes are allowed. See Java documentation on Runtime.exec() for more information.
wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command.
Returns:
command exit code as is specified in the Exec specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

exec

public int exec(java.lang.String command,
                boolean nowait)
         throws java.io.IOException
Convenience method employing the exec(java.lang.String, java.io.OutputStream, int, java.lang.String) method to execute a command without any further options.

Parameters:
command - a command to be executed. On Unix/Linux systems the commands have a few limitations. No redirections and pipes are allowed. See Java documentation on Runtime.exec() for more information.
nowait - a flag specifying whether method should make the test script wait until the OS command finishes. The default value is false which makes it wait. When the value is set to true the method does not wait for the result and the test script continues immediately after the process is started. The _EXEC_OUTPUT and _EXEC_ERROR variables are not populated because the output is not known when the method returns the control to the calling script. The _EXEC_ERROR variable may be created if the underlying OS fails to start the specified command and reports it immediately to Robot.
Returns:
command exit code as is specified in the Exec specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.
Since:
3.4

exec

public int exec(java.lang.String command)
         throws java.io.IOException
Convenience method employing the exec(java.lang.String, java.io.OutputStream, int, java.lang.String) method to execute a command without any further options.

Parameters:
command - a command to be executed. On Unix/Linux systems the commands have a few limitations. No redirections and pipes are allowed. See Java documentation on Runtime.exec() for more information.
Returns:
command exit code as is specified in the Exec specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

execBrowser

public int execBrowser(java.lang.String url)

A convenience method to open a web browser on the local operating system. The method makes several attempts to locate and most often used browsers and starts the first one found. The code is optimized to open the default system browser on Windows, Mac OS and Ubuntu. On other systems the method tries to run typical start comands of the most common web browsers according to a hardcoded list and finishes when one of the commands reports success or the list is exhausted.

Note that the method does not use any facilities provided by the Exec command and its behavior can not be modified by any settings applicable to Exec.

Parameters:
url - a document URL to open.
Returns:
0 (zero) on success. Any other value indicates that the method failed to open the browser.

report

public int report(java.io.File out,
                  java.lang.String provider,
                  java.lang.String description,
                  java.lang.String scope)
           throws java.io.IOException

Start the specified report provider to generate a report on test script execution. The method provides access to functionality of the Report scripting language command.

Report providers are independent threads which typically register with the script manager to receive script execution events. Their role is usually to create and maintain a report with the outputs, such as remote desktop screenshots, image comparison results, warnings and execution logs. The report format is completely up to the particular provider implementation. As the report provider interface ReportProvider is exposed through the plugin framework, anyone may write a custom provider and plug it into the tool.

Note that report scope is obsolete and will be removed in the future. It is provided here only for backward compatibility with test scripts prior to v2.0.

Parameters:
out - a file to save the report to.
provider - a report provider code. It must be a valid code returned by the Plugin.getCode() method of one of the installed report provider plugins or null to use the default report provider (configurable through preferences). T-Plan Robot Enterprise provides by default just one simple HTML report provider with the "default" code.
description - report description.
scope - report scope as is defined in the Report command specification.
Returns:
command exit code as is specified in the Report specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

report

public int report(java.io.File out,
                  java.lang.String provider,
                  java.lang.String description)
           throws java.io.IOException

Start the specified report provider to generate a report on test script execution. The method provides access to functionality of the Report scripting language command.

Report providers are independent threads which typically register with the script manager to receive script execution events. Their role is usually to create and maintain a report with the outputs, such as remote desktop screenshots, image comparison results, warnings and execution logs. The report format is completely up to the particular provider implementation. As the report provider interface ReportProvider is exposed through the plugin framework, anyone may write a custom provider and plug it into the tool.

Parameters:
out - a file to save the report to.
provider - a report provider code. It must be a valid code returned by the Plugin.getCode() method of one of the installed report provider plugins or null to use the default report provider (configurable through preferences). T-Plan Robot Enterprise provides by default just one simple HTML report provider with the "default" code.
description - report description.
Returns:
command exit code as is specified in the Report specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

report

public int report(java.io.File out,
                  java.lang.String description)
           throws java.io.IOException

Start the default report provider to generate a report on test script execution. The method provides access to functionality of the Report scripting language command.

Report providers are independent threads which typically register with the script manager to receive script execution events. Their role is usually to create and maintain a report with the outputs, such as remote desktop screenshots, image comparison results, warnings and execution logs. The report format is completely up to the particular provider implementation. As the report provider interface ReportProvider is exposed through the plugin framework, anyone may write a custom provider and plug it into the tool.

One of the installed report providers is always set as the default one. Unless user changes the default provider in preferences, this method starts the only built-in HTML report provider with the "default" code.

Parameters:
out - a file to save the report to.
description - report description.
Returns:
command exit code as is specified in the Report specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

report

public int report(java.io.File out)
           throws java.io.IOException

Start the default report provider to generate a report on test script execution. The method provides access to functionality of the Report scripting language command.

Report providers are independent threads which typically register with the script manager to receive script execution events. Their role is usually to create and maintain a report with the outputs, such as remote desktop screenshots, image comparison results, warnings and execution logs. The report format is completely up to the particular provider implementation. As the report provider interface ReportProvider is exposed through the plugin framework, anyone may write a custom provider and plug it into the tool.

One of the installed report providers is always set as the default one. Unless user changes the default provider in preferences, this method starts the only built-in HTML report provider with the "default" code.

Parameters:
out - a file to save the report to.
Returns:
command exit code as is specified in the Report specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

compareTo

public int compareTo(java.awt.Image[] templates,
                     ImageComparisonModule module,
                     float passRate,
                     java.awt.Rectangle cmpArea,
                     java.lang.Boolean removeBg,
                     java.awt.Color bgColor,
                     java.lang.Integer minAlpha,
                     java.lang.Integer rgbTolerance)
              throws java.io.IOException

Compare the current remote desktop image to one or more template images using the specified image comparison module instance, numeric pass rate and an optional comparison rectangle. The method provides access to functionality of the Compareto scripting language command with the full set of supported parameters and template images in form of java.awt.Image array.

Result of image comparison is typically indicated by the return value. where 0 usually means success, 1 (one) indicates negative result and higher values indicate an error (for example, image file not found etc.). See the Compareto command specification for the list of error codes.

Image comparison modules (methods) may save additional results to the context. Refer to the CompareTo command specification for details. For example, the "search" module stores coordinates of the match areas both to the variable table as well to a list stored in the context. To retrieve them use either of the following ways:

   // 1. Getting x, y from variables
   Integer x = (Integer)getContext().getVariable("_SEARCH_X");
   Integer y = (Integer)getContext().getVariable("_SEARCH_Y");

   // 2. Getting x, y from context's coordinate list
   Point p = getContext().getSearchHits().get(0);
   x = p.x;
   y = p.y;
 

The context was enhanced in v2.1 to provide comfortable access to image search results and template parameters. See the ScriptingContext.getSearchHits() method documentation for an overview.

Parameters:
templates - list of template images (Image instances).
module - image comparison method (module). It may be created through its code (either "default", "search" or third party image comparison plugin code) through the ImageComparisonModuleFactory.getInstance().getModule(code) method.
passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching). To use the default pass rate defined for the particular image comparison method set the value to a negative number.
cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.
removeBg -

set on/off filtering of background color. It is a new 2.1 feature allowing to search for objects on varying background. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). The background filter is applied only to completely opaque template images which do not contain any translucent or transparent pixels introduced through third party image editors. When an existing translucency is detected the filter is switched off silently and only the eventual minAlpha parameter is applied.

The default value is null (equivalent to "false") meaning that background filtering is off. See the Compareto documentation for details.

bgColor - optional color for the background filter. The parameter is ignored when background filtering is off. If the color is not specified (is null), the background filter will use color of the very first image pixel at [0,0] (upper left image corner).
minAlpha - translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing translucent pixels. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). Alpha is a pixel color component between 0 (transparent) and 255 (opaque) which defines the level of pixel translucency. The default minalpha value of null or -1 (internally equal to 255) instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Other values between 0 and 254 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit. Comparison of such pixels is based on color similarity with a fixed threshold.
rgbTolerance - RGB tolerance value. This parameter may be populated only for "search" image comparison algorithm. It is a number between 0 and 100 and it specifies tolerance to color changes on the level of individual pixel R, G, B components. A value of 20 for example makes the search robust against color changes where any of the R, G, B components varies by 20 or less from the template image pixels. It is recommended to use higher values of this parameter or even the limit one of 100 for testing of environments with varying images (for example in Flash or Flex ones). To get best results it is also recommended avoid mixing of the RGB tolerance parameter with other tolerance mechanisms such as pass rate (should be set to 100%) and background filtering (should be off).

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

Returns:
command exit code as is specified in the Compareto specification.
Throws:
java.io.IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(java.awt.Image template,
                     java.lang.Float passRate,
                     java.awt.Rectangle cmpArea,
                     java.awt.Color color,
                     java.awt.Color[] bridgeColors,
                     java.lang.Integer rgbTolerance,
                     java.lang.Integer rotations,
                     java.lang.Boolean draw,
                     java.lang.Boolean clear)
              throws java.io.IOException

Analyze the current remote desktop image using the Object Search Method. The method provides access to functionality of the Compareto scripting language command fixed to the "object" comparison module with an optional template image in form of java.awt.Image.

The Object Search module searches the desktop image or its rectangular part for objects of a particular color or colors within the tolerated RGB variance. It also allows to filter the object list by an optional template image with detection of eventual object rotation. The method was designed to handle simple image analysis tasks such as "find all black triangles in any level of rotation on the screen".

As the method always locates the largest possible object and it doesn't search recursively for any other ones it may contain, this approach is not suitable for classic GUI components which are often framed, overlayed and merged together. The method however performs very well in testing of schemes, maps and images with low color scenes generated for example by Geographic Information System (GIS) applications or systems producing simple image data. The method can be also employed to check whether an object of a certain color or color range is present on the screen, for example to answer a question like "is there any red message in this particular area?".

The algorithm first scans the image for the first pixel which meets the input color criteria. Than it follows the outer shape of each such an object until the shape gets closed. The objects are internally stored as a list of java.awt.Shape instances in the context and may be retrieved through the through the ScriptingContext.getObjectSearchShapes() convenience method. Besides the raw shape data the method also stores bounding rectangle of each object into the context in form of four variables _OBJECT_X_[n], _OBJECT_Y_[n], _OBJECT_W_[n] and _OBJECT_H_[n] which represent the top left corner [x,y] coordinates, width and height. The [n] expression is the object ordinary number starting from 1. The number of objects available is stored under the _OBJECT_COUNT variable. These variables are the only data exposed to the standard scripting language.

Parameters:
template - an optional template image to filter the list of objects by (an Image instance).It must contain just one shape of the specified color and/or tolerance in any level of rotation. When it is provided, the list of objects will be filtered to leave just shapes which are similar to the template image shape up to the ratio specified by the 'passrate' parameter. If the 'rotations' parameter is also specified and is greater than 1, the object list will be matched against the list of template shapes rotated the specified number of times.

If the template image is not specified, the algorithm locates all objects matching the color parameters regardless of their size or shape.
passRate - pass rate as percentage between 0 and 100. The pass rate makes sense only when the template is not null and specifies the percentage of acceptable pixel variance from the template image.
cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.
color - defines the object color.
bridgeColors - is optional list of additional admissible object colors. This allows to search for continuous objects which are expected to have other objects of known colors painted over them. Colors in this list are always compared using the exact RGB match and they do not work with the rgbTolerance parameter.
rgbTolerance - RGB tolerance value. It must be an integer number between 0 and 256. It indicates how much the Red, Green and Blue components of a pixel may differ at a maximum to consider the color be equivalent to the object color specified by the 'color' parameter. This value allows to deal with blurred images where the shapes are not formed by a solid color but rather a range of similar colors. Be however aware that the higher the tolerance value, the higher the probability of false shape detections is. In most scenarios the value should be in the [0, 100] range depending on the blurring level. If the parameter is not specified, it defaults to zero and the algorithm looks for solid color objects only.

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

rotations - makes only sense when a template image is provided. It defines rotation granularity. It basically says how many times to rotate the object extracted from the template for filtering purposes. For example, the value of 36 will rotate the shape in 10 degree steps. Obviously, a high number of rotations increases accuracy of recognition of rotated objects but decreases performance. Low rotation values may be compensated through lowering the 'passrate' parameter. This approach is somewhat better in terms of performance but raises the risk of wrong detection of objects similar enough to the template one.
clear - optional boolean flag dealing with result highlighting in the GUI. The clear parameter allows to clear up all drawings created by the previously called object searches. The drawings are also automatically reset when the script finishes.
draw - optional boolean flag dealing with result highlighting in the GUI. When the draw parameter is 'true', the algorithm draws the object rectangles over the desktop image in the desktop viewer GUI component.
Returns:
The method returns 0 when there's at least one object meeting the criteria or 1 otherwise.
Throws:
java.io.IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(java.io.File template,
                     java.lang.Float passRate,
                     java.awt.Rectangle cmpArea,
                     java.awt.Color color,
                     java.awt.Color[] bridgeColors,
                     java.lang.Integer rgbTolerance,
                     java.lang.Integer rotations,
                     java.lang.Boolean draw,
                     java.lang.Boolean clear)
              throws java.io.IOException

Analyze the current remote desktop image using the Object Search Method. The method provides access to functionality of the Compareto scripting language command fixed to the "object" comparison module with an optional template image in form of java.io.File.

The Object Search module searches the desktop image or its rectangular part for objects of a particular color or colors within the tolerated RGB variance. It also allows to filter the object list by an optional template image with detection of eventual object rotation. The method was designed to handle simple image analysis tasks such as "find all black triangles in any level of rotation on the screen".

As the method always locates the largest possible object and it doesn't search recursively for any other ones it may contain, this approach is not suitable for classic GUI components which are often framed, overlayed and merged together. The method however performs very well in testing of schemes, maps and images with low color scenes generated for example by Geographic Information System (GIS) applications or systems producing simple image data. The method can be also employed to check whether an object of a certain color or color range is present on the screen, for example to answer a question like "is there any red message in this particular area?".

The algorithm first scans the image for the first pixel which meets the input color criteria. Than it follows the outer shape of each such an object until the shape gets closed. The objects are internally stored as a list of java.awt.Shape instances in the context and may be retrieved through the through the ScriptingContext.getObjectSearchShapes() convenience method. Besides the raw shape data the method also stores bounding rectangle of each object into the context in form of four variables _OBJECT_X_[n], _OBJECT_Y_[n], _OBJECT_W_[n] and _OBJECT_H_[n] which represent the top left corner [x,y] coordinates, width and height. The [n] expression is the object ordinary number starting from 1. The number of objects available is stored under the _OBJECT_COUNT variable. These variables are the only data exposed to the standard scripting language.

Parameters:
template - an optional template image to filter the list of objects by (an Image instance).It must contain just one shape of the specified color and/or tolerance in any level of rotation. When it is provided, the list of objects will be filtered to leave just shapes which are similar to the template image shape up to the ratio specified by the 'passrate' parameter. If the 'rotations' parameter is also specified and is greater than 1, the object list will be matched against the list of template shapes rotated the specified number of times.

If the template image is not specified, the algorithm locates all objects matching the color parameters regardless of their size or shape.
passRate - pass rate as percentage between 0 and 100. The pass rate makes sense only when the template is not null and specifies the percentage of acceptable pixel variance from the template image.
cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.
color - defines the object color.
bridgeColors - is optional list of additional admissible object colors. This allows to search for continuous objects which are expected to have other objects of known colors painted over them. Colors in this list are always compared using the exact RGB match and they do not work with the rgbTolerance parameter.
rgbTolerance - RGB tolerance value. It must be an integer number between 0 and 256. It indicates how much the Red, Green and Blue components of a pixel may differ at a maximum to consider the color be equivalent to the object color specified by the 'color' parameter. This value allows to deal with blurred images where the shapes are not formed by a solid color but rather a range of similar colors. Be however aware that the higher the tolerance value, the higher the probability of false shape detections is. In most scenarios the value should be in the [0, 100] range depending on the blurring level. If the parameter is not specified, it defaults to zero and the algorithm looks for solid color objects only.

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

rotations - makes only sense when a template image is provided. It defines rotation granularity. It basically says how many times to rotate the object extracted from the template for filtering purposes. For example, the value of 36 will rotate the shape in 10 degree steps. Obviously, a high number of rotations increases accuracy of recognition of rotated objects but decreases performance. Low rotation values may be compensated through lowering the 'passrate' parameter. This approach is somewhat better in terms of performance but raises the risk of wrong detection of objects similar enough to the template one.
clear - optional boolean flag dealing with result highlighting in the GUI. The clear parameter allows to clear up all drawings created by the previously called object searches. The drawings are also automatically reset when the script finishes.
draw - optional boolean flag dealing with result highlighting in the GUI. When the draw parameter is 'true', the algorithm draws the object rectangles over the desktop image in the desktop viewer GUI component.
Returns:
The method returns 0 when there's at least one object meeting the criteria or 1 otherwise.
Throws:
java.io.IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(java.awt.Image[] templates,
                     ImageComparisonModule module,
                     float passRate,
                     java.awt.Rectangle cmpArea,
                     java.lang.Boolean removeBg,
                     java.awt.Color bgColor,
                     java.lang.Integer minAlpha)
              throws java.io.IOException

Compare the current remote desktop image to one or more template images using the specified image comparison module instance, numeric pass rate and an optional comparison rectangle. The method provides access to functionality of the Compareto scripting language command with the full set of supported parameters and template images in form of java.awt.Image array.

Result of image comparison is typically indicated by the return value. where 0 usually means success, 1 (one) indicates negative result and higher values indicate an error (for example, image file not found etc.). See the Compareto command specification for the list of error codes.

Image comparison modules (methods) may save additional results to the context. Refer to the CompareTo command specification for details. For example, the "search" module stores coordinates of the match areas both to the variable table as well to a list stored in the context. To retrieve them use either of the following ways:

   // 1. Getting x, y from variables
   Integer x = (Integer)getContext().getVariable("_SEARCH_X");
   Integer y = (Integer)getContext().getVariable("_SEARCH_Y");

   // 2. Getting x, y from context's coordinate list
   Point p = getContext().getSearchHits().get(0);
   x = p.x;
   y = p.y;
 

The context was enhanced in v2.1 to provide comfortable access to image search results and template parameters. See the ScriptingContext.getSearchHits() method documentation for an overview.

Parameters:
templates - list of template images (Image instances).
module - image comparison method (module). It may be created through its code (either "default", "search" or third party image comparison plugin code) through the ImageComparisonModuleFactory.getInstance().getModule(code) method.
passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching). To use the default pass rate defined for the particular image comparison method set the value to a negative number.
cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.
removeBg -

set on/off filtering of background color. It is a new 2.1 feature allowing to search for objects on varying background. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). The background filter is applied only to completely opaque template images which do not contain any translucent or transparent pixels introduced through third party image editors. When an existing translucency is detected the filter is switched off silently and only the eventual minAlpha parameter is applied.

The default value is null (equivalent to "false") meaning that background filtering is off. See the Compareto documentation for details.

bgColor - optional color for the background filter. The parameter is ignored when background filtering is off. If the color is not specified (is null), the background filter will use color of the very first image pixel at [0,0] (upper left image corner).
minAlpha - translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing translucent pixels. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). Alpha is a pixel color component between 0 (transparent) and 255 (opaque) which defines the level of pixel translucency. The default minalpha value of null or -1 (internally equal to 255) instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Other values between 0 and 254 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit. Comparison of such pixels is based on color similarity with a fixed threshold.
Returns:
command exit code as is specified in the Compareto specification.
Throws:
java.io.IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(java.awt.Image[] templates,
                     ImageComparisonModule module,
                     float passRate,
                     java.awt.Rectangle cmpArea,
                     java.lang.Integer rgbTolerance)
              throws java.io.IOException

Compare the current remote desktop image to one or more template images using the specified image comparison module instance, numeric pass rate and an optional comparison rectangle. The method provides access to functionality of the Compareto scripting language command with the full set of supported parameters except the imagse search specific ones and template images in form of java.awt.Image array.

Result of image comparison is typically indicated by the return value. where 0 usually means success, 1 (one) indicates negative result and higher values indicate an error (for example, image file not found etc.). See the Compareto command specification for the list of error codes.

Image comparison modules (methods) may save additional results to the context. Refer to the CompareTo command specification for details. For example, the "search" module stores coordinates of the match areas both to the variable table as well to a list stored in the context. To retrieve them use either of the following ways:

   // 1. Getting x, y from variables
   Integer x = (Integer)getContext().getVariable("_SEARCH_X");
   Integer y = (Integer)getContext().getVariable("_SEARCH_Y");

   // 2. Getting x, y from context's coordinate list
   Point p = getContext().getSearchHits().get(0);
   x = p.x;
   y = p.y;
 

The context was enhanced in v2.1 to provide comfortable access to image search results and template parameters. See the ScriptingContext.getSearchHits() method documentation for an overview.

Parameters:
templates - list of template images (Image instances).
module - image comparison method (module). It may be created through its code (either "default", "search" or third party image comparison plugin code) through the ImageComparisonModuleFactory.getInstance().getModule(code) method.
passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching). To use the default pass rate defined for the particular image comparison method set the value to a negative number.
cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.
rgbTolerance - RGB tolerance value. This parameter may be populated only for "search" image comparison algorithm. It is a number between 0 and 100 and it specifies tolerance to color changes on the level of individual pixel R, G, B components. A value of 20 for example makes the search robust against color changes where any of the R, G, B components varies by 20 or less from the template image pixels. It is recommended to use higher values of this parameter or even the limit one of 100 for testing of environments with varying images (for example in Flash or Flex ones). To get best results it is also recommended avoid mixing of the RGB tolerance parameter with other tolerance mechanisms such as pass rate (should be set to 100%) and background filtering (should be off).

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

Returns:
command exit code as is specified in the Compareto specification.
Throws:
java.io.IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(java.awt.Image[] templates,
                     ImageComparisonModule module,
                     float passRate,
                     java.awt.Rectangle cmpArea)
              throws java.io.IOException

Compare the current remote desktop image to one or more template images using the specified image comparison module instance, numeric pass rate and an optional comparison rectangle. The method provides access to functionality of the Compareto scripting language command with the full set of supported parameters except the imagse search specific ones and template images in form of java.awt.Image array.

Result of image comparison is typically indicated by the return value. where 0 usually means success, 1 (one) indicates negative result and higher values indicate an error (for example, image file not found etc.). See the Compareto command specification for the list of error codes.

Image comparison modules (methods) may save additional results to the context. Refer to the CompareTo command specification for details. For example, the "search" module stores coordinates of the match areas both to the variable table as well to a list stored in the context. To retrieve them use either of the following ways:

   // 1. Getting x, y from variables
   Integer x = (Integer)getContext().getVariable("_SEARCH_X");
   Integer y = (Integer)getContext().getVariable("_SEARCH_Y");

   // 2. Getting x, y from context's coordinate list
   Point p = getContext().getSearchHits().get(0);
   x = p.x;
   y = p.y;
 

The context was enhanced in v2.1 to provide comfortable access to image search results and template parameters. See the ScriptingContext.getSearchHits() method documentation for an overview.

Parameters:
templates - list of template images (Image instances).
module - image comparison method (module). It may be created through its code (either "default", "search" or third party image comparison plugin code) through the ImageComparisonModuleFactory.getInstance().getModule(code) method.
passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching). To use the default pass rate defined for the particular image comparison method set the value to a negative number.
cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.
Returns:
command exit code as is specified in the Compareto specification.
Throws:
java.io.IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(java.io.File[] templates,
                     float passRate,
                     java.awt.Rectangle cmpArea,
                     boolean removeBg,
                     java.lang.String bgColor,
                     java.lang.Integer minAlpha,
                     java.lang.Integer rgbTolerance)
              throws java.io.IOException

Search the current remote desktop image for one or more template images using the "search" image comparison module (method), numeric pass rate and an optional comparison rectangle. The method provides access to functionality of the Compareto scripting language command with template images specified in form of java.io.File array and with the set of arguments enhanced with optional image search specific parameters dealing with background filtering and RGB tolerance.

Result of image comparison is typically indicated by the return value. where 0 usually means success, 1 (one) indicates negative result and higher values indicate an error (for example, image file not found etc.). See the Compareto command specification for the list of error codes.

Image comparison modules (methods) may save additional results to the context. Refer to the CompareTo command specification for details. For example, the "search" module stores coordinates of the match areas both to the variable table as well to a list stored in the context. To retrieve them use either of the following ways:

   // 1. Getting x, y from variables
   Integer x = (Integer)getContext().getVariable("_SEARCH_X");
   Integer y = (Integer)getContext().getVariable("_SEARCH_Y");

   // 2. Getting x, y from context's coordinate list
   Point p = getContext().getSearchHits().get(0);
   x = p.x;
   y = p.y;
 

The context was enhanced in v2.1 to provide comfortable access to image search results and template parameters. See the ScriptingContext.getSearchHits() method documentation for an overview.

Parameters:
templates - list of template images (Image instances).
passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching).
cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.
removeBg -

set on/off filtering of background color. It is a new 2.1 feature allowing to search for objects on varying background. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). The background filter is applied only to completely opaque template images which do not contain any translucent or transparent pixels introduced through third party image editors. When an existing translucency is detected the filter is switched off silently and only the eventual minAlpha parameter is applied.

The default value is null (equivalent to "false") meaning that background filtering is off. See the Compareto documentation for details.

bgColor - optional color for the background filter. The parameter is ignored when background filtering is off. If the color is not specified (is null), the background filter will use color of the very first image pixel at [0,0] (upper left image corner).
minAlpha - translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing translucent pixels. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). Alpha is a pixel color component between 0 (transparent) and 255 (opaque) which defines the level of pixel translucency. The default minalpha value of null or -1 (internally equal to 255) instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Other values between 0 and 254 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit. Comparison of such pixels is based on color similarity with a fixed threshold.
rgbTolerance - RGB tolerance value. It is a number between 0 and 100 and it specifies tolerance to color changes on the level of individual pixel R, G, B components. A value of 20 for example makes the search robust against color changes where any of the R, G, B components varies by 20 or less from the template image pixels. It is recommended to use higher values of this parameter or even the limit one of 100 for testing of environments with varying images (for example in Flash or Flex ones). To get best results it is also recommended avoid mixing of the RGB tolerance parameter with other tolerance mechanisms such as pass rate (should be set to 100%) and background filtering (should be off).

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

Returns:
command exit code as is specified in the Compareto specification.
Throws:
java.io.IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(java.io.File[] templates,
                     float passRate,
                     java.awt.Rectangle cmpArea,
                     boolean removeBg,
                     java.lang.String bgColor,
                     java.lang.Integer minAlpha)
              throws java.io.IOException

Search the current remote desktop image for one or more template images using the "search" image comparison module (method), numeric pass rate and an optional comparison rectangle. The method provides access to functionality of the Compareto scripting language command with template images specified in form of java.io.File array and with the set of arguments enhanced with image search specific parameters dealing with background filtering.

Result of image comparison is typically indicated by the return value. where 0 usually means success, 1 (one) indicates negative result and higher values indicate an error (for example, image file not found etc.). See the Compareto command specification for the list of error codes.

Image comparison modules (methods) may save additional results to the context. Refer to the CompareTo command specification for details. For example, the "search" module stores coordinates of the match areas both to the variable table as well to a list stored in the context. To retrieve them use either of the following ways:

   // 1. Getting x, y from variables
   Integer x = (Integer)getContext().getVariable("_SEARCH_X");
   Integer y = (Integer)getContext().getVariable("_SEARCH_Y");

   // 2. Getting x, y from context's coordinate list
   Point p = getContext().getSearchHits().get(0);
   x = p.x;
   y = p.y;
 

The context was enhanced in v2.1 to provide comfortable access to image search results and template parameters. See the ScriptingContext.getSearchHits() method documentation for an overview.

Parameters:
templates - list of template images (Image instances).
passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching).
cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.
removeBg -

set on/off filtering of background color. It is a new 2.1 feature allowing to search for objects on varying background. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). The background filter is applied only to completely opaque template images which do not contain any translucent or transparent pixels introduced through third party image editors. When an existing translucency is detected the filter is switched off silently and only the eventual minAlpha parameter is applied.

The default value is null (equivalent to "false") meaning that background filtering is off. See the Compareto documentation for details.

bgColor - optional color for the background filter. The parameter is ignored when background filtering is off. If the color is not specified (is null), the background filter will use color of the very first image pixel at [0,0] (upper left image corner).
minAlpha - translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing translucent pixels. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). Alpha is a pixel color component between 0 (transparent) and 255 (opaque) which defines the level of pixel translucency. The default minalpha value of null or -1 (internally equal to 255) instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Other values between 0 and 254 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit. Comparison of such pixels is based on color similarity with a fixed threshold.
Returns:
command exit code as is specified in the Compareto specification.
Throws:
java.io.IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(java.io.File[] templates,
                     float passRate,
                     java.awt.Rectangle cmpArea,
                     java.lang.String sort)
              throws java.io.IOException

Search the current remote desktop image for one or more template images using the "search2" image comparison module (method), numeric pass rate and an optional comparison rectangle. The method provides access to functionality of the Compareto scripting language command with template images specified in form of java.io.File array.

Result of image comparison is typically indicated by the return value. where 0 usually means success, 1 (one) indicates negative result and higher values indicate an error (for example, image file not found etc.). See the Compareto command specification for the list of error codes.

The "search2" method stores coordinates of the match areas both to the variable table as well to a list stored in the context. To retrieve them use either of the following ways:

   // 1. Getting x, y from variables
   Integer x = (Integer)getContext().getVariable("_SEARCH_X");
   Integer y = (Integer)getContext().getVariable("_SEARCH_Y");

   // 2. Getting x, y from context's coordinate list
   Point p = getContext().getSearchHits().get(0);
   x = p.x;
   y = p.y;
 

The context was enhanced in v2.1 to provide comfortable access to image search results and template parameters. See the ScriptingContext.getSearchHits() method documentation for an overview.

Parameters:
templates - list of template images (File instances).
passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching).
cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.
sort - the sort order for the resulting match locations (Point/Rectangle). Supported modes:
  • "best" - Put the best matching location first (default mode).
  • "none" - Don't sort and leave the results in their natural "reading" order (left to right, top to bottom). This mode will produce the same order as the legacy "search" method.
  • "top" - Sort locations from the top to the bottom (topmost first).
  • "bottom" - Sort locations from the bottom to the top (bottommost first).
  • "left" - Sort locations from the left to the right (leftmost first).
  • "right" - Sort locations from the right to the left (rightmost first).
When the argument is null the sort mode defaults to the "best" one.
Returns:
command exit code as is specified in the Compareto specification.
Throws:
java.io.IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(java.io.File[] templates,
                     float passRate,
                     java.awt.Rectangle cmpArea,
                     java.lang.String sort,
                     float[] scale)
              throws java.io.IOException

Search the current remote desktop image for one or more template images using the "search2" image comparison module (method), numeric pass rate and an optional comparison rectangle. The method provides access to functionality of the Compareto scripting language command with template images specified in form of java.io.File array.

Result of image comparison is typically indicated by the return value. where 0 usually means success, 1 (one) indicates negative result and higher values indicate an error (for example, image file not found etc.). See the Compareto command specification for the list of error codes.

The "search2" method stores coordinates of the match areas both to the variable table as well to a list stored in the context. To retrieve them use either of the following ways:

   // 1. Getting x, y from variables
   Integer x = (Integer)getContext().getVariable("_SEARCH_X");
   Integer y = (Integer)getContext().getVariable("_SEARCH_Y");

   // 2. Getting x, y from context's coordinate list
   Point p = getContext().getSearchHits().get(0);
   x = p.x;
   y = p.y;
 

The context was enhanced in v2.1 to provide comfortable access to image search results and template parameters. See the ScriptingContext.getSearchHits() method documentation for an overview.

Parameters:
templates - list of template images (File instances).
passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching).
cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.
sort - the sort order for the resulting match locations (Point/Rectangle). Supported modes:
  • "best" - Put the best matching location first (default mode).
  • "none" - Don't sort and leave the results in their natural "reading" order (left to right, top to bottom). This mode will produce the same order as the legacy "search" method.
  • "top" - Sort locations from the top to the bottom (topmost first).
  • "bottom" - Sort locations from the bottom to the top (bottommost first).
  • "left" - Sort locations from the left to the right (leftmost first).
  • "right" - Sort locations from the right to the left (rightmost first).
When the argument is null the sort mode defaults to the "best" one.
scale - allows to search for scaled instances of the input image (supported since 4.0). To set off scaling use the value of 0 (ignore) or 1 (use original size). When the value is greater than zero it is being handled as a scale ratio. For example, the value of 2.0 will search for the component whose width and height are magnified twice.

There are two negative constants which can be specified to employ dynamic scaling. They will scale the input image(s) with regard to the difference between the current desktop resolution and size of the desktop the template (component) image was created from. As Robot 3.x and older did not save the desktop resolution to the template meta data, the image must be created or updated with Robot 4.0 to enable this operation. The supported scale modes are:

  • -1 ("stretch mode") will scale the input image following the desktop width and height changes independently. The resulting image may or may not have the same width and height proportions (the width/height ratio).
  • -2 ("proportional scale mode") will pick up the smaller relative change of the desktop width and height and use it for both width and height scaling. The resulting image will have the the same proportions (the width/height ratio).
Returns:
command exit code as is specified in the Compareto specification.
Throws:
java.io.IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).
Since:
4.0

compareTo

public int compareTo(java.awt.Rectangle cmpArea,
                     java.lang.String language,
                     java.lang.String text,
                     java.lang.String pattern)
              throws java.io.IOException

Perform Optical Character Recognition (OCR) using the Tesseract engine. The method provides access to functionality of the Compareto scripting language command with the comparison method name fixed to "tocr" and support of its specific parameters. See also the TesseractOCR class documentation for details on how to install and configure Tesseract.

Result of OCR is indicated by the return value where 0 usually means success, and 1 (one) indicates negative result. This method by default returns the value of 0 if the OCR is performed successfully and the value of 1 if the command fails, for example when the engine is not installed or misconfigured or the language code is not supported. If either 'text' or 'pattern' parameter is specified, the method returns 0 to indicate success only if the OCR performs successfully and the resulting text contains the string specified by 'text' or matches the 'pattern' regular expression.

The resulting text from OCR is stored in form of individual text lines to _TOCR_LINE[line_number] variables into the context. The number of resulting text lines is available from the _TOCR_LINE_COUNT variable. The whole text including the new line characters is also available as a String through the getContext().get(TesseractOCR.CONTEXT_TOCR_TEXT) method.

If the OCR throws an error caused by misconfiguration or an I/O error, the method returns the value of 1. Text of the errors is made available through the _TOCR_ERROR variable. Testing of existence of this variable is the only way to detect core OCR errors in test scripts.

Parameters:
cmpArea - comparison area (sub rectangle) in the desktop image to apply the comparison to. If it is null the full image will be processed.
language - target language (optional). It must be the 3-char lower case code of a properly installed Tesseract language data file set. For example, English code is "eng", German is "deu", Spanish is "spa" etc. This parameter will be passed as value of the "-l" argument to the engine. See the Tesseract's download page for the list of supported language files.
text - a string to look for in the recognized text (optional). If the parameter is specified (not null), the 'pattern' parameter must be null. If the string is found in the text resulting from OCR, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.
pattern - a Pattern compatible regular expression to match against the recognized text (optional). If the parameter is specified (not null), the 'text' parameter must be null. If the text resulting from OCR matches the regular expression, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.
Returns:
command exit code as is specified in the Compareto specification.
Throws:
java.io.IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(java.awt.Rectangle cmpArea,
                     java.lang.String language)
              throws java.io.IOException

Perform Optical Character Recognition (OCR) using the Tesseract engine. The method provides access to functionality of the Compareto scripting language command with the comparison method name fixed to "tocr" and support of its specific parameters. See also the TesseractOCR class documentation for details on how to install and configure Tesseract.

Result of OCR is indicated by the return value where 0 usually means success, and 1 (one) indicates negative result. This method by default returns the value of 0 if the OCR is performed successfully and the value of 1 if the command fails, for example when the engine is not installed or misconfigured or the language code is not supported. If either 'text' or 'pattern' parameter is specified, the method returns 0 to indicate success only if the OCR performs successfully and the resulting text contains the string specified by 'text' or matches the 'pattern' regular expression.

The resulting text from OCR is stored in form of individual text lines to _TOCR_LINE[line_number] variables into the context. The number of resulting text lines is available from the _TOCR_LINE_COUNT variable. The whole text including the new line characters is also available as a String through the getContext().get(TesseractOCR.CONTEXT_TOCR_TEXT) method.

If the OCR throws an error caused by misconfiguration or an I/O error, the method returns the value of 1. Text of the errors is made available through the _TOCR_ERROR variable. Testing of existence of this variable is the only way to detect core OCR errors in test scripts.

Parameters:
cmpArea - comparison area (sub rectangle) in the desktop image to apply the comparison to. If it is null the full image will be processed.
language - target language (optional). It must be the 3-char lower case code of a properly installed Tesseract language data file set. For example, English code is "eng", German is "deu", Spanish is "spa" etc. This parameter will be passed as value of the "-l" argument to the engine. See the Tesseract's download page for the list of supported language files.
Returns:
command exit code as is specified in the Compareto specification.
Throws:
java.io.IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(java.awt.Rectangle cmpArea,
                     java.lang.String language,
                     float scale,
                     java.lang.String text,
                     int distance,
                     java.lang.String pattern)
              throws java.io.IOException

Perform Optical Character Recognition (OCR) using the Tesseract engine. The method provides access to functionality of the Compareto scripting language command with the comparison method name fixed to "tocr" and support of its specific parameters. See also the TesseractOCR class documentation for details on how to install and configure Tesseract.

Result of OCR is indicated by the return value where 0 usually means success, and 1 (one) indicates negative result. This method by default returns the value of 0 if the OCR is performed successfully and the value of 1 if the command fails, for example when the engine is not installed or misconfigured or the language code is not supported. If either 'text' or 'pattern' parameter is specified, the method returns 0 to indicate success only if the OCR performs successfully and the resulting text contains the string specified by 'text' or matches the 'pattern' regular expression.

The resulting text from OCR is stored in form of individual text lines to _TOCR_LINE[line_number] variables into the context. The number of resulting text lines is available from the _TOCR_LINE_COUNT variable. The whole text including the new line characters is also available as a String through the getContext().get(TesseractOCR.CONTEXT_TOCR_TEXT) method.

If the OCR throws an error caused by misconfiguration or an I/O error, the method returns the value of 1. Text of the errors is made available through the _TOCR_ERROR variable. Testing of existence of this variable is the only way to detect core OCR errors in test scripts.

Parameters:
cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the OCR will be performed on the full desktop image.
language - target language (optional). It must be the 3-char lower case code of a properly installed Tesseract language data file set. For example, English code is "eng", German is "deu", Spanish is "spa" etc. This parameter will be passed as value of the "-l" argument to the engine. See the Tesseract's download page for the list of supported language files. If the parameter is null, it will default to the English one ("eng").
scale - magnification factor. The method magnifies (enlarges) the image by the given factor to improve OCR accuracy. If this parameter is set to a value below 0, it defaults to the value configured in the Tesseract OCR Plugin preferences (the factory setting is 2 meaning that the image shall be enlarged to 200% of its original size).
text - a string to look for in the recognized text (optional). If the parameter is specified (not null), the 'pattern' parameter must be null. If the string is found in the text resulting from OCR, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.
distance - fuzzy string matching factor applied to comparison of the recognized text with value of the 'text' parameter. The distance is an integer based on the Levenshtein distance. It is defined as the minimum number of edits needed to transform one string into the other, with the allowable edit operations being insertion, deletion, or substitution of a single character. This metric is exposed as a new parameter called 'distance' which is an integer number specifying how many characters may be omitted or not recognized properly at a maximum to consider the sample text provided in the 'text' parameter equivalent. The default value of this parameter is 0 which will force exact comparison with the specified text.

Unlike the regular expressions the 'distance' parameter always searches the recognized text for any occurrence of a string matching the given text and distance. There's no need to specify that the string is preceded or trailed by another text. For example, the parameters of distance=1 and test=Apple will produce positive comparison result against recognized text of "The apple is red" because the text contains the word "apple" which may be converted to "Apple" in one character substitution.

pattern - a Pattern compatible regular expression to match against the recognized text (optional). If the parameter is specified (not null), the 'text' parameter must be null. If the text resulting from OCR matches the regular expression, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.
Returns:
command exit code as is specified in the Compareto specification.
Throws:
java.io.IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(java.awt.Rectangle cmpArea,
                     java.lang.String language,
                     float scale,
                     java.lang.String text,
                     int distance,
                     java.lang.String pattern,
                     int mode,
                     int filter,
                     int fontSize)
              throws java.io.IOException

Perform Optical Character Recognition (OCR) using the Tesseract engine. The method provides access to functionality of the Compareto scripting language command with the comparison method name fixed to "tocr" and support of its specific parameters. See also the TesseractOCR class documentation for details on how to install and configure Tesseract.

Result of OCR is indicated by the return value where 0 usually means success, and 1 (one) indicates negative result. This method by default returns the value of 0 if the OCR is performed successfully and the value of 1 if the command fails, for example when the engine is not installed or misconfigured or the language code is not supported. If either 'text' or 'pattern' parameter is specified, the method returns 0 to indicate success only if the OCR performs successfully and the resulting text contains the string specified by 'text' or matches the 'pattern' regular expression.

The resulting text from OCR is stored in form of individual text lines to _TOCR_LINE[line_number] variables into the context. The number of resulting text lines is available from the _TOCR_LINE_COUNT variable. The whole text including the new line characters is also available as a String through the getContext().get(TesseractOCR.CONTEXT_TOCR_TEXT) method.

If the OCR throws an error caused by misconfiguration or an I/O error, the method returns the value of 1. Text of the errors is made available through the _TOCR_ERROR variable. Testing of existence of this variable is the only way to detect core OCR errors in test scripts.

Parameters:
cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the OCR will be performed on the full desktop image.
language - target language (optional). It must be the 3-char lower case code of a properly installed Tesseract language data file set. For example, English code is "eng", German is "deu", Spanish is "spa" etc. This parameter will be passed as value of the "-l" argument to the engine. See the Tesseract's download page for the list of supported language files. If the parameter is null, it will default to the English one ("eng").
scale - magnification factor. The method magnifies (enlarges) the image by the given factor to improve OCR accuracy. If this parameter is set to a value below 0, it defaults to the value configured in the Tesseract OCR Plugin preferences (the factory setting is 2 meaning that the image shall be enlarged to 200% of its original size).
text - a string to look for in the recognized text (optional). If the parameter is specified (not null), the 'pattern' parameter must be null. If the string is found in the text resulting from OCR, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.
distance - fuzzy string matching factor applied to comparison of the recognized text with value of the 'text' parameter. The distance is an integer based on the Levenshtein distance. It is defined as the minimum number of edits needed to transform one string into the other, with the allowable edit operations being insertion, deletion, or substitution of a single character. This metric is exposed as a new parameter called 'distance' which is an integer number specifying how many characters may be omitted or not recognized properly at a maximum to consider the sample text provided in the 'text' parameter equivalent. The default value of this parameter is 0 which will force exact comparison with the specified text.

Unlike the regular expressions the 'distance' parameter always searches the recognized text for any occurrence of a string matching the given text and distance. There's no need to specify that the string is preceded or trailed by another text. For example, the parameters of distance=1 and test=Apple will produce positive comparison result against recognized text of "The apple is red" because the text contains the word "apple" which may be converted to "Apple" in one character substitution.

pattern - a Pattern compatible regular expression to match against the recognized text (optional). If the parameter is specified (not null), the 'text' parameter must be null. If the text resulting from OCR matches the regular expression, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.
mode - the OCR mode (since 3.5). It allows to modify the engine behavior in special cases to get better results. This parameter is optional. To leave the mode on default specify any value equal to or less than 1. The supported modes are:
  1. Default Tesseract mode (the value of 1). It is the Tesseract's default mode of automatic page segmentation with no OSD (the "-psm 3" CLI switch). This value is compatible with the Robot releases prior to 3.5.
  2. High accuracy (mode 2). This is a Robot enhancement which splits the text on the screen into lines and reapplies the OCR separately in the line mode (-psm 7). This approach is several times slower but typically delivers more accurate results, especially where the OCR is applied to a smaller screen area such as an application window.
  3. Treat the image as a single word (mode 8). Use this mode when the recognized text is up to 3 characters long. This is Tesseract's native mode driven through the "-psm 8" CLI switch.
filter - optional image filter code (since 3.5). It removes certain artifacts on the screen in order to improve the OCR accuracy. The filter should be applied selectively where the target screen or its part contains text of dark color in rectangular areas with solid color background, such as for example application windows with standard solid gray or white buttons, drop downs and other components. White or bright color text and rich color graphics such as images or photographs are not suitable for filtering. Usage of the filter in such scenes may damage the text and decrease the OCR accuracy.

The supported filter codes are:
  1. 0 - No filter (default).
  2. 1 - Remove artefacts. It will remove typical application components consisting of horizontal and vertical solid color lines (borders).
  3. 2 - Remove artefacts and underlines will remove components and single character underlines typical for application menus.
  4. 3 - Remove artefacts, underlines and dashed lines will remove components, underlines and any dashed line borders which typically mark a selected component or the one that currently owns the focus. The dash line pattern must be populated properly in the 'tocr' method preferences in order to get recognized and removed properly.
The filter is optional. To leave this parameter on default provide any value equal to or less than 0.
fontSize - an approximate font size of the text to be recognized (since 3.5). The default value is 15. It is used only when the image filter is on. It tells the filter not to remove artifacts that are smaller than or equal to the font size. When the value is much smaller than the actual font size the filter may cripple some of the characters. When the value is too large the filter will fail to remove certain artifacts (components) from the screen which may result in lower accuracy.

The font size is optional. To leave this parameter on default provide any value equal to or less than 0.
Returns:
command exit code as is specified in the Compareto specification.
Throws:
java.io.IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(java.io.File[] templates,
                     java.lang.String method,
                     java.lang.String methodParams,
                     float passRate,
                     java.awt.Rectangle cmpArea)
              throws java.io.IOException

Compare the current remote desktop image to one or more template images using the specified image comparison module instance, numeric pass rate and an optional comparison rectangle. The method provides access to functionality of the Compareto scripting language command with template images specified in form of java.io.File array.

Result of image comparison is typically indicated by the return value. where 0 usually means success, 1 (one) indicates negative result and higher values indicate an error (for example, image file not found etc.). See the Compareto command specification for the list of error codes.

Image comparison modules (methods) may save additional results to the context. Refer to the CompareTo command specification for details. For example, the "search" module stores coordinates of the match areas both to the variable table as well to a list stored in the context. To retrieve them use either of the following ways:

   // 1. Getting x, y from variables
   Integer x = (Integer)getContext().getVariable("_SEARCH_X");
   Integer y = (Integer)getContext().getVariable("_SEARCH_Y");

   // 2. Getting x, y from context's coordinate list
   Point p = getContext().getSearchHits().get(0);
   x = p.x;
   y = p.y;
 

The context was enhanced in v2.1 to provide comfortable access to image search results and template parameters. See the ScriptingContext.getSearchHits() method documentation for an overview.

Parameters:
templates - list of template images (Image instances).
method - image comparison method code. It may be either "default" (histogram based comparison), "search" (tolerant image search) or eventually code of a custom image comparison algorithm added to the tool in form of a plug in.
methodParams - use null for both the "default" and "search" methods. This is a legacy parameter intended to let custom plugins to receive specific parameters from a script.
passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching).
cmpArea - comparison area (sub rectangle) in the desktop image to apply the comparison to. If it is null the full image will be processed.
Returns:
command exit code as is specified in the Compareto specification.
Throws:
java.io.IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(java.io.File[] templates,
                     java.lang.String method,
                     float passRate,
                     java.awt.Rectangle cmpArea)
              throws java.io.IOException

Compare the current remote desktop image to one or more template images using the specified image comparison module instance, numeric pass rate and an optional comparison rectangle. The method provides access to functionality of the Compareto scripting language command with template images specified in form of java.io.File array.

Result of image comparison is typically indicated by the return value. where 0 usually means success, 1 (one) indicates negative result and higher values indicate an error (for example, image file not found etc.). See the Compareto command specification for the list of error codes.

Image comparison modules (methods) may save additional results to the context. Refer to the CompareTo command specification for details. For example, the "search" module stores coordinates of the match areas both to the variable table as well to a list stored in the context. To retrieve them use either of the following ways:

   // 1. Getting x, y from variables
   Integer x = (Integer)getContext().getVariable("_SEARCH_X");
   Integer y = (Integer)getContext().getVariable("_SEARCH_Y");

   // 2. Getting x, y from context's coordinate list
   Point p = getContext().getSearchHits().get(0);
   x = p.x;
   y = p.y;
 

The context was enhanced in v2.1 to provide comfortable access to image search results and template parameters. See the ScriptingContext.getSearchHits() method documentation for an overview.

Parameters:
templates - list of template images (Image instances).
method - image comparison method code. It may be either "default" (histogram based comparison), "search" (tolerant image search) or eventually code of a custom image comparison algorithm added to the tool in form of a plug in.
passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching).
cmpArea - comparison area (sub rectangle) in the desktop image to apply the comparison to. If it is null the full image will be processed.
Returns:
command exit code as is specified in the Compareto specification.
Throws:
java.io.IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(java.io.File[] templates,
                     java.lang.String method,
                     float passRate,
                     java.awt.Rectangle cmpArea,
                     java.lang.Integer rgbTolerance)
              throws java.io.IOException

Compare the current remote desktop image to one or more template images using the specified image comparison module instance, numeric pass rate and an optional comparison rectangle. The method provides access to functionality of the Compareto scripting language command with template images specified in form of java.io.File array.

Result of image comparison is typically indicated by the return value. where 0 usually means success, 1 (one) indicates negative result and higher values indicate an error (for example, image file not found etc.). See the Compareto command specification for the list of error codes.

Image comparison modules (methods) may save additional results to the context. Refer to the CompareTo command specification for details. For example, the "search" module stores coordinates of the match areas both to the variable table as well to a list stored in the context. To retrieve them use either of the following ways:

   // 1. Getting x, y from variables
   Integer x = (Integer)getContext().getVariable("_SEARCH_X");
   Integer y = (Integer)getContext().getVariable("_SEARCH_Y");

   // 2. Getting x, y from context's coordinate list
   Point p = getContext().getSearchHits().get(0);
   x = p.x;
   y = p.y;
 

The context was enhanced in v2.1 to provide comfortable access to image search results and template parameters. See the ScriptingContext.getSearchHits() method documentation for an overview.

Parameters:
templates - list of template images (Image instances).
method - image comparison method code. It may be either "default" (histogram based comparison), "search" (tolerant image search) or eventually code of a custom image comparison algorithm added to the tool in form of a plug in.
passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching).
cmpArea - comparison area (sub rectangle) in the desktop image to apply the comparison to. If it is null the full image will be processed.
rgbTolerance - RGB tolerance value. This parameter may be populated only for "search" image comparison algorithm. It is a number between 0 and 100 and it specifies tolerance to color changes on the level of individual pixel R, G, B components. A value of 20 for example makes the search robust against color changes where any of the R, G, B components varies by 20 or less from the template image pixels. It is recommended to use higher values of this parameter or even the limit one of 100 for testing of environments with varying images (for example in Flash or Flex ones). To get best results it is also recommended avoid mixing of the RGB tolerance parameter with other tolerance mechanisms such as pass rate (should be set to 100%) and background filtering (should be off).

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

Returns:
command exit code as is specified in the Compareto specification.
Throws:
java.io.IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(java.io.File[] templates,
                     java.lang.String method,
                     float passRate)
              throws java.io.IOException

Compare the current remote desktop image to one or more template images using the specified image comparison module instance and numeric pass rate. The method provides access to functionality of the Compareto scripting language command with template images specified in form of java.io.File array.

Result of image comparison is typically indicated by the return value. where 0 usually means success, 1 (one) indicates negative result and higher values indicate an error (for example, image file not found etc.). See the Compareto command specification for the list of error codes.

Image comparison modules (methods) may save additional results to the context. Refer to the CompareTo command specification for details. For example, the "search" module stores coordinates of the match areas both to the variable table as well to a list stored in the context. To retrieve them use either of the following ways:

   // 1. Getting x, y from variables
   Integer x = (Integer)getContext().getVariable("_SEARCH_X");
   Integer y = (Integer)getContext().getVariable("_SEARCH_Y");

   // 2. Getting x, y from context's coordinate list
   Point p = getContext().getSearchHits().get(0);
   x = p.x;
   y = p.y;
 

The context was enhanced in v2.1 to provide comfortable access to image search results and template parameters. See the ScriptingContext.getSearchHits() method documentation for an overview.

Parameters:
templates - list of template images (Image instances).
method - image comparison method code. It may be either "default" (histogram based comparison), "search" (tolerant image search) or eventually code of a custom image comparison algorithm added to the tool in form of a plug in.
passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching).
Returns:
command exit code as is specified in the Compareto specification.
Throws:
java.io.IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(java.io.File[] templates,
                     java.lang.String method,
                     float passRate,
                     java.lang.Integer rgbTolerance)
              throws java.io.IOException

Compare the current remote desktop image to one or more template images using the specified image comparison module instance and numeric pass rate. The method provides access to functionality of the Compareto scripting language command with template images specified in form of java.io.File array.

Result of image comparison is typically indicated by the return value. where 0 usually means success, 1 (one) indicates negative result and higher values indicate an error (for example, image file not found etc.). See the Compareto command specification for the list of error codes.

Image comparison modules (methods) may save additional results to the context. Refer to the CompareTo command specification for details. For example, the "search" module stores coordinates of the match areas both to the variable table as well to a list stored in the context. To retrieve them use either of the following ways:

   // 1. Getting x, y from variables
   Integer x = (Integer)getContext().getVariable("_SEARCH_X");
   Integer y = (Integer)getContext().getVariable("_SEARCH_Y");

   // 2. Getting x, y from context's coordinate list
   Point p = getContext().getSearchHits().get(0);
   x = p.x;
   y = p.y;
 

The context was enhanced in v2.1 to provide comfortable access to image search results and template parameters. See the ScriptingContext.getSearchHits() method documentation for an overview.

Parameters:
templates - list of template images (Image instances).
method - image comparison method code. It may be either "default" (histogram based comparison), "search" (tolerant image search) or eventually code of a custom image comparison algorithm added to the tool in form of a plug in.
passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching).
rgbTolerance - RGB tolerance value. This parameter may be populated only for "search" image comparison algorithm. It is a number between 0 and 100 and it specifies tolerance to color changes on the level of individual pixel R, G, B components. A value of 20 for example makes the search robust against color changes where any of the R, G, B components varies by 20 or less from the template image pixels. It is recommended to use higher values of this parameter or even the limit one of 100 for testing of environments with varying images (for example in Flash or Flex ones). To get best results it is also recommended avoid mixing of the RGB tolerance parameter with other tolerance mechanisms such as pass rate (should be set to 100%) and background filtering (should be off).

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

Returns:
command exit code as is specified in the Compareto specification.
Throws:
java.io.IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(java.io.File[] templates,
                     float passRate)
              throws java.io.IOException

Compare the current remote desktop image to one or more template images using the default histogram based image comparison (code "default") and numeric pass rate. The method provides access to functionality of the Compareto scripting language command with template images specified in form of java.io.File array.

Result of image comparison is typically indicated by the return value. where 0 usually means success, 1 (one) indicates negative result and higher values indicate an error (for example, image file not found etc.). See the Compareto command specification for the list of error codes.

Image comparison modules (methods) may save additional results to the context. Refer to the CompareTo command specification for details. For example, the "default" method stores at least the index and size of the matching template as well as the resulting rate expressing similarity of the two compared images. These values are made available as predefined variables with the _COMPARETO prefix (see the Var command specification for a full list). To retrieve them use the ScriptingContext.getVariable(java.lang.String) method such as:

   // Get the matching template index in input array
   Integer index = (Integer)getContext().getVariable("_COMPARETO_TEMPLATE_INDEX");

   // Resulting pass rate may be accessed directly from context
   Number resultingRate = getContext().getComparisonResult();
 

Parameters:
templates - list of template images (Image instances).
passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching).
Returns:
command exit code as is specified in the Compareto specification.
Throws:
java.io.IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(java.io.File[] templates,
                     float passRate,
                     java.awt.Rectangle cmpArea,
                     java.lang.String text,
                     int distance,
                     java.lang.String pattern)
              throws java.io.IOException

Recognize the text on the screen by a character image collection using the Image Based Text Recognition comparison method. The method provides access to functionality of the Compareto scripting language command with the comparison method name fixed to "text" and support of its specific parameters.

The resulting text from the method is stored in form of individual text lines to _TEXT_LINE[line_number] variables into the context. The number of resulting text lines is available from the _TEXT_LINE_COUNT variable and can be retrieved using the getVariableAsInt("_TEXT_LINE_COUNT") method. The whole text including the new line characters as well as the map of text elements and their coordinates can be obtained directly from the context through the getContext().getRecognizedText(java.awt.Rectangle) and getContext().getRecognizedTextElements() methods.

If the method throws an error caused by misconfiguration or an I/O error, the method returns the value of 1. Text of the errors is made available through the _TEXT_ERROR variable.

Parameters:
cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the recognition will be performed on the full desktop image.
text - a string to look for in the recognized text (optional). If the parameter is specified (not null), the 'pattern' parameter must be null. If the string is found in the recognized text the method returns 0 to indicate success. Otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.
distance - fuzzy string matching factor applied to comparison of the recognized text with value of the 'text' parameter. The distance is an integer based on the Levenshtein distance. It is defined as the minimum number of edits needed to transform one string into the other, with the allowable edit operations being insertion, deletion, or substitution of a single character. This metric is exposed as a new parameter called 'distance' which is an integer number specifying how many characters may be omitted or not recognized properly at a maximum to consider the sample text provided in the 'text' parameter equivalent. The default value of this parameter is 0 which will force exact comparison with the specified text.

Unlike the regular expressions the 'distance' parameter always searches the recognized text for any occurrence of a string matching the given text and distance. There's no need to specify that the string is preceded or trailed by another text. For example, the parameters of distance=1 and test=Apple will produce positive comparison result against recognized text of "The apple is red" because the text contains the word "apple" which may be converted to "Apple" in one character substitution.

pattern - a Pattern compatible regular expression to match against the recognized text (optional). If the parameter is specified (not null), the 'text' parameter must be null. If the recognized text matches the regular expression, the method returns 0 to indicate success or 1 otherwise. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.
Returns:
the exit code as is specified in the Image Based Text Recognition specification. When none of the "text", "distance" and "pattern" parameters is specified the method returns 0 (success) to indicate a successful execution even when no text gets actually recognized. If the text matching parameters are used the method will return either success (0) or fail (non-zero value) depending on whether the recognized text matches or not.
Throws:
java.io.IOException - on an I/O error (can't read an image file and/or can't get image of the remote desktop).

compareTo

public int compareTo(java.io.File[] template,
                     java.lang.String method)
              throws java.io.IOException

Compare the current remote desktop image to one or more template images using the specified image comparison module and default numeric pass rate (100% for "search", 95% for "default" unless the user modified these values in user preferences). The method provides access to functionality of the Compareto scripting language command with template images specified in form of java.io.File array.

Result of image comparison is typically indicated by the return value. where 0 usually means success, 1 (one) indicates negative result and higher values indicate an error (for example, image file not found etc.). See the Compareto command specification for the list of error codes.

Image comparison modules (methods) may save additional results to the context. Refer to the CompareTo command specification for details. For example, the "search" module stores coordinates of the match areas both to the variable table as well to a list stored in the context. To retrieve them use either of the following ways:

   // 1. Getting x, y from variables
   Integer x = (Integer)getContext().getVariable("_SEARCH_X");
   Integer y = (Integer)getContext().getVariable("_SEARCH_Y");

   // 2. Getting x, y from context's coordinate list
   Point p = getContext().getSearchHits().get(0);
   x = p.x;
   y = p.y;
 

The context was enhanced in v2.1 to provide comfortable access to image search results and template parameters. See the ScriptingContext.getSearchHits() method documentation for an overview.

Parameters:
template - list of template images (Image instances).
method - image comparison method code. It may be either "default" (histogram based comparison), "search" (tolerant image search) or eventually code of a custom image comparison algorithm added to the tool in form of a plug in.
Returns:
command exit code as is specified in the Compareto specification.
Throws:
java.io.IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

compareTo

public int compareTo(java.io.File[] templates)
              throws java.io.IOException

Compare the current remote desktop image to one or more template images using the default histogram based image comparison (code "default") and default numeric pass rate (95% unless the user modified the value in user preferences). The method provides access to functionality of the Compareto scripting language command with template images specified in form of java.io.File array.

Result of image comparison is typically indicated by the return value. where 0 usually means success, 1 (one) indicates negative result and higher values indicate an error (for example, image file not found etc.). See the Compareto command specification for the list of error codes.

Image comparison modules (methods) may save additional results to the context. Refer to the CompareTo command specification for details. For example, the "default" method stores at least the index and size of the matching template as well as the resulting rate expressing similarity of the two compared images. These values are made available as predefined variables with the _COMPARETO prefix (see the Var command specification for a full list). To retrieve them use the ScriptingContext.getVariable(java.lang.String) method such as:

   // Get the matching template index in input array
   Integer index = (Integer)getContext().getVariable("_COMPARETO_TEMPLATE_INDEX");

   // Resulting pass rate may be accessed directly from context
   Number resultingRate = getContext().getComparisonResult();
 

Parameters:
templates - list of template images (Image instances).
Returns:
command exit code as is specified in the Compareto specification.
Throws:
java.io.IOException - on an I/O error (can't read file and/or can't get image of the remote desktop).

pause

public int pause(java.lang.String reason)
          throws java.io.IOException

Pause execution of the test script until the user manually resumes it with an optional description for report providers. The method provides access to functionality of the Pause scripting language command.

The pausing functionality should not be confused with the Wait command and its corresponding Java method wait(java.lang.String). While the Wait command takes the time specified to complete and delays the script execution this way, the Pause one sets the pause flag of the test script interpret and lets the scripting framework handle it.

When the method gets called, it fires an internal event (ScriptEvent.SCRIPT_EXECUTION_PAUSED) to all registered listeners. The GUI (if present) typically updates status of the associated controls ("pause" menu item and tool bar button) and highlights the pause command line in the script editor. If the script is being executed in CLI mode, the tool prints out a pause warning message into the console. In both cases the user has to resume the script execution manually either through deselection of the GUI controls or a key press in CLI. To resume programmatically call the TestScriptInterpret.setPause(java.lang.Object, boolean, java.lang.String) method with the pause argument set to false. This functionality is however not visible to the TPR test scripts.

Parameters:
reason - an optional description of why the script was paused. It may be picked up by report providers to display it in the report.
Returns:
command exit code as is specified in the Pause specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

pause

public int pause()
          throws java.io.IOException

Pause execution of the test script until the user manually resumes it. The method provides access to functionality of the Pause scripting language command.

The pausing functionality should not be confused with the Wait command and its corresponding Java method wait(java.lang.String). While the Wait command takes the time specified to complete and delays the script execution this way, the Pause one sets the pause flag of the test script interpret and lets the scripting framework handle it.

When the method gets called, it fires an internal event (ScriptEvent.SCRIPT_EXECUTION_PAUSED) to all registered listeners. The GUI (if present) typically updates status of the associated controls ("pause" menu item and tool bar button) and highlights the pause command line in the script editor. If the script is being executed in CLI mode, the tool prints out a pause warning message into the console. In both cases the user has to resume the script execution manually either through deselection of the GUI controls or a key press in CLI. To resume programmatically call the TestScriptInterpret.setPause(java.lang.Object, boolean, java.lang.String) method with the pause argument set to false. This functionality is however not visible to the TPR test scripts.

Returns:
command exit code as is specified in the Pause specification.
Throws:
java.io.IOException - if an I/O error happens during client-server communication.

exit

public int exit(java.lang.Integer exitCode,
                java.lang.String description)
         throws java.io.IOException
Exit the test script. The argument exit code will be recorded into the results stored to the report file created through a call of one of the methods. The code of 0 is interpreted as "success" while any other value indicates a failure of some type. If the script is executed as a standalone process (typically through the -r CLI option) the exit code is also returned to the underlying operating system.

Parameters:
exitCode - numeric exit code to be returned to the underlying operating system.
description - optional description which will be saved to the test results in form of a variable and it will be displayed in the report.
Returns:
exit code.
Throws:
java.io.IOException

exit

public int exit(java.lang.Integer exitCode)
         throws java.io.IOException
Exit the test script. The argument exit code will be recorded into the results stored to the report file created through a call of one of the methods. The code of 0 is interpreted as "success" while any other value indicates a failure of some type. If the script is executed as a standalone process (typically through the -r CLI option) the exit code is also returned to the underlying operating system.

Parameters:
exitCode - numeric exit code to be returned to the underlying operating system.
Returns:
exit code.
Throws:
java.io.IOException

warning

public int warning(java.lang.String text,
                   java.io.File image)

Add a warning to be picked up by a report provider. The method provides access to functionality of the Warning scripting language command.

Like the screenshot() method, each call of this method inserts a data structure (OutputObject instance) with the warning text, date and optional associated screen shot to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:
text - warning text.
image - optional screen shot file name to associate with this warning. The point is to give the report provider a hint to display the warning close to the previously taken screenshot so that a human may review the reported problem in the image. This argument should correspond to file name argument of a previously executed screenshot() method.
Returns:
command exit code as is specified in the Warning specification.

warning

public int warning(java.lang.String text)
            throws java.io.IOException

Add a warning to be picked up by a report provider. The method provides access to functionality of the Warning scripting language command.

Like the screenshot() method, each call of this method inserts a data structure (OutputObject instance) with the warning text, date and optional associated screen shot to a list in the context (key ScriptingContext.CONTEXT_OUTPUT_OBJECTS). It will also internally fire a specific event which notifies registered listeners of the new screen shot (see CommandEvent.OUTPUT_CHANGED_EVENT). This event may be picked up by any running report provider which may follow up and refresh the report file.

Parameters:
text - warning text.
Returns:
command exit code as is specified in the Warning specification.
Throws:
java.io.IOException - the exception is declared but never thrown because the command doesn't deal with the I/O.

waitForBell

public int waitForBell(int count,
                       java.lang.String timeout,
                       java.lang.String wait)
                throws java.io.IOException
Wait until the remote desktop emits one or more beeps (bells). It provides access to functionality of the WaitFor bell scripting language command.

Parameters:
count - number of expected beeps.
timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition is met (the beep(s) is/are received as expected).
wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).
Returns:
command exit code as is specified in the Waitfor specification. The method returns 0 (zero) when the condition is met and the beeps are received as expected. The value of 1 is returned when the timeout is reached.
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForBell

public int waitForBell(java.lang.String timeout,
                       java.lang.String wait)
                throws java.io.IOException
Wait until the remote desktop beeps (rings a bell). It provides access to functionality of the WaitFor bell scripting language command.

Parameters:
timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition is met (the beep(s) is/are received as expected).
wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).
Returns:
command exit code as is specified in the Waitfor specification. The method returns 0 (zero) when the condition is met and the beeps are received as expected. The value of 1 is returned when the timeout is reached.
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForBell

public int waitForBell(java.lang.String timeout)
                throws java.io.IOException
Wait until the remote desktop beeps (rings a bell). It provides access to functionality of the WaitFor bell scripting language command.

Parameters:
timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition is met (the beep(s) is/are received as expected).
Returns:
command exit code as is specified in the Waitfor specification. The method returns 0 (zero) when the condition is met and the beeps are received as expected. The value of 1 is returned when the timeout is reached.
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForUpdate

public int waitForUpdate(java.awt.Rectangle area,
                         java.lang.String extent,
                         boolean cumulative,
                         java.lang.String timeout,
                         java.lang.String wait)
                  throws java.io.IOException
Wait until the remote desktop refreshes the screen or its particular area. This can be used for a simple script control, for example when an application window is expected to open on the desktop. The method provides access to functionality of the WaitFor update scripting language command.

Parameters:
area - the screen area to be watched for update (use null for the full desktop screen).
extent - percentage of the area pixels that are required to refresh. For example if the area is set to a rectangle of 100 pixels (10x10) and the extent is 90% the command will succeed and resume the script once at least 90 pixels of the area get updated.
cumulative - the value of false requires the whole area or its part to refresh at once. This mode works well only with some VNC servers mainly on non-Windows OSes. The value of true will collate minor updates and resume once the union of the updated rectangles meets the specified area and extent restrictions.
timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition is met (the screen refreshes as expected).
wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).
Returns:
command exit code as is specified in the Waitfor specification. The method returns 0 (zero) when the condition is met and the screen refreshes as expected. The value of 1 is returned when the timeout is reached.
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForUpdate

public int waitForUpdate(java.awt.Rectangle area,
                         java.lang.String extent,
                         java.lang.String timeout,
                         java.lang.String wait)
                  throws java.io.IOException
Wait until the remote desktop refreshes the screen or its particular area. This can be used for a simple script control, for example when an application window is expected to open on the desktop. As this method defaults to the non-cumulative mode it may not work properly with servers which prefer to send a series of minor update events instead of a large one. Use the waitForUpdate(java.awt.Rectangle, java.lang.String, boolean, java.lang.String, java.lang.String) method with the cumulative parameter set to true on such environments. The method provides access to functionality of the WaitFor update scripting language command.

Parameters:
area - the screen area to be watched for update (use null for the full desktop screen).
extent - percentage of the area pixels that are required to refresh. For example if the area is set to a rectangle of 100 pixels (10x10) and the extent is 90% the command will succeed and resume the script once at least 90 pixels of the area get updated.
timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition is met (the screen refreshes as expected).
wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).
Returns:
command exit code as is specified in the Waitfor specification. The method returns 0 (zero) when the condition is met and the screen refreshes as expected. The value of 1 is returned when the timeout is reached.
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForUpdate

public int waitForUpdate(java.awt.Rectangle area,
                         java.lang.String extent,
                         java.lang.String timeout)
                  throws java.io.IOException
Wait until the remote desktop refreshes the screen or its particular area. This can be used for a simple script control, for example when an application window is expected to open on the desktop. As this method defaults to the non-cumulative mode it may not work properly with servers which prefer to send a series of minor update events instead of a large one. Use the waitForUpdate(java.awt.Rectangle, java.lang.String, boolean, java.lang.String, java.lang.String) method with the cumulative parameter set to true on such environments. The method provides access to functionality of the WaitFor update scripting language command.

Parameters:
area - the screen area to be watched for update (use null for the full desktop screen).
extent - percentage of the area pixels that are required to refresh. For example if the area is set to a rectangle of 100 pixels (10x10) and the extent is 90% the command will succeed and resume the script once at least 90 pixels of the area get updated.
timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition is met (the screen refreshes as expected).
Returns:
command exit code as is specified in the Waitfor specification. The method returns 0 (zero) when the condition is met and the screen refreshes as expected. The value of 1 is returned when the timeout is reached.
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForUpdate

public int waitForUpdate(java.lang.String extent,
                         java.lang.String timeout)
                  throws java.io.IOException
Wait until the remote desktop refreshes the whole screen. This can be used for a simple script control, for example when an application window is expected to open on the desktop. As this method defaults to the non-cumulative mode it may not work properly with servers which prefer to send a series of minor update events instead of a large one. Use the waitForUpdate(java.awt.Rectangle, java.lang.String, boolean, java.lang.String, java.lang.String) method with the cumulative parameter set to true on such environments. The method provides access to functionality of the WaitFor update scripting language command.

Parameters:
extent - percentage of the screen pixels that are required to refresh. For example if the extent is 90% the command will succeed and resume the script once at least 90% of the screen pixels get updated.
timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition is met (the screen refreshes as expected).
Returns:
command exit code as is specified in the Waitfor specification. The method returns 0 (zero) when the condition is met and the screen refreshes as expected. The value of 1 is returned when the timeout is reached.
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMatch

public int waitForMatch(java.awt.Image[] templates,
                        float passRate,
                        java.lang.String interval,
                        java.awt.Rectangle cmpArea,
                        java.lang.String timeout,
                        boolean removeBg,
                        java.lang.String bgColor,
                        java.lang.Integer minAlpha,
                        java.lang.String wait)
                 throws java.io.IOException

Pause the script until the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.awt.Image[], com.tplan.robot.imagecomparison.ImageComparisonModule, float, java.awt.Rectangle, java.lang.Boolean, java.awt.Color, java.lang.Integer) one save that it performs image comparison repeatedly at scheduled intervals until either a match or timeout is achieved.

This particular method deals with template images in form of java.awt.Image array. It is also hard coded to the image search algorithm (code "search") and supports its specific template background filtering parameters removebg, bgcolor and minalpha.

Parameters:
templates - list of template images (Image instances).
passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching). To use the default pass rate defined for the particular image comparison method set the value to a negative number.
interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).
cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.
timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition (positive image comparison result) is met.
removeBg -

set on/off filtering of background color. It is a new 2.1 feature allowing to search for objects on varying background. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). The background filter is applied only to completely opaque template images which do not contain any translucent or transparent pixels introduced through third party image editors. When an existing translucency is detected the filter is switched off silently and only the eventual minAlpha parameter is applied.

The default value is null (equivalent to "false") meaning that background filtering is off. See the Compareto documentation for details.

bgColor - optional color for the background filter. The parameter is ignored when background filtering is off. If the color is not specified (is null), the background filter will use color of the very first image pixel at [0,0] (upper left image corner).
minAlpha - translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing translucent pixels. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). Alpha is a pixel color component between 0 (transparent) and 255 (opaque) which defines the level of pixel translucency. The default minalpha value of null or -1 (internally equal to 255) instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Other values between 0 and 254 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit. Comparison of such pixels is based on color similarity with a fixed threshold.
wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).
Returns:
command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a positive result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes, 1 when it fails and 2 when one or more template images are not found or cannot be read.
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMatch

public int waitForMatch(java.awt.Image[] templates,
                        float passRate,
                        java.lang.String interval,
                        java.awt.Rectangle cmpArea,
                        java.lang.String timeout,
                        boolean removeBg,
                        java.lang.String bgColor,
                        java.lang.Integer minAlpha,
                        java.lang.Integer rgbTolerance,
                        java.lang.String wait)
                 throws java.io.IOException

Pause the script until the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.awt.Image[], com.tplan.robot.imagecomparison.ImageComparisonModule, float, java.awt.Rectangle, java.lang.Boolean, java.awt.Color, java.lang.Integer) one save that it performs image comparison repeatedly at scheduled intervals until either a match or timeout is achieved.

This particular method deals with template images in form of java.awt.Image array. It is also hard coded to the image search algorithm (code "search") and supports its specific template background filtering parameters removebg, bgcolor, minalpha and tolerance.

Parameters:
templates - list of template images (Image instances).
passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching). To use the default pass rate defined for the particular image comparison method set the value to a negative number.
interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).
cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.
timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition (positive image comparison result) is met.
removeBg -

set on/off filtering of background color. It is a new 2.1 feature allowing to search for objects on varying background. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). The background filter is applied only to completely opaque template images which do not contain any translucent or transparent pixels introduced through third party image editors. When an existing translucency is detected the filter is switched off silently and only the eventual minAlpha parameter is applied.

The default value is null (equivalent to "false") meaning that background filtering is off. See the Compareto documentation for details.

bgColor - optional color for the background filter. The parameter is ignored when background filtering is off. If the color is not specified (is null), the background filter will use color of the very first image pixel at [0,0] (upper left image corner).
minAlpha - translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing translucent pixels. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). Alpha is a pixel color component between 0 (transparent) and 255 (opaque) which defines the level of pixel translucency. The default minalpha value of null or -1 (internally equal to 255) instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Other values between 0 and 254 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit. Comparison of such pixels is based on color similarity with a fixed threshold.
wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).
rgbTolerance - RGB tolerance value. This parameter may be populated only for "search" image comparison algorithm. It is a number between 0 and 100 and it specifies tolerance to color changes on the level of individual pixel R, G, B components. A value of 20 for example makes the search robust against color changes where any of the R, G, B components varies by 20 or less from the template image pixels. It is recommended to use higher values of this parameter or even the limit one of 100 for testing of environments with varying images (for example in Flash or Flex ones). To get best results it is also recommended avoid mixing of the RGB tolerance parameter with other tolerance mechanisms such as pass rate (should be set to 100%) and background filtering (should be off).

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

Returns:
command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a positive result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes, 1 when it fails and 2 when one or more template images are not found or cannot be read.
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMatch

public int waitForMatch(java.lang.String interval,
                        java.awt.Rectangle cmpArea,
                        java.lang.String timeout,
                        java.lang.String language,
                        java.lang.String text,
                        java.lang.String pattern,
                        java.lang.String wait)
                 throws java.io.IOException

Pause the script until the text recognized through Tesseract OCR contains a string or matches a regular expression or until the time out limit is reached. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.awt.Rectangle, java.lang.String, java.lang.String, java.lang.String) one save that it performs image comparison repeatedly at scheduled intervals until either a match or timeout is achieved.

Result of OCR is indicated by the return value where 0 usually means success, and 1 (one) indicates negative result. This method by default returns the value of 0 if the OCR is performed successfully and the value of 1 if the command fails, for example when the engine is not installed or misconfigured or the language code is not supported. If either 'text' or 'pattern' parameter is specified, the method returns 0 to indicate success only if the OCR performs successfully and the resulting text contains the string specified by 'text' or matches the 'pattern' regular expression.

The resulting text from OCR is stored in form of individual text lines to _TOCR_LINE[line_number] variables into the context. The number of resulting text lines is available from the _TOCR_LINE_COUNT variable. The whole text including the new line characters is also available as a String through the getContext().get(TesseractOCR.CONTEXT_TOCR_TEXT) method.

If the OCR throws an error caused by misconfiguration or an I/O error, the method returns the value of 1. Text of the errors is made available through the _TOCR_ERROR variable. Testing of existence of this variable is the only way to detect core OCR errors in test scripts.

See the TesseractOCR class documentation for details on how to install and configure Tesseract.

Parameters:
interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).
cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.
timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition (positive image comparison result) is met.
wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).
language - target language (optional). It must be the 3-char lower case code of a properly installed Tesseract language data file set. For example, English code is "eng", German is "deu", Spanish is "spa" etc. This parameter will be passed as value of the "-l" argument to the engine. See the Tesseract's download page for the list of supported language files.
text - a string to look for in the recognized text (optional). If the parameter is specified (not null), the 'pattern' parameter must be null. If the string is found in the text resulting from OCR, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.
pattern - a Pattern compatible regular expression to match against the recognized text (optional). If the parameter is specified (not null), the 'text' parameter must be null. If the text resulting from OCR matches the regular expression, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.
Returns:
command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a positive result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes, 1 when it fails and 2 when one or more template images are not found or cannot be read.
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMatch

public int waitForMatch(java.io.File[] templates,
                        float passRate,
                        java.awt.Rectangle cmpArea,
                        java.lang.String interval,
                        java.lang.String timeout,
                        java.lang.String text,
                        int distance,
                        java.lang.String pattern,
                        java.lang.String wait)
                 throws java.io.IOException
Pause the script until the text recognized through the Image Based Text Recognition comparison method contains a string or matches a regular expression or until the time out limit is reached. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.io.File[], float, java.awt.Rectangle, java.lang.String, int, java.lang.String) one save that it performs image comparison repeatedly at scheduled intervals until either a match or timeout is achieved.

Recognize the text on the screen by a character image collection using . The method provides access to functionality of the Compareto scripting language command with the comparison method name fixed to "text" and support of its specific parameters.

The resulting text from the method is stored in form of individual text lines to _TEXT_LINE[line_number] variables into the context. The number of resulting text lines is available from the _TEXT_LINE_COUNT variable and can be retrieved using the getVariableAsInt("_TEXT_LINE_COUNT") method. The whole text including the new line characters as well as the map of text elements and their coordinates can be obtained directly from the context through the getContext().getRecognizedText(java.awt.Rectangle) and getContext().getRecognizedTextElements() methods.

If the method throws an error caused by misconfiguration or an I/O error, the method returns the value of 1. Text of the errors is made available through the _TEXT_ERROR variable.

Parameters:
cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the recognition will be performed on the full desktop image.
text - a string to look for in the recognized text (optional). If the parameter is specified (not null), the 'pattern' parameter must be null. If the string is found in the recognized text the method returns 0 to indicate success. Otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.
distance - fuzzy string matching factor applied to comparison of the recognized text with value of the 'text' parameter. The distance is an integer based on the Levenshtein distance. It is defined as the minimum number of edits needed to transform one string into the other, with the allowable edit operations being insertion, deletion, or substitution of a single character. This metric is exposed as a new parameter called 'distance' which is an integer number specifying how many characters may be omitted or not recognized properly at a maximum to consider the sample text provided in the 'text' parameter equivalent. The default value of this parameter is 0 which will force exact comparison with the specified text.

Unlike the regular expressions the 'distance' parameter always searches the recognized text for any occurrence of a string matching the given text and distance. There's no need to specify that the string is preceded or trailed by another text. For example, the parameters of distance=1 and test=Apple will produce positive comparison result against recognized text of "The apple is red" because the text contains the word "apple" which may be converted to "Apple" in one character substitution.

pattern - a Pattern compatible regular expression to match against the recognized text (optional). If the parameter is specified (not null), the 'text' parameter must be null. If the recognized text matches the regular expression, the method returns 0 to indicate success or 1 otherwise. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.
Returns:
the exit code as is specified in the Image Based Text Recognition specification. When none of the "text", "distance" and "pattern" parameters is specified the method returns 0 (success) to indicate a successful execution even when no text gets actually recognized. If the text matching parameters are used the method will return either success (0) or fail (non-zero value) depending on whether the recognized text matches or not.
Throws:
java.io.IOException - on an I/O error (can't read an image file and/or can't get image of the remote desktop).

waitForMatch

public int waitForMatch(java.lang.String interval,
                        java.awt.Rectangle cmpArea,
                        java.lang.String timeout,
                        java.lang.String language,
                        float scale,
                        java.lang.String text,
                        int distance,
                        java.lang.String pattern,
                        java.lang.String wait)
                 throws java.io.IOException

Pause the script until the text recognized through Tesseract OCR contains a string or matches a regular expression or until the time out limit is reached. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.awt.Rectangle, java.lang.String, java.lang.String, java.lang.String) one save that it performs image comparison repeatedly at scheduled intervals until either a match or timeout is achieved.

Result of OCR is indicated by the return value where 0 usually means success, and 1 (one) indicates negative result. This method by default returns the value of 0 if the OCR is performed successfully and the value of 1 if the command fails, for example when the engine is not installed or misconfigured or the language code is not supported. If either 'text' or 'pattern' parameter is specified, the method returns 0 to indicate success only if the OCR performs successfully and the resulting text contains the string specified by 'text' or matches the 'pattern' regular expression.

The resulting text from OCR is stored in form of individual text lines to _TOCR_LINE[line_number] variables into the context. The number of resulting text lines is available from the _TOCR_LINE_COUNT variable. The whole text including the new line characters is also available as a String through the getContext().get(TesseractOCR.CONTEXT_TOCR_TEXT) method.

If the OCR throws an error caused by misconfiguration or an I/O error, the method returns the value of 1. Text of the errors is made available through the _TOCR_ERROR variable. Testing of existence of this variable is the only way to detect core OCR errors in test scripts.

See the TesseractOCR class documentation for details on how to install and configure Tesseract.

Parameters:
interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).
cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the OCR will be performed on the full desktop image.
language - target language (optional). It must be the 3-char lower case code of a properly installed Tesseract language data file set. For example, English code is "eng", German is "deu", Spanish is "spa" etc. This parameter will be passed as value of the "-l" argument to the engine. See the Tesseract's download page for the list of supported language files. If the parameter is null, it will default to the English one ("eng").
scale - magnification factor. The method magnifies (enlarges) the image by the given factor to improve OCR accuracy. If this parameter is set to a value below 0, it defaults to the value configured in the Tesseract OCR Plugin preferences (the factory setting is 2 meaning that the image shall be enlarged to 200% of its original size).
text - a string to look for in the recognized text (optional). If the parameter is specified (not null), the 'pattern' parameter must be null. If the string is found in the text resulting from OCR, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.
distance - fuzzy string matching factor applied to comparison of the recognized text with value of the 'text' parameter. The distance is an integer based on the Levenshtein distance. It is defined as the minimum number of edits needed to transform one string into the other, with the allowable edit operations being insertion, deletion, or substitution of a single character. This metric is exposed as a new parameter called 'distance' which is an integer number specifying how many characters may be omitted or not recognized properly at a maximum to consider the sample text provided in the 'text' parameter equivalent. The default value of this parameter is 0 which will force exact comparison with the specified text.

Unlike the regular expressions the 'distance' parameter always searches the recognized text for any occurrence of a string matching the given text and distance. There's no need to specify that the string is preceded or trailed by another text. For example, the parameters of distance=1 and test=Apple will produce positive comparison result against recognized text of "The apple is red" because the text contains the word "apple" which may be converted to "Apple" in one character substitution.

pattern - a Pattern compatible regular expression to match against the recognized text (optional). If the parameter is specified (not null), the 'text' parameter must be null. If the text resulting from OCR matches the regular expression, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.
Returns:
command exit code as is specified in the Waitfor specification. The method returns 0 (zero) when the OCR was performed successfully. If either the 'pattern' or 'text' are specified, the method returns 0 when the recognized text matches the given text/regular expression or 1 otherwise..
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMatch

public int waitForMatch(java.lang.String interval,
                        java.awt.Rectangle cmpArea,
                        java.lang.String timeout,
                        java.lang.String language,
                        float scale,
                        java.lang.String text,
                        int distance,
                        java.lang.String pattern,
                        int mode,
                        int filter,
                        int fontSize,
                        java.lang.String wait)
                 throws java.io.IOException

Pause the script until the text recognized through Tesseract OCR contains a string or matches a regular expression or until the time out limit is reached. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.awt.Rectangle, java.lang.String, java.lang.String, java.lang.String) one save that it performs image comparison repeatedly at scheduled intervals until either a match or timeout is achieved.

Result of OCR is indicated by the return value where 0 usually means success, and 1 (one) indicates negative result. This method by default returns the value of 0 if the OCR is performed successfully and the value of 1 if the command fails, for example when the engine is not installed or misconfigured or the language code is not supported. If either 'text' or 'pattern' parameter is specified, the method returns 0 to indicate success only if the OCR performs successfully and the resulting text contains the string specified by 'text' or matches the 'pattern' regular expression.

The resulting text from OCR is stored in form of individual text lines to _TOCR_LINE[line_number] variables into the context. The number of resulting text lines is available from the _TOCR_LINE_COUNT variable. The whole text including the new line characters is also available as a String through the getContext().get(TesseractOCR.CONTEXT_TOCR_TEXT) method.

If the OCR throws an error caused by misconfiguration or an I/O error, the method returns the value of 1. Text of the errors is made available through the _TOCR_ERROR variable. Testing of existence of this variable is the only way to detect core OCR errors in test scripts.

See the TesseractOCR class documentation for details on how to install and configure Tesseract.

Parameters:
interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).
cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the OCR will be performed on the full desktop image.
language - target language (optional). It must be the 3-char lower case code of a properly installed Tesseract language data file set. For example, English code is "eng", German is "deu", Spanish is "spa" etc. This parameter will be passed as value of the "-l" argument to the engine. See the Tesseract's download page for the list of supported language files. If the parameter is null, it will default to the English one ("eng").
scale - magnification factor. The method magnifies (enlarges) the image by the given factor to improve OCR accuracy. If this parameter is set to a value below 0, it defaults to the value configured in the Tesseract OCR Plugin preferences (the factory setting is 2 meaning that the image shall be enlarged to 200% of its original size).
text - a string to look for in the recognized text (optional). If the parameter is specified (not null), the 'pattern' parameter must be null. If the string is found in the text resulting from OCR, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.
distance - fuzzy string matching factor applied to comparison of the recognized text with value of the 'text' parameter. The distance is an integer based on the Levenshtein distance. It is defined as the minimum number of edits needed to transform one string into the other, with the allowable edit operations being insertion, deletion, or substitution of a single character. This metric is exposed as a new parameter called 'distance' which is an integer number specifying how many characters may be omitted or not recognized properly at a maximum to consider the sample text provided in the 'text' parameter equivalent. The default value of this parameter is 0 which will force exact comparison with the specified text.

Unlike the regular expressions the 'distance' parameter always searches the recognized text for any occurrence of a string matching the given text and distance. There's no need to specify that the string is preceded or trailed by another text. For example, the parameters of distance=1 and test=Apple will produce positive comparison result against recognized text of "The apple is red" because the text contains the word "apple" which may be converted to "Apple" in one character substitution.

pattern - a Pattern compatible regular expression to match against the recognized text (optional). If the parameter is specified (not null), the 'text' parameter must be null. If the text resulting from OCR matches the regular expression, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.
mode - the OCR mode (since 3.5). It allows to modify the engine behavior in special cases to get better results. This parameter is optional. To leave the mode on default specify any value equal to or less than 1. The supported modes are:
  1. Default Tesseract mode (the value of 1). It is the Tesseract's default mode of automatic page segmentation with no OSD (the "-psm 3" CLI switch). This value is compatible with the Robot releases prior to 3.5.
  2. High accuracy (mode 2). This is a Robot enhancement which splits the text on the screen into lines and reapplies the OCR separately in the line mode (-psm 7). This approach is several times slower but typically delivers more accurate results, especially where the OCR is applied to a smaller screen area such as an application window.
  3. Treat the image as a single word (mode 8). Use this mode when the recognized text is up to 3 characters long. This is Tesseract's native mode driven through the "-psm 8" CLI switch.
filter - optional image filter code (since 3.5). It removes certain artifacts on the screen in order to improve the OCR accuracy. The filter should be applied selectively where the target screen or its part contains text of dark color in rectangular areas with solid color background, such as for example application windows with standard solid gray or white buttons, drop downs and other components. White or bright color text and rich color graphics such as images or photographs are not suitable for filtering. Usage of the filter in such scenes may damage the text and decrease the OCR accuracy.

The supported filter codes are:
  1. 0 - No filter (default).
  2. 1 - Remove artefacts. It will remove typical application components consisting of horizontal and vertical solid color lines (borders).
  3. 2 - Remove artefacts and underlines will remove components and single character underlines typical for application menus.
  4. 3 - Remove artefacts, underlines and dashed lines will remove components, underlines and any dashed line borders which typically mark a selected component or the one that currently owns the focus. The dash line pattern must be populated properly in the 'tocr' method preferences in order to get recognized and removed properly.
The filter is optional. To leave this parameter on default provide any value equal to or less than 0.
fontSize - an approximate font size of the text to be recognized (since 3.5). The default value is 15. It is used only when the image filter is on. It tells the filter not to remove artifacts that are smaller than or equal to the font size. When the value is much smaller than the actual font size the filter may cripple some of the characters. When the value is too large the filter will fail to remove certain artifacts (components) from the screen which may result in lower accuracy.

The font size is optional. To leave this parameter on default provide any value equal to or less than 0.
Returns:
command exit code as is specified in the Waitfor specification. The method returns 0 (zero) when the OCR was performed successfully. If either the 'pattern' or 'text' are specified, the method returns 0 when the recognized text matches the given text/regular expression or 1 otherwise..
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMatch

public int waitForMatch(java.awt.Image[] templates,
                        float passRate,
                        java.lang.String interval,
                        java.lang.String method,
                        java.lang.String methodParams,
                        java.awt.Rectangle cmpArea,
                        java.lang.String timeout,
                        java.lang.String wait)
                 throws java.io.IOException

Pause the script until the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.awt.Image[], com.tplan.robot.imagecomparison.ImageComparisonModule, float, java.awt.Rectangle) one save that it performs image comparison repeatedly at scheduled intervals until either a match or timeout is achieved.

This particular method deals with template images in form of java.awt.Image array and allows to select the image comparison method ("search" for image search, "default" for histogram based comparison or eventually any other code of third party algorithm installed as a plug in).

Parameters:
templates - list of template images (Image instances).
passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching). To use the default pass rate defined for the particular image comparison method set the value to a negative number.
interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).
method - use "search" for image search, "default" for histogram based comparison or eventually any other code of third party algorithm installed as a plug in.
methodParams - use null for both the "default" and "search" methods. This is a legacy parameter intended to let custom plugins to receive specific parameters from a script.
cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.
timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition (positive image comparison result) is met.
wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).
Returns:
command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a positive result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes, 1 when it fails and 2 when one or more template images are not found or cannot be read.
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMatch

public int waitForMatch(java.io.File[] templates,
                        float passRate,
                        java.lang.String interval,
                        java.awt.Rectangle cmpArea,
                        java.lang.String timeout,
                        boolean removeBg,
                        java.lang.String bgColor,
                        java.lang.Integer minAlpha,
                        java.lang.Integer rgbTolerance,
                        java.lang.String wait)
                 throws java.io.IOException

Pause the script until the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.io.File[], float, java.awt.Rectangle, boolean, java.lang.String, java.lang.Integer) one save that it performs image comparison repeatedly at scheduled intervals until either a match or timeout is achieved.

This particular method deals with template images in form of java.io.File array. It is also hard coded to the image search algorithm (code "search") and supports its specific template background filtering parameters removebg, bgcolor and minalpha.

Parameters:
templates - list of template images (Image instances).
passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching). To use the default pass rate defined for the particular image comparison method set the value to a negative number.
interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).
cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.
timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition (positive image comparison result) is met.
removeBg -

set on/off filtering of background color. It is a new 2.1 feature allowing to search for objects on varying background. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). The background filter is applied only to completely opaque template images which do not contain any translucent or transparent pixels introduced through third party image editors. When an existing translucency is detected the filter is switched off silently and only the eventual minAlpha parameter is applied.

The default value is null (equivalent to "false") meaning that background filtering is off. See the Compareto documentation for details.

bgColor - optional color for the background filter. The parameter is ignored when background filtering is off. If the color is not specified (is null), the background filter will use color of the very first image pixel at [0,0] (upper left image corner).
minAlpha - translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing translucent pixels. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). Alpha is a pixel color component between 0 (transparent) and 255 (opaque) which defines the level of pixel translucency. The default minalpha value of null or -1 (internally equal to 255) instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Other values between 0 and 254 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit. Comparison of such pixels is based on color similarity with a fixed threshold.
wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).
rgbTolerance - RGB tolerance value. This parameter may be populated only for "search" image comparison algorithm. It is a number between 0 and 100 and it specifies tolerance to color changes on the level of individual pixel R, G, B components. A value of 20 for example makes the search robust against color changes where any of the R, G, B components varies by 20 or less from the template image pixels. It is recommended to use higher values of this parameter or even the limit one of 100 for testing of environments with varying images (for example in Flash or Flex ones). To get best results it is also recommended avoid mixing of the RGB tolerance parameter with other tolerance mechanisms such as pass rate (should be set to 100%) and background filtering (should be off).

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

Returns:
command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a positive result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes, 1 when it fails and 2 when one or more template images are not found or cannot be read.
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMatch

public int waitForMatch(java.io.File[] templates,
                        float passRate,
                        java.lang.String interval,
                        java.awt.Rectangle cmpArea,
                        java.lang.String timeout,
                        java.lang.String sort,
                        float[] scale,
                        java.lang.String wait)
                 throws java.io.IOException

Pause the script until the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.io.File[], float, java.awt.Rectangle, boolean, java.lang.String, java.lang.Integer) one save that it performs image comparison repeatedly at scheduled intervals until either a match or timeout is achieved.

This particular method deals with template images in form of java.io.File array. It is also hard coded to the Enterprise Image Search v2 algorithm (code "search2") and it supports its specific parameter of order.

Parameters:
templates - list of template images (Image instances).
passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching). To use the default pass rate defined for the particular image comparison method set the value to a negative number.
interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).
cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.
timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition (positive image comparison result) is met.
sort - the sort order for the resulting match locations (Point/Rectangle). Supported modes:
  • "best" - Put the best matching location first (default mode).
  • "none" - Don't sort and leave the results in their natural "reading" order (left to right, top to bottom). This mode will produce the same order as the legacy "search" method.
  • "top" - Sort locations from the top to the bottom (topmost first).
  • "bottom" - Sort locations from the bottom to the top (bottommost first).
  • "left" - Sort locations from the left to the right (leftmost first).
  • "right" - Sort locations from the right to the left (rightmost first).
When the argument is null the sort mode defaults to the "best" one.
scale - allows to search for scaled instances of the input image (supported since 4.0). To set off scaling use the value of 0 (ignore) or 1 (use original size). When the value is greater than zero it is being handled as a scale ratio. For example, the value of 2.0 will search for the component whose width and height are magnified twice.

There are two negative constants which can be specified to employ dynamic scaling. They will scale the input image(s) with regard to the difference between the current desktop resolution and size of the desktop the template (component) image was created from. As Robot 3.x and older did not save the desktop resolution to the template meta data, the image must be created or updated with Robot 4.0 to enable this operation. The supported scale modes are:

  • -1 ("stretch mode") will scale the input image following the desktop width and height changes independently. The resulting image may or may not have the same width and height proportions (the width/height ratio).
  • -2 ("proportional scale mode") will pick up the smaller relative change of the desktop width and height and use it for both width and height scaling. The resulting image will have the the same proportions (the width/height ratio).
Returns:
command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a positive result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes, 1 when it fails and 2 when one or more template images are not found or cannot be read.
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMatch

public int waitForMatch(java.io.File[] templates,
                        float passRate,
                        java.lang.String interval,
                        java.awt.Rectangle cmpArea,
                        java.lang.String timeout,
                        java.lang.String sort,
                        java.lang.String wait)
                 throws java.io.IOException

Pause the script until the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.io.File[], float, java.awt.Rectangle, boolean, java.lang.String, java.lang.Integer) one save that it performs image comparison repeatedly at scheduled intervals until either a match or timeout is achieved.

This particular method deals with template images in form of java.io.File array. It is also hard coded to the Enterprise Image Search v2 algorithm (code "search2") and it supports its specific parameter of order.

Parameters:
templates - list of template images (Image instances).
passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching). To use the default pass rate defined for the particular image comparison method set the value to a negative number.
interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).
cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.
timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition (positive image comparison result) is met.
sort - the sort order for the resulting match locations (Point/Rectangle). Supported modes:
  • "best" - Put the best matching location first (default mode).
  • "none" - Don't sort and leave the results in their natural "reading" order (left to right, top to bottom). This mode will produce the same order as the legacy "search" method.
  • "top" - Sort locations from the top to the bottom (topmost first).
  • "bottom" - Sort locations from the bottom to the top (bottommost first).
  • "left" - Sort locations from the left to the right (leftmost first).
  • "right" - Sort locations from the right to the left (rightmost first).
When the argument is null the sort mode defaults to the "best" one.
Returns:
command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a positive result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes, 1 when it fails and 2 when one or more template images are not found or cannot be read.
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMatch

public int waitForMatch(java.io.File[] templates,
                        float passRate,
                        java.lang.String interval,
                        java.awt.Rectangle cmpArea,
                        java.lang.String timeout,
                        boolean removeBg,
                        java.lang.String bgColor,
                        java.lang.Integer minAlpha,
                        java.lang.String wait)
                 throws java.io.IOException

Pause the script until the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.io.File[], float, java.awt.Rectangle, boolean, java.lang.String, java.lang.Integer) one save that it performs image comparison repeatedly at scheduled intervals until either a match or timeout is achieved.

This particular method deals with template images in form of java.io.File array. It is also hard coded to the image search algorithm (code "search") and supports its specific template background filtering parameters removebg, bgcolor and minalpha.

Parameters:
templates - list of template images (Image instances).
passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching). To use the default pass rate defined for the particular image comparison method set the value to a negative number.
interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).
cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.
timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition (positive image comparison result) is met.
removeBg -

set on/off filtering of background color. It is a new 2.1 feature allowing to search for objects on varying background. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). The background filter is applied only to completely opaque template images which do not contain any translucent or transparent pixels introduced through third party image editors. When an existing translucency is detected the filter is switched off silently and only the eventual minAlpha parameter is applied.

The default value is null (equivalent to "false") meaning that background filtering is off. See the Compareto documentation for details.

bgColor - optional color for the background filter. The parameter is ignored when background filtering is off. If the color is not specified (is null), the background filter will use color of the very first image pixel at [0,0] (upper left image corner).
minAlpha - translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing translucent pixels. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). Alpha is a pixel color component between 0 (transparent) and 255 (opaque) which defines the level of pixel translucency. The default minalpha value of null or -1 (internally equal to 255) instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Other values between 0 and 254 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit. Comparison of such pixels is based on color similarity with a fixed threshold.
wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).
Returns:
command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a positive result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes, 1 when it fails and 2 when one or more template images are not found or cannot be read.
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMatch

public int waitForMatch(java.io.File[] templates,
                        float passRate,
                        java.lang.String interval,
                        java.lang.String method,
                        java.lang.String methodParams,
                        java.awt.Rectangle cmpArea,
                        java.lang.String timeout,
                        java.lang.String wait)
                 throws java.io.IOException

Pause the script until the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.io.File[], java.lang.String, java.lang.String, float, java.awt.Rectangle) one save that it performs image comparison repeatedly at scheduled intervals until either a match or timeout is achieved.

This particular method deals with template images in form of java.io.File array and allows to select the image comparison method ("search" for image search, "default" for histogram based comparison or eventually any other code of third party algorithm installed as a plug in).

Parameters:
templates - list of template images (Image instances).
passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching). To use the default pass rate defined for the particular image comparison method set the value to a negative number.
interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).
method - use "search" for image search, "default" for histogram based comparison or eventually any other code of third party algorithm installed as a plug in.
methodParams - use null for both the "default" and "search" methods. This is a legacy parameter intended to let custom plugins to receive specific parameters from a script.
cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.
timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition (positive image comparison result) is met.
wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).
Returns:
command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a positive result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes, 1 when it fails and 2 when one or more template images are not found or cannot be read.
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMatch

public int waitForMatch(java.io.File template,
                        float passRate,
                        java.lang.String interval,
                        java.awt.Rectangle cmpArea,
                        java.lang.String timeout,
                        java.awt.Color color,
                        java.awt.Color[] bridgeColors,
                        java.lang.Integer rgbTolerance,
                        java.lang.Integer rotations,
                        java.lang.Boolean draw,
                        java.lang.Boolean clear,
                        java.lang.String wait)
                 throws java.io.IOException

Pause the script until the current remote desktop contains at least one object located by the Object Search image comparison method. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.io.File, java.lang.Float, java.awt.Rectangle, java.awt.Color, java.awt.Color[], java.lang.Integer, java.lang.Integer, java.lang.Boolean, java.lang.Boolean) one save that it performs image comparison repeatedly at scheduled intervals until either a match or timeout is achieved.

The Object Search module searches the desktop image or its rectangular part for objects of a particular color or colors within the tolerated RGB variance. It also allows to filter the object list by an optional template image with detection of eventual object rotation. The method was designed to handle simple image analysis tasks such as "find all black triangles in any level of rotation on the screen".

As the method always locates the largest possible object and it doesn't search recursively for any other ones it may contain, this approach is not suitable for classic GUI components which are often framed, overlayed and merged together. The method however performs very well in testing of schemes, maps and images with low color scenes generated for example by Geographic Information System (GIS) applications or systems producing simple image data. The method can be also employed to check whether an object of a certain color or color range is present on the screen, for example to answer a question like "is there any red message in this particular area?".

The algorithm first scans the image for the first pixel which meets the input color criteria. Than it follows the outer shape of each such an object until the shape gets closed. The objects are internally stored as a list of java.awt.Shape instances in the context and may be retrieved through the through the ScriptingContext.getObjectSearchShapes() convenience method. Besides the raw shape data the method also stores bounding rectangle of each object into the context in form of four variables _OBJECT_X_[n], _OBJECT_Y_[n], _OBJECT_W_[n] and _OBJECT_H_[n] which represent the top left corner [x,y] coordinates, width and height. The [n] expression is the object ordinary number starting from 1. The number of objects available is stored under the _OBJECT_COUNT variable. These variables are the only data exposed to the standard scripting language.

Parameters:
template - an optional template image to filter the list of objects by (a File instance). It must contain just one shape of the specified color and/or tolerance in any level of rotation. When it is provided, the list of objects will be filtered to leave just shapes which are similar to the template image shape up to the ratio specified by the 'passrate' parameter. If the 'rotations' parameter is also specified and is greater than 1, the object list will be matched against the list of template shapes rotated the specified number of times. If the template image is not specified, the algorithm locates all objects matching the color parameters regardless of their size or shape.
passRate - pass rate as percentage between 0 and 100. The pass rate makes sense only when the template is not null and specifies the percentage of acceptable pixel variance from the template image.
cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.
color - defines the object color.
bridgeColors - is optional list of additional admissible object colors. This allows to search for continuous objects which are expected to have other objects of known colors painted over them. Colors in this list are always compared using the exact RGB match and they do not work with the rgbTolerance parameter.
rgbTolerance - RGB tolerance value. It must be an integer number between 0 and 256. It indicates how much the Red, Green and Blue components of a pixel may differ at a maximum to consider the color be equivalent to the object color specified by the 'color' parameter. This value allows to deal with blurred images where the shapes are not formed by a solid color but rather a range of similar colors. Be however aware that the higher the tolerance value, the higher the probability of false shape detections is. In most scenarios the value should be in the [0, 100] range depending on the blurring level. If the parameter is not specified, it defaults to zero and the algorithm looks for solid color objects only.

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

rotations - makes only sense when a template image is provided. It defines rotation granularity. It basically says how many times to rotate the object extracted from the template for filtering purposes. For example, the value of 36 will rotate the shape in 10 degree steps. Obviously, a high number of rotations increases accuracy of recognition of rotated objects but decreases performance. Low rotation values may be compensated through lowering the 'passrate' parameter. This approach is somewhat better in terms of performance but raises the risk of wrong detection of objects similar enough to the template one.
clear - optional boolean flag dealing with result highlighting in the GUI. The clear parameter allows to clear up all drawings created by the previously called object searches. The drawings are also automatically reset when the script finishes.
draw - optional boolean flag dealing with result highlighting in the GUI. When the draw parameter is 'true', the algorithm draws the object rectangles over the desktop image in the desktop viewer GUI component.
interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).
timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition (positive image comparison result) is met.
wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).
Returns:
command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a positive result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes, 1 when it fails and 2 when one or more template images are not found or cannot be read.
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMatch

public int waitForMatch(java.awt.Image template,
                        float passRate,
                        java.lang.String interval,
                        java.awt.Rectangle cmpArea,
                        java.lang.String timeout,
                        java.awt.Color color,
                        java.awt.Color[] bridgeColors,
                        java.lang.Integer rgbTolerance,
                        java.lang.Integer rotations,
                        java.lang.Boolean draw,
                        java.lang.Boolean clear,
                        java.lang.String wait)
                 throws java.io.IOException

Pause the script until the current remote desktop contains at least one object located by the Object Search image comparison method. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.awt.Image, java.lang.Float, java.awt.Rectangle, java.awt.Color, java.awt.Color[], java.lang.Integer, java.lang.Integer, java.lang.Boolean, java.lang.Boolean) one save that it performs image comparison repeatedly at scheduled intervals until either a match or timeout is achieved.

The Object Search module searches the desktop image or its rectangular part for objects of a particular color or colors within the tolerated RGB variance. It also allows to filter the object list by an optional template image with detection of eventual object rotation. The method was designed to handle simple image analysis tasks such as "find all black triangles in any level of rotation on the screen".

As the method always locates the largest possible object and it doesn't search recursively for any other ones it may contain, this approach is not suitable for classic GUI components which are often framed, overlayed and merged together. The method however performs very well in testing of schemes, maps and images with low color scenes generated for example by Geographic Information System (GIS) applications or systems producing simple image data. The method can be also employed to check whether an object of a certain color or color range is present on the screen, for example to answer a question like "is there any red message in this particular area?".

The algorithm first scans the image for the first pixel which meets the input color criteria. Than it follows the outer shape of each such an object until the shape gets closed. The objects are internally stored as a list of java.awt.Shape instances in the context and may be retrieved through the through the ScriptingContext.getObjectSearchShapes() convenience method. Besides the raw shape data the method also stores bounding rectangle of each object into the context in form of four variables _OBJECT_X_[n], _OBJECT_Y_[n], _OBJECT_W_[n] and _OBJECT_H_[n] which represent the top left corner [x,y] coordinates, width and height. The [n] expression is the object ordinary number starting from 1. The number of objects available is stored under the _OBJECT_COUNT variable. These variables are the only data exposed to the standard scripting language.

Parameters:
template - an optional template image to filter the list of objects by (an Image instance). It must contain just one shape of the specified color and/or tolerance in any level of rotation. When it is provided, the list of objects will be filtered to leave just shapes which are similar to the template image shape up to the ratio specified by the 'passrate' parameter. If the 'rotations' parameter is also specified and is greater than 1, the object list will be matched against the list of template shapes rotated the specified number of times. If the template image is not specified, the algorithm locates all objects matching the color parameters regardless of their size or shape.
passRate - pass rate as percentage between 0 and 100. The pass rate makes sense only when the template is not null and specifies the percentage of acceptable pixel variance from the template image.
cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.
color - defines the object color.
bridgeColors - is optional list of additional admissible object colors. This allows to search for continuous objects which are expected to have other objects of known colors painted over them. Colors in this list are always compared using the exact RGB match and they do not work with the rgbTolerance parameter.
rgbTolerance - RGB tolerance value. It must be an integer number between 0 and 256. It indicates how much the Red, Green and Blue components of a pixel may differ at a maximum to consider the color be equivalent to the object color specified by the 'color' parameter. This value allows to deal with blurred images where the shapes are not formed by a solid color but rather a range of similar colors. Be however aware that the higher the tolerance value, the higher the probability of false shape detections is. In most scenarios the value should be in the [0, 100] range depending on the blurring level. If the parameter is not specified, it defaults to zero and the algorithm looks for solid color objects only.

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

rotations - makes only sense when a template image is provided. It defines rotation granularity. It basically says how many times to rotate the object extracted from the template for filtering purposes. For example, the value of 36 will rotate the shape in 10 degree steps. Obviously, a high number of rotations increases accuracy of recognition of rotated objects but decreases performance. Low rotation values may be compensated through lowering the 'passrate' parameter. This approach is somewhat better in terms of performance but raises the risk of wrong detection of objects similar enough to the template one.
clear - optional boolean flag dealing with result highlighting in the GUI. The clear parameter allows to clear up all drawings created by the previously called object searches. The drawings are also automatically reset when the script finishes.
draw - optional boolean flag dealing with result highlighting in the GUI. When the draw parameter is 'true', the algorithm draws the object rectangles over the desktop image in the desktop viewer GUI component.
interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).
timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition (positive image comparison result) is met.
wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).
Returns:
command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a positive result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes, 1 when it fails and 2 when one or more template images are not found or cannot be read.
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMatch

public int waitForMatch(java.io.File[] templates,
                        float passRate,
                        java.lang.String method,
                        java.awt.Rectangle cmpArea,
                        java.lang.String timeout,
                        java.lang.String wait)
                 throws java.io.IOException
Throws:
java.io.IOException

waitForMatch

public int waitForMatch(java.io.File[] templates,
                        float passRate,
                        java.lang.String method,
                        java.lang.String timeout)
                 throws java.io.IOException
Throws:
java.io.IOException

waitForMatch

public int waitForMatch(java.io.File[] templates,
                        java.lang.String method,
                        java.lang.String timeout)
                 throws java.io.IOException
Throws:
java.io.IOException

waitForMatch

public int waitForMatch(java.io.File[] templates,
                        java.lang.String timeout)
                 throws java.io.IOException
Throws:
java.io.IOException

waitForMatch

public int waitForMatch(java.io.File[] templates)
                 throws java.io.IOException

Pause the script indefinitely until the default image comparison method produces a positive result for at least one of the template. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.io.File[], java.lang.String, java.lang.String, float, java.awt.Rectangle) one save that it performs image comparison repeatedly at scheduled intervals until either a match is achieved.

This particular method deals with template images in form of java.io.File array and sticks to the "default" for histogram based comparison with the default pass rate of 95%.

Parameters:
templates - list of template images (File instances).
Returns:
command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a positive result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes, 1 when it fails and 2 when one or more template images are not found or cannot be read.
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMismatch

public int waitForMismatch(java.awt.Image[] templates,
                           float passRate,
                           java.lang.String interval,
                           java.awt.Rectangle cmpArea,
                           java.lang.String timeout,
                           boolean removeBg,
                           java.lang.String bgColor,
                           java.lang.Integer minAlpha,
                           java.lang.Integer rgbTolerance,
                           java.lang.String wait)
                    throws java.io.IOException

Pause the script as long as the specified image comparison method produces a positive result for at least one of the templates or until the time out limit is reached. In plain words the method allows to wait until the desktop changes enough to produce a mismatch with the specified template image or images. It provides access to functionality of the WaitFor mismatch scripting language command. The method behaves like the compareTo(java.awt.Image[], com.tplan.robot.imagecomparison.ImageComparisonModule, float, java.awt.Rectangle, java.lang.Boolean, java.awt.Color, java.lang.Integer) one save that it performs image comparison repeatedly at scheduled intervals until either a mismatch or timeout is achieved.

This particular method deals with template images in form of java.awt.Image array. It is also hard coded to the image search algorithm (code "search") and supports its specific template background filtering parameters removebg, bgcolor and minalpha.

Parameters:
templates - list of template images (Image instances).
passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching). To use the default pass rate defined for the particular image comparison method set the value to a negative number.
interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).
cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.
timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition (negative image comparison result) is met.
removeBg -

set on/off filtering of background color. It is a new 2.1 feature allowing to search for objects on varying background. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). The background filter is applied only to completely opaque template images which do not contain any translucent or transparent pixels introduced through third party image editors. When an existing translucency is detected the filter is switched off silently and only the eventual minAlpha parameter is applied.

The default value is null (equivalent to "false") meaning that background filtering is off. See the Compareto documentation for details.

bgColor - optional color for the background filter. The parameter is ignored when background filtering is off. If the color is not specified (is null), the background filter will use color of the very first image pixel at [0,0] (upper left image corner).
minAlpha - translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing translucent pixels. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). Alpha is a pixel color component between 0 (transparent) and 255 (opaque) which defines the level of pixel translucency. The default minalpha value of null or -1 (internally equal to 255) instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Other values between 0 and 254 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit. Comparison of such pixels is based on color similarity with a fixed threshold.
rgbTolerance - RGB tolerance value. This parameter may be populated only for "search" image comparison algorithm. It is a number between 0 and 100 and it specifies tolerance to color changes on the level of individual pixel R, G, B components. A value of 20 for example makes the search robust against color changes where any of the R, G, B components varies by 20 or less from the template image pixels. It is recommended to use higher values of this parameter or even the limit one of 100 for testing of environments with varying images (for example in Flash or Flex ones). To get best results it is also recommended avoid mixing of the RGB tolerance parameter with other tolerance mechanisms such as pass rate (should be set to 100%) and background filtering (should be off).

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).
Returns:
command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a negative result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes (fails for mismatch), 1 when it fails (passes for mismatch and 2 when one or more template images are not found or cannot be read.
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMismatch

public int waitForMismatch(java.io.File[] templates,
                           float passRate,
                           java.lang.String interval,
                           java.awt.Rectangle cmpArea,
                           java.lang.String timeout,
                           java.lang.String sort,
                           float[] scale,
                           java.lang.String wait)
                    throws java.io.IOException

Pause the script as long as the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.io.File[], float, java.awt.Rectangle, boolean, java.lang.String, java.lang.Integer) one save that it performs image comparison repeatedly at scheduled intervals until either a match or timeout is achieved.

This particular method deals with template images in form of java.io.File array. It is also hard coded to the Enterprise Image Search v2 algorithm (code "search2") and it supports its specific parameter of order.

Parameters:
templates - list of template images (Image instances).
passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching). To use the default pass rate defined for the particular image comparison method set the value to a negative number.
interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).
cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.
timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition (positive image comparison result) is met.
sort - the sort order for the resulting match locations (Point/Rectangle). Supported modes:
  • "best" - Put the best matching location first (default mode).
  • "none" - Don't sort and leave the results in their natural "reading" order (left to right, top to bottom). This mode will produce the same order as the legacy "search" method.
  • "top" - Sort locations from the top to the bottom (topmost first).
  • "bottom" - Sort locations from the bottom to the top (bottommost first).
  • "left" - Sort locations from the left to the right (leftmost first).
  • "right" - Sort locations from the right to the left (rightmost first).
When the argument is null the sort mode defaults to the "best" one.
scale - allows to search for scaled instances of the input image (supported since 4.0). To set off scaling use the value of 0 (ignore) or 1 (use original size). When the value is greater than zero it is being handled as a scale ratio. For example, the value of 2.0 will search for the component whose width and height are magnified twice.

There are two negative constants which can be specified to employ dynamic scaling. They will scale the input image(s) with regard to the difference between the current desktop resolution and size of the desktop the template (component) image was created from. As Robot 3.x and older did not save the desktop resolution to the template meta data, the image must be created or updated with Robot 4.0 to enable this operation. The supported scale modes are:

  • -1 ("stretch mode") will scale the input image following the desktop width and height changes independently. The resulting image may or may not have the same width and height proportions (the width/height ratio).
  • -2 ("proportional scale mode") will pick up the smaller relative change of the desktop width and height and use it for both width and height scaling. The resulting image will have the the same proportions (the width/height ratio).
Returns:
command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a positive result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes, 1 when it fails and 2 when one or more template images are not found or cannot be read.
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMismatch

public int waitForMismatch(java.io.File[] templates,
                           float passRate,
                           java.lang.String interval,
                           java.awt.Rectangle cmpArea,
                           java.lang.String timeout,
                           java.lang.String sort,
                           java.lang.String wait)
                    throws java.io.IOException

Pause the script as long as the specified image comparison method produces a positive result for at least one of the template or until the time out limit is reached. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.io.File[], float, java.awt.Rectangle, boolean, java.lang.String, java.lang.Integer) one save that it performs image comparison repeatedly at scheduled intervals until either a match or timeout is achieved.

This particular method deals with template images in form of java.io.File array. It is also hard coded to the Enterprise Image Search v2 algorithm (code "search2") and it supports its specific parameter of order.

Parameters:
templates - list of template images (Image instances).
passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching). To use the default pass rate defined for the particular image comparison method set the value to a negative number.
interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).
cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.
timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition (positive image comparison result) is met.
sort - the sort order for the resulting match locations (Point/Rectangle). Supported modes:
  • "best" - Put the best matching location first (default mode).
  • "none" - Don't sort and leave the results in their natural "reading" order (left to right, top to bottom). This mode will produce the same order as the legacy "search" method.
  • "top" - Sort locations from the top to the bottom (topmost first).
  • "bottom" - Sort locations from the bottom to the top (bottommost first).
  • "left" - Sort locations from the left to the right (leftmost first).
  • "right" - Sort locations from the right to the left (rightmost first).
When the argument is null the sort mode defaults to the "best" one.
Returns:
command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a positive result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes, 1 when it fails and 2 when one or more template images are not found or cannot be read.
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMismatch

public int waitForMismatch(java.io.File template,
                           float passRate,
                           java.lang.String interval,
                           java.awt.Rectangle cmpArea,
                           java.lang.String timeout,
                           java.awt.Color color,
                           java.awt.Color[] bridgeColors,
                           java.lang.Integer rgbTolerance,
                           java.lang.Integer rotations,
                           java.lang.Boolean draw,
                           java.lang.Boolean clear,
                           java.lang.String wait)
                    throws java.io.IOException

Pause the script as long as the current remote desktop contains at least one object located by the Object Search image comparison method. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.io.File, java.lang.Float, java.awt.Rectangle, java.awt.Color, java.awt.Color[], java.lang.Integer, java.lang.Integer, java.lang.Boolean, java.lang.Boolean) one save that it performs image comparison repeatedly at scheduled intervals until either a mismatch or timeout is achieved.

The Object Search module searches the desktop image or its rectangular part for objects of a particular color or colors within the tolerated RGB variance. It also allows to filter the object list by an optional template image with detection of eventual object rotation. The method was designed to handle simple image analysis tasks such as "find all black triangles in any level of rotation on the screen".

As the method always locates the largest possible object and it doesn't search recursively for any other ones it may contain, this approach is not suitable for classic GUI components which are often framed, overlayed and merged together. The method however performs very well in testing of schemes, maps and images with low color scenes generated for example by Geographic Information System (GIS) applications or systems producing simple image data. The method can be also employed to check whether an object of a certain color or color range is present on the screen, for example to answer a question like "is there any red message in this particular area?".

The algorithm first scans the image for the first pixel which meets the input color criteria. Than it follows the outer shape of each such an object until the shape gets closed. The objects are internally stored as a list of java.awt.Shape instances in the context and may be retrieved through the through the ScriptingContext.getObjectSearchShapes() convenience method. Besides the raw shape data the method also stores bounding rectangle of each object into the context in form of four variables _OBJECT_X_[n], _OBJECT_Y_[n], _OBJECT_W_[n] and _OBJECT_H_[n] which represent the top left corner [x,y] coordinates, width and height. The [n] expression is the object ordinary number starting from 1. The number of objects available is stored under the _OBJECT_COUNT variable. These variables are the only data exposed to the standard scripting language.

Parameters:
template - an optional template image to filter the list of objects by (a File instance). It must contain just one shape of the specified color and/or tolerance in any level of rotation. When it is provided, the list of objects will be filtered to leave just shapes which are similar to the template image shape up to the ratio specified by the 'passrate' parameter. If the 'rotations' parameter is also specified and is greater than 1, the object list will be matched against the list of template shapes rotated the specified number of times. If the template image is not specified, the algorithm locates all objects matching the color parameters regardless of their size or shape.
passRate - pass rate as percentage between 0 and 100. The pass rate makes sense only when the template is not null and specifies the percentage of acceptable pixel variance from the template image.
cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.
color - defines the object color.
bridgeColors - is optional list of additional admissible object colors. This allows to search for continuous objects which are expected to have other objects of known colors painted over them. Colors in this list are always compared using the exact RGB match and they do not work with the rgbTolerance parameter.
rgbTolerance - RGB tolerance value. It must be an integer number between 0 and 256. It indicates how much the Red, Green and Blue components of a pixel may differ at a maximum to consider the color be equivalent to the object color specified by the 'color' parameter. This value allows to deal with blurred images where the shapes are not formed by a solid color but rather a range of similar colors. Be however aware that the higher the tolerance value, the higher the probability of false shape detections is. In most scenarios the value should be in the [0, 100] range depending on the blurring level. If the parameter is not specified, it defaults to zero and the algorithm looks for solid color objects only.

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

rotations - makes only sense when a template image is provided. It defines rotation granularity. It basically says how many times to rotate the object extracted from the template for filtering purposes. For example, the value of 36 will rotate the shape in 10 degree steps. Obviously, a high number of rotations increases accuracy of recognition of rotated objects but decreases performance. Low rotation values may be compensated through lowering the 'passrate' parameter. This approach is somewhat better in terms of performance but raises the risk of wrong detection of objects similar enough to the template one.
clear - optional boolean flag dealing with result highlighting in the GUI. The clear parameter allows to clear up all drawings created by the previously called object searches. The drawings are also automatically reset when the script finishes.
draw - optional boolean flag dealing with result highlighting in the GUI. When the draw parameter is 'true', the algorithm draws the object rectangles over the desktop image in the desktop viewer GUI component.
interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).
timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition (positive image comparison result) is met.
wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).
Returns:
command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a positive result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes, 1 when it fails and 2 when one or more template images are not found or cannot be read.
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMismatch

public int waitForMismatch(java.awt.Image template,
                           float passRate,
                           java.lang.String interval,
                           java.awt.Rectangle cmpArea,
                           java.lang.String timeout,
                           java.awt.Color color,
                           java.awt.Color[] bridgeColors,
                           java.lang.Integer rgbTolerance,
                           java.lang.Integer rotations,
                           java.lang.Boolean draw,
                           java.lang.Boolean clear,
                           java.lang.String wait)
                    throws java.io.IOException

Pause the script as long as the current remote desktop contains at least one object located by the Object Search image comparison method. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.awt.Image, java.lang.Float, java.awt.Rectangle, java.awt.Color, java.awt.Color[], java.lang.Integer, java.lang.Integer, java.lang.Boolean, java.lang.Boolean) one save that it performs image comparison repeatedly at scheduled intervals until either a mismatch or timeout is achieved.

The Object Search module searches the desktop image or its rectangular part for objects of a particular color or colors within the tolerated RGB variance. It also allows to filter the object list by an optional template image with detection of eventual object rotation. The method was designed to handle simple image analysis tasks such as "find all black triangles in any level of rotation on the screen".

As the method always locates the largest possible object and it doesn't search recursively for any other ones it may contain, this approach is not suitable for classic GUI components which are often framed, overlayed and merged together. The method however performs very well in testing of schemes, maps and images with low color scenes generated for example by Geographic Information System (GIS) applications or systems producing simple image data. The method can be also employed to check whether an object of a certain color or color range is present on the screen, for example to answer a question like "is there any red message in this particular area?".

The algorithm first scans the image for the first pixel which meets the input color criteria. Than it follows the outer shape of each such an object until the shape gets closed. The objects are internally stored as a list of java.awt.Shape instances in the context and may be retrieved through the through the ScriptingContext.getObjectSearchShapes() convenience method. Besides the raw shape data the method also stores bounding rectangle of each object into the context in form of four variables _OBJECT_X_[n], _OBJECT_Y_[n], _OBJECT_W_[n] and _OBJECT_H_[n] which represent the top left corner [x,y] coordinates, width and height. The [n] expression is the object ordinary number starting from 1. The number of objects available is stored under the _OBJECT_COUNT variable. These variables are the only data exposed to the standard scripting language.

Parameters:
template - an optional template image to filter the list of objects by (an Image instance). It must contain just one shape of the specified color and/or tolerance in any level of rotation. When it is provided, the list of objects will be filtered to leave just shapes which are similar to the template image shape up to the ratio specified by the 'passrate' parameter. If the 'rotations' parameter is also specified and is greater than 1, the object list will be matched against the list of template shapes rotated the specified number of times. If the template image is not specified, the algorithm locates all objects matching the color parameters regardless of their size or shape.
passRate - pass rate as percentage between 0 and 100. The pass rate makes sense only when the template is not null and specifies the percentage of acceptable pixel variance from the template image.
cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.
color - defines the object color.
bridgeColors - is optional list of additional admissible object colors. This allows to search for continuous objects which are expected to have other objects of known colors painted over them. Colors in this list are always compared using the exact RGB match and they do not work with the rgbTolerance parameter.
rgbTolerance - RGB tolerance value. It must be an integer number between 0 and 256. It indicates how much the Red, Green and Blue components of a pixel may differ at a maximum to consider the color be equivalent to the object color specified by the 'color' parameter. This value allows to deal with blurred images where the shapes are not formed by a solid color but rather a range of similar colors. Be however aware that the higher the tolerance value, the higher the probability of false shape detections is. In most scenarios the value should be in the [0, 100] range depending on the blurring level. If the parameter is not specified, it defaults to zero and the algorithm looks for solid color objects only.

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

rotations - makes only sense when a template image is provided. It defines rotation granularity. It basically says how many times to rotate the object extracted from the template for filtering purposes. For example, the value of 36 will rotate the shape in 10 degree steps. Obviously, a high number of rotations increases accuracy of recognition of rotated objects but decreases performance. Low rotation values may be compensated through lowering the 'passrate' parameter. This approach is somewhat better in terms of performance but raises the risk of wrong detection of objects similar enough to the template one.
clear - optional boolean flag dealing with result highlighting in the GUI. The clear parameter allows to clear up all drawings created by the previously called object searches. The drawings are also automatically reset when the script finishes.
draw - optional boolean flag dealing with result highlighting in the GUI. When the draw parameter is 'true', the algorithm draws the object rectangles over the desktop image in the desktop viewer GUI component.
interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).
timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition (positive image comparison result) is met.
wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).
Returns:
command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a positive result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes, 1 when it fails and 2 when one or more template images are not found or cannot be read.
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMismatch

public int waitForMismatch(java.lang.String interval,
                           java.awt.Rectangle cmpArea,
                           java.lang.String timeout,
                           java.lang.String language,
                           java.lang.String text,
                           java.lang.String pattern,
                           java.lang.String wait)
                    throws java.io.IOException

Pause the script as long as the text recognized through Tesseract OCR contains a string or matches a regular expression or until the time out limit is reached. It provides access to functionality of the WaitFor mismatch scripting language command. The method behaves like the compareTo(java.awt.Rectangle, java.lang.String, java.lang.String, java.lang.String) one save that it performs image comparison repeatedly at scheduled intervals until either a mismatch or timeout is achieved.

See the TesseractOCR class documentation for details on how to install and configure Tesseract. Additional information is available in description of the corresponding waitForMatch(java.lang.String, java.awt.Rectangle, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String) method.

Parameters:
interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).
cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.
timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition (positive image comparison result) is met.
wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).
language - target language (optional). It must be the 3-char lower case code of a properly installed Tesseract language data file set. For example, English code is "eng", German is "deu", Spanish is "spa" etc. This parameter will be passed as value of the "-l" argument to the engine. See the Tesseract's download page for the list of supported language files.
text - a string to look for in the recognized text (optional). If the parameter is specified (not null), the 'pattern' parameter must be null. If the string is found in the text resulting from OCR, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.
pattern - a Pattern compatible regular expression to match against the recognized text (optional). If the parameter is specified (not null), the 'text' parameter must be null. If the text resulting from OCR matches the regular expression, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.
Returns:
command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a positive result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes, 1 when it fails and 2 when one or more template images are not found or cannot be read.
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMismatch

public int waitForMismatch(java.lang.String interval,
                           java.awt.Rectangle cmpArea,
                           java.lang.String timeout,
                           java.lang.String language,
                           float scale,
                           java.lang.String text,
                           int distance,
                           java.lang.String pattern,
                           java.lang.String wait)
                    throws java.io.IOException

Pause the script as long as the text recognized through Tesseract OCR contains a string or matches a regular expression or until the time out limit is reached. It provides access to functionality of the WaitFor mismatch scripting language command. The method behaves like the compareTo(java.awt.Rectangle, java.lang.String, java.lang.String, java.lang.String) one save that it performs image comparison repeatedly at scheduled intervals until either a mismatch or timeout is achieved.

See the TesseractOCR class documentation for details on how to install and configure Tesseract. Additional information is available in description of the corresponding waitForMatch(java.lang.String, java.awt.Rectangle, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String) method.

Parameters:
interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).
cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the OCR will be performed on the full desktop image.
language - target language (optional). It must be the 3-char lower case code of a properly installed Tesseract language data file set. For example, English code is "eng", German is "deu", Spanish is "spa" etc. This parameter will be passed as value of the "-l" argument to the engine. See the Tesseract's download page for the list of supported language files. If the parameter is null, it will default to the English one ("eng").
scale - magnification factor. The method magnifies (enlarges) the image by the given factor to improve OCR accuracy. If this parameter is set to a value below 0, it defaults to the value configured in the Tesseract OCR Plugin preferences (the factory setting is 2 meaning that the image shall be enlarged to 200% of its original size).
text - a string to look for in the recognized text (optional). If the parameter is specified (not null), the 'pattern' parameter must be null. If the string is found in the text resulting from OCR, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.
distance - fuzzy string matching factor applied to comparison of the recognized text with value of the 'text' parameter. The distance is an integer based on the Levenshtein distance. It is defined as the minimum number of edits needed to transform one string into the other, with the allowable edit operations being insertion, deletion, or substitution of a single character. This metric is exposed as a new parameter called 'distance' which is an integer number specifying how many characters may be omitted or not recognized properly at a maximum to consider the sample text provided in the 'text' parameter equivalent. The default value of this parameter is 0 which will force exact comparison with the specified text.

Unlike the regular expressions the 'distance' parameter always searches the recognized text for any occurrence of a string matching the given text and distance. There's no need to specify that the string is preceded or trailed by another text. For example, the parameters of distance=1 and test=Apple will produce positive comparison result against recognized text of "The apple is red" because the text contains the word "apple" which may be converted to "Apple" in one character substitution.

pattern - a Pattern compatible regular expression to match against the recognized text (optional). If the parameter is specified (not null), the 'text' parameter must be null. If the text resulting from OCR matches the regular expression, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.
Returns:
command exit code as is specified in the Waitfor specification. The method returns 0 (zero) when the OCR was performed successfully. If either the 'pattern' or 'text' are specified, the method returns 0 when the recognized text matches the given text/regular expression or 1 otherwise..
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMismatch

public int waitForMismatch(java.lang.String interval,
                           java.awt.Rectangle cmpArea,
                           java.lang.String timeout,
                           java.lang.String language,
                           float scale,
                           java.lang.String text,
                           int distance,
                           java.lang.String pattern,
                           int mode,
                           int filter,
                           int fontSize,
                           java.lang.String wait)
                    throws java.io.IOException

Pause the script as long as the text recognized through Tesseract OCR contains a string or matches a regular expression or until the time out limit is reached. It provides access to functionality of the WaitFor mismatch scripting language command. The method behaves like the compareTo(java.awt.Rectangle, java.lang.String, java.lang.String, java.lang.String) one save that it performs image comparison repeatedly at scheduled intervals until either a mismatch or timeout is achieved.

See the TesseractOCR class documentation for details on how to install and configure Tesseract. Additional information is available in description of the corresponding waitForMatch(java.lang.String, java.awt.Rectangle, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String) method.

Parameters:
interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).
cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the OCR will be performed on the full desktop image.
language - target language (optional). It must be the 3-char lower case code of a properly installed Tesseract language data file set. For example, English code is "eng", German is "deu", Spanish is "spa" etc. This parameter will be passed as value of the "-l" argument to the engine. See the Tesseract's download page for the list of supported language files. If the parameter is null, it will default to the English one ("eng").
scale - magnification factor. The method magnifies (enlarges) the image by the given factor to improve OCR accuracy. If this parameter is set to a value below 0, it defaults to the value configured in the Tesseract OCR Plugin preferences (the factory setting is 2 meaning that the image shall be enlarged to 200% of its original size).
text - a string to look for in the recognized text (optional). If the parameter is specified (not null), the 'pattern' parameter must be null. If the string is found in the text resulting from OCR, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.
distance - fuzzy string matching factor applied to comparison of the recognized text with value of the 'text' parameter. The distance is an integer based on the Levenshtein distance. It is defined as the minimum number of edits needed to transform one string into the other, with the allowable edit operations being insertion, deletion, or substitution of a single character. This metric is exposed as a new parameter called 'distance' which is an integer number specifying how many characters may be omitted or not recognized properly at a maximum to consider the sample text provided in the 'text' parameter equivalent. The default value of this parameter is 0 which will force exact comparison with the specified text.

Unlike the regular expressions the 'distance' parameter always searches the recognized text for any occurrence of a string matching the given text and distance. There's no need to specify that the string is preceded or trailed by another text. For example, the parameters of distance=1 and test=Apple will produce positive comparison result against recognized text of "The apple is red" because the text contains the word "apple" which may be converted to "Apple" in one character substitution.

pattern - a Pattern compatible regular expression to match against the recognized text (optional). If the parameter is specified (not null), the 'text' parameter must be null. If the text resulting from OCR matches the regular expression, the method returns 0 to indicate success, otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.
mode - the OCR mode (since 3.5). It allows to modify the engine behavior in special cases to get better results. This parameter is optional. To leave the mode on default specify any value equal to or less than 1. The supported modes are:
  1. Default Tesseract mode (the value of 1). It is the Tesseract's default mode of automatic page segmentation with no OSD (the "-psm 3" CLI switch). This value is compatible with the Robot releases prior to 3.5.
  2. High accuracy (mode 2). This is a Robot enhancement which splits the text on the screen into lines and reapplies the OCR separately in the line mode (-psm 7). This approach is several times slower but typically delivers more accurate results, especially where the OCR is applied to a smaller screen area such as an application window.
  3. Treat the image as a single word (mode 8). Use this mode when the recognized text is up to 3 characters long. This is Tesseract's native mode driven through the "-psm 8" CLI switch.
filter - optional image filter code (since 3.5). It removes certain artifacts on the screen in order to improve the OCR accuracy. The filter should be applied selectively where the target screen or its part contains text of dark color in rectangular areas with solid color background, such as for example application windows with standard solid gray or white buttons, drop downs and other components. White or bright color text and rich color graphics such as images or photographs are not suitable for filtering. Usage of the filter in such scenes may damage the text and decrease the OCR accuracy.

The supported filter codes are:
  1. 0 - No filter (default).
  2. 1 - Remove artefacts. It will remove typical application components consisting of horizontal and vertical solid color lines (borders).
  3. 2 - Remove artefacts and underlines will remove components and single character underlines typical for application menus.
  4. 3 - Remove artefacts, underlines and dashed lines will remove components, underlines and any dashed line borders which typically mark a selected component or the one that currently owns the focus. The dash line pattern must be populated properly in the 'tocr' method preferences in order to get recognized and removed properly.
The filter is optional. To leave this parameter on default provide any value equal to or less than 0.
fontSize - an approximate font size of the text to be recognized (since 3.5). The default value is 15. It is used only when the image filter is on. It tells the filter not to remove artifacts that are smaller than or equal to the font size. When the value is much smaller than the actual font size the filter may cripple some of the characters. When the value is too large the filter will fail to remove certain artifacts (components) from the screen which may result in lower accuracy.

The font size is optional. To leave this parameter on default provide any value equal to or less than 0.
Returns:
command exit code as is specified in the Waitfor specification. The method returns 0 (zero) when the OCR was performed successfully. If either the 'pattern' or 'text' are specified, the method returns 0 when the recognized text matches the given text/regular expression or 1 otherwise..
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMismatch

public int waitForMismatch(java.io.File[] templates,
                           float passRate,
                           java.awt.Rectangle cmpArea,
                           java.lang.String interval,
                           java.lang.String timeout,
                           java.lang.String text,
                           int distance,
                           java.lang.String pattern,
                           java.lang.String wait)
                    throws java.io.IOException
Pause the script as long as the text recognized through the Image Based Text Recognition comparison method contains a string or matches a regular expression or until the time out limit is reached. It provides access to functionality of the WaitFor mismatch scripting language command. The method behaves like the compareTo(java.io.File[], float, java.awt.Rectangle, java.lang.String, int, java.lang.String) one save that it performs image comparison repeatedly at scheduled intervals until either a mismatch (negative comparison result) or timeout is achieved.

Recognize the text on the screen by a character image collection using . The method provides access to functionality of the Compareto scripting language command with the comparison method name fixed to "text" and support of its specific parameters.

The resulting text from the method is stored in form of individual text lines to _TEXT_LINE[line_number] variables into the context. The number of resulting text lines is available from the _TEXT_LINE_COUNT variable and can be retrieved using the getVariableAsInt("_TEXT_LINE_COUNT") method. The whole text including the new line characters as well as the map of text elements and their coordinates can be obtained directly from the context through the getContext().getRecognizedText(java.awt.Rectangle) and getContext().getRecognizedTextElements() methods.

If the method throws an error caused by misconfiguration or an I/O error, the method returns the value of 1. Text of the errors is made available through the _TEXT_ERROR variable.

Parameters:
cmpArea - a rectangle of the desktop image to restrict the image comparison to. If the argument is null, the recognition will be performed on the full desktop image.
text - a string to look for in the recognized text (optional). If the parameter is specified (not null), the 'pattern' parameter must be null. If the string is found in the recognized text the method returns 0 to indicate success. Otherwise it returns 1. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.
distance - fuzzy string matching factor applied to comparison of the recognized text with value of the 'text' parameter. The distance is an integer based on the Levenshtein distance. It is defined as the minimum number of edits needed to transform one string into the other, with the allowable edit operations being insertion, deletion, or substitution of a single character. This metric is exposed as a new parameter called 'distance' which is an integer number specifying how many characters may be omitted or not recognized properly at a maximum to consider the sample text provided in the 'text' parameter equivalent. The default value of this parameter is 0 which will force exact comparison with the specified text.

Unlike the regular expressions the 'distance' parameter always searches the recognized text for any occurrence of a string matching the given text and distance. There's no need to specify that the string is preceded or trailed by another text. For example, the parameters of distance=1 and test=Apple will produce positive comparison result against recognized text of "The apple is red" because the text contains the word "apple" which may be converted to "Apple" in one character substitution.

pattern - a Pattern compatible regular expression to match against the recognized text (optional). If the parameter is specified (not null), the 'text' parameter must be null. If the recognized text matches the regular expression, the method returns 0 to indicate success or 1 otherwise. If neither 'text' nor 'pattern' are specified, the method always returns 0 on successful OCR regardless of the resulting text.
Returns:
the exit code as is specified in the Image Based Text Recognition specification. When none of the "text", "distance" and "pattern" parameters is specified the method returns 0 (success) to indicate a successful execution even when no text gets actually recognized. If the text matching parameters are used the method will return either success (0) or fail (non-zero value) depending on whether the recognized text matches or not.
Throws:
java.io.IOException - on an I/O error (can't read an image file and/or can't get image of the remote desktop).

waitForMismatch

public int waitForMismatch(java.awt.Image[] templates,
                           float passRate,
                           java.lang.String interval,
                           java.awt.Rectangle cmpArea,
                           java.lang.String timeout,
                           boolean removeBg,
                           java.lang.String bgColor,
                           java.lang.Integer minAlpha,
                           java.lang.String wait)
                    throws java.io.IOException

Pause the script as long as the specified image comparison method produces a positive result for at least one of the templates or until the time out limit is reached. In plain words the method allows to wait until the desktop changes enough to produce a mismatch with the specified template image or images. It provides access to functionality of the WaitFor mismatch scripting language command. The method behaves like the compareTo(java.awt.Image[], com.tplan.robot.imagecomparison.ImageComparisonModule, float, java.awt.Rectangle, java.lang.Boolean, java.awt.Color, java.lang.Integer) one save that it performs image comparison repeatedly at scheduled intervals until either a mismatch or timeout is achieved.

This particular method deals with template images in form of java.awt.Image array. It is also hard coded to the image search algorithm (code "search") and supports its specific template background filtering parameters removebg, bgcolor and minalpha.

Parameters:
templates - list of template images (Image instances).
passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching). To use the default pass rate defined for the particular image comparison method set the value to a negative number.
interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).
cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.
timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition (negative image comparison result) is met.
removeBg -

set on/off filtering of background color. It is a new 2.1 feature allowing to search for objects on varying background. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). The background filter is applied only to completely opaque template images which do not contain any translucent or transparent pixels introduced through third party image editors. When an existing translucency is detected the filter is switched off silently and only the eventual minAlpha parameter is applied.

The default value is null (equivalent to "false") meaning that background filtering is off. See the Compareto documentation for details.

bgColor - optional color for the background filter. The parameter is ignored when background filtering is off. If the color is not specified (is null), the background filter will use color of the very first image pixel at [0,0] (upper left image corner).
minAlpha - translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing translucent pixels. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). Alpha is a pixel color component between 0 (transparent) and 255 (opaque) which defines the level of pixel translucency. The default minalpha value of null or -1 (internally equal to 255) instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Other values between 0 and 254 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit. Comparison of such pixels is based on color similarity with a fixed threshold.
wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).
Returns:
command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a negative result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes (fails for mismatch), 1 when it fails (passes for mismatch and 2 when one or more template images are not found or cannot be read.
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMismatch

public int waitForMismatch(java.awt.Image[] templates,
                           float passRate,
                           java.lang.String interval,
                           java.lang.String method,
                           java.lang.String methodParams,
                           java.awt.Rectangle cmpArea,
                           java.lang.String timeout,
                           java.lang.String wait)
                    throws java.io.IOException

Pause the script as long as the specified image comparison method produces a positive result for at least one of the templates or until the time out limit is reached. In plain words the method allows to wait until the desktop changes enough to produce a mismatch with the specified template image or images. It provides access to functionality of the WaitFor mismatch scripting language command. The method behaves like the compareTo(java.awt.Image[], com.tplan.robot.imagecomparison.ImageComparisonModule, float, java.awt.Rectangle) one save that it performs image comparison repeatedly at scheduled intervals until either a mismatch or timeout is achieved.

This particular method deals with template images in form of java.awt.Image array and allows to select the image comparison method ("search" for image search, "default" for histogram based comparison or eventually any other code of third party algorithm installed as a plug in).

Parameters:
templates - list of template images (Image instances).
passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching). To use the default pass rate defined for the particular image comparison method set the value to a negative number.
interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).
method - use "search" for image search, "default" for histogram based comparison or eventually any other code of third party algorithm installed as a plug in.
methodParams - use null for both the "default" and "search" methods. This is a legacy parameter intended to let custom plugins to receive specific parameters from a script.
cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.
timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition (positive image comparison result) is met.
wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).
Returns:
command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a negative result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes (fails for mismatch), 1 when it fails (passes for mismatch and 2 when one or more template images are not found or cannot be read.
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMismatch

public int waitForMismatch(java.io.File[] templates,
                           float passRate,
                           java.lang.String interval,
                           java.awt.Rectangle cmpArea,
                           java.lang.String timeout,
                           boolean removeBg,
                           java.lang.String bgColor,
                           java.lang.Integer minAlpha,
                           java.lang.Integer rgbTolerance,
                           java.lang.String wait)
                    throws java.io.IOException

Pause the script as long as the specified image comparison method produces a positive result for at least one of the templates or until the time out limit is reached. In plain words the method allows to wait until the desktop changes enough to produce a mismatch with the specified template image or images. It provides access to functionality of the WaitFor mismatch scripting language command. The method behaves like the compareTo(java.awt.Image[], com.tplan.robot.imagecomparison.ImageComparisonModule, float, java.awt.Rectangle, java.lang.Boolean, java.awt.Color, java.lang.Integer) one save that it performs image comparison repeatedly at scheduled intervals until either a mismatch or timeout is achieved.

This particular method deals with template images in form of java.awt.Image array. It is also hard coded to the image search algorithm (code "search") and supports its specific template background filtering parameters removebg, bgcolor and minalpha.

Parameters:
templates - list of template images (Image instances).
passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching). To use the default pass rate defined for the particular image comparison method set the value to a negative number.
interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).
cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.
timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition (negative image comparison result) is met.
removeBg -

set on/off filtering of background color. It is a new 2.1 feature allowing to search for objects on varying background. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). The background filter is applied only to completely opaque template images which do not contain any translucent or transparent pixels introduced through third party image editors. When an existing translucency is detected the filter is switched off silently and only the eventual minAlpha parameter is applied.

The default value is null (equivalent to "false") meaning that background filtering is off. See the Compareto documentation for details.

bgColor - optional color for the background filter. The parameter is ignored when background filtering is off. If the color is not specified (is null), the background filter will use color of the very first image pixel at [0,0] (upper left image corner).
minAlpha - translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing translucent pixels. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). Alpha is a pixel color component between 0 (transparent) and 255 (opaque) which defines the level of pixel translucency. The default minalpha value of null or -1 (internally equal to 255) instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Other values between 0 and 254 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit. Comparison of such pixels is based on color similarity with a fixed threshold.
rgbTolerance - RGB tolerance value. This parameter may be populated only for "search" image comparison algorithm. It is a number between 0 and 100 and it specifies tolerance to color changes on the level of individual pixel R, G, B components. A value of 20 for example makes the search robust against color changes where any of the R, G, B components varies by 20 or less from the template image pixels. It is recommended to use higher values of this parameter or even the limit one of 100 for testing of environments with varying images (for example in Flash or Flex ones). To get best results it is also recommended avoid mixing of the RGB tolerance parameter with other tolerance mechanisms such as pass rate (should be set to 100%) and background filtering (should be off).

The default value of RGB tolerance is zero meaning no tolerance. This default value may be modified in preferences of the image search plug in. See the Compareto documentation for details.

wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).
Returns:
command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a negative result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes (fails for mismatch), 1 when it fails (passes for mismatch and 2 when one or more template images are not found or cannot be read.
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMismatch

public int waitForMismatch(java.io.File[] templates,
                           float passRate,
                           java.lang.String interval,
                           java.awt.Rectangle cmpArea,
                           java.lang.String timeout,
                           boolean removeBg,
                           java.lang.String bgColor,
                           java.lang.Integer minAlpha,
                           java.lang.String wait)
                    throws java.io.IOException

Pause the script as long as the specified image comparison method produces a positive result for at least one of the templates or until the time out limit is reached. In plain words the method allows to wait until the desktop changes enough to produce a mismatch with the specified template image or images. It provides access to functionality of the WaitFor mismatch scripting language command. The method behaves like the compareTo(java.awt.Image[], com.tplan.robot.imagecomparison.ImageComparisonModule, float, java.awt.Rectangle, java.lang.Boolean, java.awt.Color, java.lang.Integer) one save that it performs image comparison repeatedly at scheduled intervals until either a mismatch or timeout is achieved.

This particular method deals with template images in form of java.awt.Image array. It is also hard coded to the image search algorithm (code "search") and supports its specific template background filtering parameters removebg, bgcolor and minalpha.

Parameters:
templates - list of template images (Image instances).
passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching). To use the default pass rate defined for the particular image comparison method set the value to a negative number.
interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).
cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.
timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition (negative image comparison result) is met.
removeBg -

set on/off filtering of background color. It is a new 2.1 feature allowing to search for objects on varying background. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). The background filter is applied only to completely opaque template images which do not contain any translucent or transparent pixels introduced through third party image editors. When an existing translucency is detected the filter is switched off silently and only the eventual minAlpha parameter is applied.

The default value is null (equivalent to "false") meaning that background filtering is off. See the Compareto documentation for details.

bgColor - optional color for the background filter. The parameter is ignored when background filtering is off. If the color is not specified (is null), the background filter will use color of the very first image pixel at [0,0] (upper left image corner).
minAlpha - translucency tolerance. It may be applied to images filtered through the removebg filter as well as to templates with already existing translucent pixels. This parameter may be only populated when the module argument is a "search" one (or eventually any other custom one supporting transparency features). Alpha is a pixel color component between 0 (transparent) and 255 (opaque) which defines the level of pixel translucency. The default minalpha value of null or -1 (internally equal to 255) instructs the search algorithm to compare just the fully opaque pixels and ignore all transparent or translucent (semi-transparent) ones. Other values between 0 and 254 will make the algorithm to compare even translucent pixels with the alpha component equal to or greater than the specified limit. Comparison of such pixels is based on color similarity with a fixed threshold.
wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).
Returns:
command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a negative result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes (fails for mismatch), 1 when it fails (passes for mismatch and 2 when one or more template images are not found or cannot be read.
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMismatch

public int waitForMismatch(java.io.File[] templates,
                           float passRate,
                           java.lang.String interval,
                           java.lang.String method,
                           java.lang.String methodParams,
                           java.awt.Rectangle cmpArea,
                           java.lang.String timeout,
                           java.lang.String wait)
                    throws java.io.IOException

Pause the script as long as the specified image comparison method produces a positive result for at least one of the templates or until the time out limit is reached. In plain words the method allows to wait until the desktop changes enough to produce a mismatch with the specified template image or images. It provides access to functionality of the WaitFor mismatch scripting language command. The method behaves like the compareTo(java.io.File[], java.lang.String, java.lang.String, float, java.awt.Rectangle) one save that it performs image comparison repeatedly at scheduled intervals until either a mismatch or timeout is achieved.

This particular method deals with template images in form of java.io.File array and allows to select the image comparison method ("search" for image search, "default" for histogram based comparison or eventually any other code of third party algorithm installed as a plug in).

Parameters:
templates - list of template images (Image instances).
passRate - pass rate as percentage between 0 and 100. The value of 100 indicates that exact match is required (100% matching). To use the default pass rate defined for the particular image comparison method set the value to a negative number.
interval - a time value specifying how often the desktop is to be compared. The method takes it more as a hint and schedules comparison intervals with regard to performance and eventual image updates. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null it defaults to the value set in the user configuration (usually 3 seconds).
method - use "search" for image search, "default" for histogram based comparison or eventually any other code of third party algorithm installed as a plug in.
methodParams - use null for both the "default" and "search" methods. This is a legacy parameter intended to let custom plugins to receive specific parameters from a script.
cmpArea - comparison area (sub rectangle) in the target image to apply the comparison to. If it is null the full image will be processed.
timeout - maximum time to pause for. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call). If the value is null the command will wait forever until the required condition (positive image comparison result) is met.
wait - how long to wait after the command finishes. The argument must be in format specified by the Time Values chapter of the language specification. Examples are "1" (a millisecond), "1s" (a second), "1m" (a minute), "1h" (an hour) and "1d" (a day). If the argument is null, there will be no delay and the test script proceeds immediately to the next command (method call).
Returns:
command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a negative result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic behavior of the compareTo() method which returns 0 (zero) when the comparison passes (fails for mismatch), 1 when it fails (passes for mismatch and 2 when one or more template images are not found or cannot be read.
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForMismatch

public int waitForMismatch(java.io.File[] templates,
                           float passRate,
                           java.lang.String method,
                           java.awt.Rectangle cmpArea,
                           java.lang.String timeout,
                           java.lang.String wait)
                    throws java.io.IOException
Throws:
java.io.IOException

waitForMismatch

public int waitForMismatch(java.io.File[] templates,
                           float passRate,
                           java.lang.String method,
                           java.lang.String timeout)
                    throws java.io.IOException
Throws:
java.io.IOException

waitForMismatch

public int waitForMismatch(java.io.File[] templates,
                           java.lang.String method,
                           java.lang.String timeout)
                    throws java.io.IOException
Throws:
java.io.IOException

waitForMismatch

public int waitForMismatch(java.io.File[] templates,
                           java.lang.String timeout)
                    throws java.io.IOException
Throws:
java.io.IOException

waitForMismatch

public int waitForMismatch(java.io.File[] templates)
                    throws java.io.IOException

Wait as long as at least one of the specified template images matches the screen. It provides access to functionality of the WaitFor match scripting language command. The method behaves like the compareTo(java.io.File[], java.lang.String, java.lang.String, float, java.awt.Rectangle) one save that it performs image comparison repeatedly at scheduled intervals until either a match is achieved.

This particular method deals with template images in form of java.io.File array and sticks to the "default" for histogram based comparison with the default pass rate of 95%.

Parameters:
templates - list of template images (File instances).
Returns:
command exit code as is specified in the Waitfor specification. The method generally returns 0 (zero) when the condition is met and image comparison produces a negative result. Non-zero value (usually 1) is returned when the timeout is reached. Both waitForMatch() and waitForMismatch() from this point of view mimic reverted behavior of the compareTo() method and returns 0 (zero) when the comparison fails or 2 when one or more template images are not found or cannot be read.
Throws:
java.io.IOException - on an I/O error, usually when the method can't get image of the remote desktop or an error is reported from the communication between the client and desktop server.

waitForClipboard

public int waitForClipboard(java.lang.String timeout,
                            java.lang.String wait)
                     throws java.io.IOException

Throws:
java.io.IOException

waitForClipboard

public int waitForClipboard(java.lang.String timeout)
                     throws java.io.IOException
Throws:
java.io.IOException

script

public int script(java.lang.String number,
                  boolean isEnd,
                  java.lang.String name)
           throws java.io.IOException

Define start or end of a script (test case). The method provides access to functionality of the Script scripting language command. It is an optional command intended to allow together with the Step command to create hierarchical structure of test results common in the QA industry. Any output objects and partial test step results enclosed by the script start and end definitions will be associated with the script number.

Parameters:
number - script number (mandatory). Though the parameter indicates that a numeric value is expected, it is intentionally a String to support any kind of ID required by the third party applications consuming the test results. The default T-Plan test management tools do require a numeric ID.
isEnd - false indicates script start, true script end.
name - optional script name to be displayed in the report.
Returns:
always returns 0.
Throws:
java.io.IOException - though the exception is declared, it should be never throws because the command doesn't interact with the desktop.

scriptStart

public int scriptStart(java.lang.String number,
                       java.lang.String name)
                throws java.io.IOException

Define start of a script (test case). The method provides access to functionality of the Script scripting language command. It is an optional command intended to allow together with the Step command to create hierarchical structure of test results common in the QA industry. Any output objects and partial test step results enclosed by the script start and end definitions will be associated with the script number.

Parameters:
number - script number (mandatory). Though the parameter indicates that a numeric value is expected, it is intentionally a String to support any kind of ID required by the third party applications consuming the test results. The default T-Plan test management tools do require a numeric ID.
name - optional script name to be displayed in the report.
Returns:
always returns 0.
Throws:
java.io.IOException - though the exception is declared, it should be never throws because the command doesn't interact with the desktop.

scriptStart

public int scriptStart(java.lang.String number)
                throws java.io.IOException

Define start of a script (test case). The method provides access to functionality of the Script scripting language command. It is an optional command intended to allow together with the Step command to create hierarchical structure of test results common in the QA industry. Any output objects and partial test step results enclosed by the script start and end definitions will be associated with the script number.

Parameters:
number - script number (mandatory). Though the parameter indicates that a numeric value is expected, it is intentionally a String to support any kind of ID required by the third party applications consuming the test results. The default T-Plan test management tools do require a numeric ID.
Returns:
always returns 0.
Throws:
java.io.IOException - though the exception is declared, it should be never throws because the command doesn't interact with the desktop.

scriptEnd

public int scriptEnd(java.lang.String number,
                     java.lang.String name)
              throws java.io.IOException

Define end of a script (test case). The method provides access to functionality of the Script scripting language command. It is an optional command intended to allow together with the Step command to create hierarchical structure of test results common in the QA industry. Any output objects and partial test step results enclosed by the script start and end definitions will be associated with the script number.

Parameters:
number - script number (mandatory). Though the parameter indicates that a numeric value is expected, it is intentionally a String to support any kind of ID required by the third party applications consuming the test results. The default T-Plan test management tools do require a numeric ID.
name - optional script name to be displayed in the report.
Returns:
always returns 0.
Throws:
java.io.IOException - though the exception is declared, it should be never throws because the command doesn't interact with the desktop.

scriptEnd

public int scriptEnd(java.lang.String number)
              throws java.io.IOException

Define end of a script (test case). The method provides access to functionality of the Script scripting language command. It is an optional command intended to allow together with the Step command to create hierarchical structure of test results common in the QA industry. Any output objects and partial test step results enclosed by the script start and end definitions will be associated with the script number.

Parameters:
number - script number (mandatory). Though the parameter indicates that a numeric value is expected, it is intentionally a String to support any kind of ID required by the third party applications consuming the test results. The default T-Plan test management tools do require a numeric ID.
Returns:
always returns 0.
Throws:
java.io.IOException - though the exception is declared, it should be never throws because the command doesn't interact with the desktop.

step

public int step(java.lang.String name,
                java.lang.String result,
                java.lang.String instructions,
                java.lang.String expected,
                java.lang.String actual,
                java.lang.String notes)
         throws java.io.IOException

Define result of a particular test step. The method provides access to functionality of the Step scripting language command.

Steps should be always defined inside of a script start and script end block. Though steps are identified by a name which should be unique, the command doesn't enforce it because some systems may identify steps uniquely by a name (or numeric code) and ordinary number in a script.

Parameters:
name - step name (ID). It is mandatory and may not be null.
result - step result. The command recognizes four test results defined by literal constants:
  • "pass"
  • "fail"
  • "nt" (a short for "not tested")
  • "na" (a short for "not available")
If the argument is null, the command defaults to "pass".
instructions - step instructions (optional). It is description of what the step does or how to get it accomplished (for example "Click button XYZ and wait for the new application window").
expected - represents optional description of expected result (for example "XYZ window pops up and is populated correctly").
actual - means actual result description (optional). It is typically used for failed steps to highlight the difference between the expected and actual results.
notes - optional additional information.
Returns:
always returns 0 (success).
Throws:
java.io.IOException - though the exception is declared, it should be never throws because the command doesn't interact with the desktop.

stepPassed

public int stepPassed(java.lang.String name,
                      java.lang.String instructions,
                      java.lang.String expected,
                      java.lang.String actual,
                      java.lang.String notes)
               throws java.io.IOException

Define a passed (successful) test step. The method provides access to functionality of the Step pass scripting language command.

Steps should be always defined inside of a script start and script end block. Though steps are identified by a name which should be unique, the command doesn't enforce it because some systems may identify steps uniquely by a name (or numeric code) and ordinary number in a script.

Parameters:
name - step name (ID). It is mandatory and may not be null.
instructions - step instructions (optional). It is description of what the step does or how to get it accomplished (for example "Click button XYZ and wait for the new application window").
expected - represents optional description of expected result (for example "XYZ window pops up and is populated correctly").
actual - means actual result description (optional). It is typically used for failed steps to highlight the difference between the expected and actual results.
notes - optional additional information.
Returns:
always returns 0 (success).
Throws:
java.io.IOException - though the exception is declared, it should be never throws because the command doesn't interact with the desktop.

stepPassed

public int stepPassed(java.lang.String name,
                      java.lang.String instructions)
               throws java.io.IOException

Define a passed (successful) test step. The method provides access to functionality of the Step pass scripting language command. This is just a convenience method omitting some of the optional parameters.

Steps should be always defined inside of a script start and script end block. Though steps are identified by a name which should be unique, the command doesn't enforce it because some systems may identify steps uniquely by a name (or numeric code) and ordinary number in a script.

Parameters:
name - step name (ID). It is mandatory and may not be null.
instructions - step instructions (optional). It is description of what the step does or how to get it accomplished (for example "Click button XYZ and wait for the new application window").
Returns:
always returns 0 (success).
Throws:
java.io.IOException - though the exception is declared, it should be never throws because the command doesn't interact with the desktop.

stepFailed

public int stepFailed(java.lang.String name,
                      java.lang.String instructions,
                      java.lang.String expected,
                      java.lang.String actual,
                      java.lang.String notes)
               throws java.io.IOException

Define a failed (unsuccessful) test step. The method provides access to functionality of the Step fail scripting language command.

Steps should be always defined inside of a script start and script end block. Though steps are identified by a name which should be unique, the command doesn't enforce it because some systems may identify steps uniquely by a name (or numeric code) and ordinary number in a script.

Parameters:
name - step name (ID). It is mandatory and may not be null.
instructions - step instructions (optional). It is description of what the step does or how to get it accomplished (for example "Click button XYZ and wait for the new application window").
expected - represents optional description of expected result (for example "XYZ window pops up and is populated correctly").
actual - means actual result description (optional). It is typically used for failed steps to highlight the difference between the expected and actual results.
notes - optional additional information.
Returns:
always returns 0.
Throws:
java.io.IOException - though the exception is declared, it should be never throws because the command doesn't interact with the desktop.

stepFail

public int stepFail(java.lang.String name,
                    java.lang.String instructions)
             throws java.io.IOException

Define a failed (unsuccessful) test step. The method provides access to functionality of the Step fail scripting language command. This is just a convenience method omitting some of the optional parameters.

Steps should be always defined inside of a script start and script end block. Though steps are identified by a name which should be unique, the command doesn't enforce it because some systems may identify steps uniquely by a name (or numeric code) and ordinary number in a script.

Parameters:
name - step name (ID). It is mandatory and may not be null.
instructions - step instructions (optional). It is description of what the step does or how to get it accomplished (for example "Click button XYZ and wait for the new application window").
Returns:
always returns 0.
Throws:
java.io.IOException - though the exception is declared, it should be never throws because the command doesn't interact with the desktop.

stepNotTested

public int stepNotTested(java.lang.String name,
                         java.lang.String instructions,
                         java.lang.String expected,
                         java.lang.String actual,
                         java.lang.String notes)
                  throws java.io.IOException

Define a test step which was not (yet) tested. The method provides access to functionality of the Step fail scripting language command.

Steps should be always defined inside of a script start and script end block. Though steps are identified by a name which should be unique, the command doesn't enforce it because some systems may identify steps uniquely by a name (or numeric code) and ordinary number in a script.

Parameters:
name - step name (ID). It is mandatory and may not be null.
instructions - step instructions (optional). It is description of what the step does or how to get it accomplished (for example "Click button XYZ and wait for the new application window").
expected - represents optional description of expected result (for example "XYZ window pops up and is populated correctly").
actual - means actual result description (optional). It is typically used for failed steps to highlight the difference between the expected and actual results.
notes - optional additional information.
Returns:
always returns 0.
Throws:
java.io.IOException - though the exception is declared, it should be never throws because the command doesn't interact with the desktop.

stepNotAvailable

public int stepNotAvailable(java.lang.String name,
                            java.lang.String instructions,
                            java.lang.String expected,
                            java.lang.String actual,
                            java.lang.String notes)
                     throws java.io.IOException

Define a test step whose result is not available. The method provides access to functionality of the Step na scripting language command.

Steps should be always defined inside of a script start and script end block. Though steps are identified by a name which should be unique, the command doesn't enforce it because some systems may identify steps uniquely by a name (or numeric code) and ordinary number in a script.

Parameters:
name - step name (ID). It is mandatory and may not be null.
instructions - step instructions (optional). It is description of what the step does or how to get it accomplished (for example "Click button XYZ and wait for the new application window").
expected - represents optional description of expected result (for example "XYZ window pops up and is populated correctly").
actual - means actual result description (optional). It is typically used for failed steps to highlight the difference between the expected and actual results.
notes - optional additional information.
Returns:
always returns 0.
Throws:
java.io.IOException - though the exception is declared, it should be never throws because the command doesn't interact with the desktop.

excelOpen

public int excelOpen(java.io.File inputFile,
                     java.io.File outputFile,
                     java.lang.String sheet,
                     java.lang.String id)
              throws java.io.IOException

Open a Microsoft Excel file for reading and writing. The method provides access to functionality of the Excel open scripting language command.

Parameters:
inputFile - input file in the MS Excel format (.xls). Relative file paths are resolved against the script location.
outputFile - optional output file. If it is null, the input file is open in read/write mode and any changes applied to the document will be saved to the input file. If the output file is specified, it is always written even though there are no changes. This behavior may be suppressed by calling the excelClose() with the save parameter set to false.

Be aware that any changes are not written to the file unless the document is closed explicitly through the excelClose() method. Otherwise the underlying automation framework saves the file automatically when it receives a message of the script completion. This however doesn't apply to abnormal script terminations, for example when the test() method throws an exception. Design the method to handle all such errors and make sure the excelClose() method gets always called (for example in the "finally" block) to save your changes properly.

id - optional unique ID for the file. It has to be specified only when the script uses more than one Excel document at a time. Otherwise it may be null. Once the ID is specified, it must be used in all subsequent Excel command calls.
sheet - optional sheet to select. It may be specified either by sheet name or its ordinary number starting from 1. If the parameter is null the command opens by default the first sheet.
Returns:
command exit code as is specified in the Excel specification.
Throws:
java.io.IOException - is declared but rarely thrown because most possible I/O errors are being caught by the command handler and reported in form of return value (exit code).

excelOpen

public int excelOpen(java.io.File inputFile,
                     java.lang.String id)
              throws java.io.IOException

Open a Microsoft Excel file for reading and writing and select automatically the first sheet. The method provides access to functionality of the Excel open scripting language command.

Parameters:
inputFile - input file in the MS Excel format (.xls). Relative file paths are resolved against the script location.

Be aware that any changes are not written to the file unless the document is closed explicitly through the excelClose() method. Otherwise the underlying automation framework saves the file automatically when it receives a message of the script completion. This however doesn't apply to abnormal script terminations, for example when the test() method throws an exception. Design the method to handle all such errors and make sure the excelClose() method gets always called (for example in the "finally" block) to save your changes properly.

id - optional unique ID for the file. It has to be specified only when the script uses more than one Excel document at a time. Otherwise it may be null. Once the ID is specified, it must be used in all subsequent Excel command calls.
Returns:
command exit code as is specified in the Excel specification.
Throws:
java.io.IOException - is declared but rarely thrown because most possible I/O errors are being caught by the command handler and reported in form of return value (exit code).

excelOpen

public int excelOpen(java.io.InputStream inputStream,
                     java.io.OutputStream outputStream,
                     java.lang.String sheet,
                     java.lang.String id)
              throws java.io.IOException

Open a Microsoft Excel file. The method provides access to functionality of the Excel open scripting language command. This method allows to specify the I/O resources as streams. It is designed to allow loading of XSL bundled with the Java class and/or located in a directory known relatively to the script class. A typical code example loading the "data.xls" file just for reading from the same folder as the class:

 import com.tplan.robot.scripting.*;
 import java.io.*;

 public class MyTest extends DefaultJavaTestScript {

    public void test() {
       try {
          InputStream in = getClass().getResourceAsStream("data.xls");
          int exitCode = excelOpen(in, null, null, null);
       } catch (IOException ex) {
          ex.printStackTrace();
       }
    }
 }
 

Parameters:
inputStream - input stream to read the XLS file from. It may not be null.
outputStream - optional output stream to write the changes to. If it is not specified the document will be opened in a read only mode and any changes will be discarded when the document gets closed.
id - optional unique ID for the file. It has to be specified only when the script uses more than one Excel document at a time. Otherwise it may be null. Once the ID is specified, it must be used in all subsequent Excel command calls.
sheet - optional sheet to select. It may be specified either by sheet name or its ordinary number starting from 1. If the parameter is null the command opens by default the first sheet.
Returns:
command exit code as is specified in the Excel specification.
Throws:
java.io.IOException - is declared but rarely thrown because most possible I/O errors are being caught by the command handler and reported in form of return value (exit code).

excelCreate

public int excelCreate(java.io.File outputFile,
                       java.lang.String sheetName,
                       java.lang.String id)
                throws java.io.IOException

Create a new Microsoft Excel document for reading and writing. The method provides access to functionality of the Excel create scripting language command.

Parameters:
outputFile - mandatory output file. It is always created even though there are no changes. This behavior may be suppressed by calling the excelClose() with the save parameter set to false.

Be aware that the file is not physically created until the document is closed explicitly through the excelClose() method. The underlying automation framework also saves the file automatically when it receives a message of the script completion. This however doesn't apply to abnormal script terminations, for example when the test() method throws an exception. Design the method to handle all such errors and make sure the excelClose() method gets always called (for example in the "finally" block) to save your changes properly.

id - optional unique ID for the file. It has to be specified only when the script uses more than one Excel document at a time. Otherwise it may be null. Once the ID is specified, it must be used in all subsequent Excel command calls.
sheetName - optional name of the sheet to create and select. If the parameter is null the command creates a spread sheet with the default name of "Sheet1"..
Returns:
command exit code as is specified in the Excel specification.
Throws:
java.io.IOException - is declared but rarely thrown because most possible I/O errors are being caught by the command handler and reported in form of return value (exit code).

excelCreate

public int excelCreate(java.io.OutputStream outputStream,
                       java.lang.String sheetName,
                       java.lang.String id)
                throws java.io.IOException

Create a Microsoft Excel document and associate it with an output stream. The method provides access to functionality of the Excel create scripting language command.

Parameters:
outputStream - mandatory output stream to write the document to.
id - unique document ID specified when the document was opened or created. If the script works just with one Excel document and the ID was not specified, the parameter must be null.
sheetName - optional name of the sheet to create and select. If the parameter is null the command creates a spread sheet with the default name of "Sheet1"..
Returns:
command exit code as is specified in the Excel specification.
Throws:
java.io.IOException - is declared but rarely thrown because most possible I/O errors are being caught by the command handler and reported in form of return value (exit code).

excelCreate

public int excelCreate(java.lang.String sheetName,
                       java.lang.String id)
                throws java.io.IOException

Create and select a new sheet in the current or specified Excel document. The method provides access to functionality of the Excel create scripting language command.

Parameters:
id - unique document ID specified when the document was opened or created. If the script works just with one Excel document and the ID was not specified, the parameter must be null.
sheetName - optional name of the sheet to create and select. If the parameter is null the command creates a spread sheet with the default name of "Sheet1N" where "N" is the sheet ordinary number.
Returns:
command exit code as is specified in the Excel specification.
Throws:
java.io.IOException - is declared but rarely thrown because most possible I/O errors are being caught by the command handler and reported in form of return value (exit code).

excelClose

public int excelClose(java.lang.String id,
                      boolean save)
               throws java.io.IOException

Close and eventually save the specified Excel document. The method provides access to functionality of the Excel close scripting language command.

Parameters:
id - unique document ID specified when the document was opened or created. If the script works just with one Excel document and the ID was not specified at the time of opening or creation the parameter must be null.
save - true saves the file, false discards the changes.
Returns:
command exit code as is specified in the Excel specification.
Throws:
java.io.IOException - is declared but rarely thrown because most possible I/O errors are being caught by the command handler and reported in form of return value (exit code).

excelSelect

public int excelSelect(java.lang.String ref,
                       java.lang.String sheet,
                       boolean evaluate,
                       java.lang.String id)
                throws java.io.IOException

Select a cell and retrieve its value and type to the context variables. The method provides access to functionality of the Excel select scripting language command.

When the argument coordinates point to a valid cell, its value and type are saved to the context as _EXCEL_CELL_VALUE and _EXCEL_CELL_TYPE variables. These can be retrieved through the getContext().getVariable() method. Values are always String instances. Cell type is one of BLANK, BOOLEAN, ERROR, FORMULA, NUMERIC or STRING. As these constants are retrieved dynamically using Reflection API from the underlying Apache POI framework, there may be a different set of types if the library is updated or replaced with another version.

Parameters:
ref - Excel compatible cell reference, for example "A1" or "K10".
sheet - sheet to select the cell from. It may be either the sheet ordinary number starting from 1 (one) or the sheet name. This parameter is optional and if it is null the command will use the last selected sheet. If the parameter is specified the method updates context variables from the Sheet group.
evaluate - a flag controlling how FORMULA cells are handled. If it is "true" the cell value will be the the formula result. Otherwise the retrieved value will the formula text.
id - unique document ID specified when the document was opened or created. If the script works just with one Excel document and the ID was not specified at the time of opening or creation the parameter must be null.
Returns:
command exit code as is specified in the Excel specification.
Throws:
java.io.IOException - is declared but rarely thrown because most possible I/O errors are being caught by the command handler and reported in form of return value (exit code).

excelSelect

public int excelSelect(int row,
                       java.lang.String column,
                       java.lang.String sheet,
                       boolean evaluate,
                       java.lang.String id)
                throws java.io.IOException

Select a cell and retrieve its value and type to the context variables. The method provides access to functionality of the Excel select scripting language command.

When the argument coordinates point to a valid cell, its value and type are saved to the context as _EXCEL_CELL_VALUE and _EXCEL_CELL_TYPE variables. These can be retrieved through the getContext().getVariable() method. Values are always String instances. Cell type is one of BLANK, BOOLEAN, ERROR, FORMULA, NUMERIC or STRING. As these constants are retrieved dynamically using Reflection API from the underlying Apache POI framework, there may be a different set of types if the library is updated or replaced with another version.

Parameters:
row - cell row ordinary number starting from 1 (one).
column - cell column. It may be either column ordinary number starting from 1 (one) or Excel compatible column ID such as "A" or "AB".
sheet - sheet to select the cell from. It may be either the sheet ordinary number starting from 1 (one) or the sheet name. This parameter is optional and if it is null the command will use the last selected sheet. If the parameter is specified the method updates context variables from the Sheet group.
evaluate - a flag controlling how FORMULA cells are handled. If it is "true" the cell value will be the the formula result. Otherwise the retrieved value will the formula text.
id - unique document ID specified when the document was opened or created. If the script works just with one Excel document and the ID was not specified at the time of opening or creation the parameter must be null.
Returns:
command exit code as is specified in the Excel specification.
Throws:
java.io.IOException - is declared but rarely thrown because most possible I/O errors are being caught by the command handler and reported in form of return value (exit code).

excelSelect

public int excelSelect(java.lang.String ref,
                       boolean evaluate,
                       java.lang.String id)
                throws java.io.IOException

Select a cell from the current sheet and retrieve its value and type to the context variables. The method provides access to functionality of the Excel select scripting language command.

When the argument coordinates point to a valid cell, its value and type are saved to the context as _EXCEL_CELL_VALUE and _EXCEL_CELL_TYPE variables. These can be retrieved through the getContext().getVariable() method. Values are always String instances. Cell type is one of BLANK, BOOLEAN, ERROR, FORMULA, NUMERIC or STRING. As these constants are retrieved dynamically using Reflection API from the underlying Apache POI framework, there may be a different set of types if the library is updated or replaced with another version.

Parameters:
ref - Excel compatible cell reference, for example "A1" or "K10".
evaluate - a flag controlling how FORMULA cells are handled. If it is "true" the cell value will be the formula result. Otherwise the retrieved value will be the formula text.
id - unique document ID specified when the document was opened or created. If the script works just with one Excel document and the ID was not specified at the time of opening or creation the parameter must be null.
Returns:
command exit code as is specified in the Excel specification.
Throws:
java.io.IOException - is declared but rarely thrown because most possible I/O errors are being caught by the command handler and reported in form of return value (exit code).

excelSelect

public int excelSelect(int row,
                       java.lang.String column,
                       boolean evaluate,
                       java.lang.String id)
                throws java.io.IOException

Select a cell from the current sheet and retrieve its coordinates (row/column, reference), type and value to the context variables of _EXCEL_CELL_ROW, _EXCEL_CELL_COLUMN, _EXCEL_CELL_REF, _EXCEL_CELL_TYPE and _EXCEL_CELL_VALUE. The method provides access to functionality of the Excel select scripting language command.

When the argument coordinates point to a valid cell, its value and type are saved to the context as _EXCEL_CELL_VALUE and _EXCEL_CELL_TYPE variables. These can be retrieved through the getContext().getVariable() method. Values are always String instances. Cell type is one of BLANK, BOOLEAN, ERROR, FORMULA, NUMERIC or STRING. As these constants are retrieved dynamically using Reflection API from the underlying Apache POI framework, there may be a different set of types if the library is updated or replaced with another version.

Parameters:
row - cell row ordinary number starting from 1 (one).
column - cell column. It may be either column ordinary number starting from 1 (one) or Excel compatible column ID such as "A" or "AB".
evaluate - a flag controlling how FORMULA cells are handled. If it is "true" the cell value will be the formula result. Otherwise the retrieved value will be the formula text.
id - unique document ID specified when the document was opened or created. If the script works just with one Excel document and the ID was not specified at the time of opening or creation the parameter must be null.
Returns:
command exit code as is specified in the Excel specification.
Throws:
java.io.IOException - is declared but rarely thrown because most possible I/O errors are being caught by the command handler and reported in form of return value (exit code).

excelSelect

public int excelSelect(java.lang.String sheet,
                       java.lang.String id)
                throws java.io.IOException

Select (open) a sheet. The method provides access to functionality of the Excel select scripting language command.

Parameters:
sheet - sheet to select the cell from. It may be either the sheet ordinary