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:
.java file through File->Open Test Script
and select the Execute too bar button or menu item (manual execution),-r/--run CLI switch (automated execution).
To execute in CLI mode without GUI specify the -n switch as well.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:
Include C:\tests\MyTests.jar
Run testscript.MyJavaTestScript count=2 wait=500
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.
ExtendedParamsObject.getParameters() method during script compilation
and report a syntax error if an unknown parameter is specified.ExtendedParamsObject.getParameterValues(java.lang.String) method,
the editor will check if the parameter value is one of the expected ones and
reports a syntax error if not.ExtendedParamsObject.getVisualParameters() method, the
editor will check whether the parameter meets the specified type and any type
of declared limitations (numeric limit, mandatory, ...).Run command in the editor opens up a context
menu containing the Edit parameters menu item. When selected it opens a simple dialog
allowing to edit all the declared parameters.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:
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 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.
|
| Click command | Yes |
Provided through the clickImage(),
clickObject() and
clickText() methods and their variants.
|
| CompareTo command | Yes |
Provided through the compareTo() methods.
|
| Drag command | Yes |
Provided through the dragImage(),
dragObject() and
dragText() methods and their variants.
|
| 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:
mouseMove, mouseClick,
mouseDrag etc. Such methods usually represent a combination of a command
and one or more its parameters (for example, the mouseDoubleClick method
represent a "Mouse click button=left count=2" command).compareTo()
automatically look for 100% match if the passRate argument is set
to -1f.IOException is thrown only on when an unrecognized or unexpected
error happens in the communication between the desktop client and server. Don't be
surprised that some methods, for example connect(),
rather return an error code than throw an IOException in standard situations, such as
failure to connect to the server because it is down, authentication failure etc.IllegalArgumentException when one or more argument
values are invalid and/or if the corresponding command requires connection to a desktop
and the tool is in disconnected state. As this execption is unchecked,
it is not explicitly declared as thrown by the method.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-2022 T-Plan Limited. All rights reserved.
| Modifier and Type | Class and Description |
|---|---|
static interface |
DefaultJavaTestScript.Command |
static interface |
DefaultJavaTestScript.Param |
WRAPPER_TYPE_BLOCK, WRAPPER_TYPE_INCLUDE, WRAPPER_TYPE_JAVA, WRAPPER_TYPE_PROCEDURE, WRAPPER_TYPE_RUN, WRAPPER_TYPE_SCRIPT, WRAPPER_TYPE_UNKNOWN| Constructor and Description |
|---|
DefaultJavaTestScript() |
| Modifier and Type | Method and Description |
|---|---|
int |
alert(String text,
String title,
String buttons,
String timeout)
Display a local alert window.
|
int |
alert(String text,
String title,
String fields,
String values,
String buttons,
String timeout)
Display a local alert window.
|
int |
alert(String text,
String title,
String fields,
String values,
String buttons,
String timeout,
Point location,
Dimension size)
Display a local alert window.
|
int |
browserClose()
Close the currently opened browser.
|
int |
browserFind(String timeout,
String... attributes)
Find an element in the currently displayed Selenium driven web browser
by a set of tag attributes and apply an optional action to it.
|
int |
browserFindAndClear(int elementNumber,
String timeout,
boolean continueScript,
String... attributes)
Find an element in the currently displayed Selenium driven web browser
by a set of tag attributes and clear it.
|
int |
browserFindAndClear(int elementNumber,
String timeout,
String... attributes)
Find an element in the currently displayed Selenium driven web browser
by a set of tag attributes and clear it.
|
int |
browserFindAndClear(String... attributes)
Find an element in the currently displayed Selenium driven web browser
by a set of tag attributes and clear it.
|
int |
browserFindAndClick(int elementNumber,
String timeout,
boolean continueScript,
String... attributes)
Find an element in the currently displayed Selenium driven web browser
by a set of tag attributes and click it.
|
int |
browserFindAndClick(int elementNumber,
String timeout,
String... attributes)
Find an element in the currently displayed Selenium driven web browser
by a set of tag attributes and click it.
|
int |
browserFindAndClick(String... attributes)
Find an element in the currently displayed Selenium driven web browser
by a set of tag attributes and click it.
|
int |
browserFindAndSelectByIndex(int optionIndex,
int elementNumber,
String timeout,
boolean continueScript,
String... attributes)
Find a drop down in the currently displayed Selenium driven web browser
by a set of tag attributes and select the option of the specified index.
|
int |
browserFindAndSelectByIndex(int optionIndex,
int elementNumber,
String timeout,
String... attributes)
Find a drop down in the currently displayed Selenium driven web browser
by a set of tag attributes and select the option of the specified index.
|
int |
browserFindAndSelectByIndex(int optionIndex,
String... attributes)
Find a drop down in the currently displayed Selenium driven web browser
by a set of tag attributes and select the option of the specified index.
|
int |
browserFindAndSelectByText(String optionText,
int elementNumber,
String timeout,
boolean continueScript,
String... attributes)
Find a drop down in the currently displayed Selenium driven web browser
by a set of tag attributes and select the option of the specified text.
|
int |
browserFindAndSelectByText(String optionText,
int elementNumber,
String timeout,
String... attributes)
Find a drop down in the currently displayed Selenium driven web browser
by a set of tag attributes and select the option of the specified text.
|
int |
browserFindAndSelectByText(String optionText,
String... attributes)
Find a drop down in the currently displayed Selenium driven web browser
by a set of tag attributes and select the option of the specified text.
|
int |
browserFindAndSelectByValue(String optionValue,
int elementNumber,
String timeout,
boolean continueScript,
String... attributes)
Find a drop down in the currently displayed Selenium driven web browser
by a set of tag attributes and select the option of the specified value.
|
int |
browserFindAndSelectByValue(String optionValue,
int elementNumber,
String timeout,
String... attributes)
Find a drop down in the currently displayed Selenium driven web browser
by a set of tag attributes and select the option of the specified value.
|
int |
browserFindAndSelectByValue(String optionValue,
String... attributes)
Find a drop down in the currently displayed Selenium driven web browser
by a set of tag attributes and select the option of the specified value.
|
int |
browserFindAndSubmit(int elementNumber,
String timeout,
boolean continueScript,
String... attributes)
Find a element (presumably a form one) in the currently displayed
Selenium driven web browser by a set of tag attributes and submit it.
|
int |
browserFindAndSubmit(int elementNumber,
String timeout,
String... attributes)
Find a element (presumably a form one) in the currently displayed
Selenium driven web browser by a set of tag attributes and submit it.
|
int |
browserFindAndSubmit(String... attributes)
Find a element (presumably a form one) in the currently displayed
Selenium driven web browser by a set of tag attributes and submit it.
|
int |
browserFindAndType(String textToType,
int elementNumber,
String timeout,
boolean continueScript,
String... attributes)
Find a text element in the currently displayed Selenium driven web browser
by a set of tag attributes and type the specified text into it.
|
int |
browserFindAndType(String textToType,
int elementNumber,
String timeout,
String... attributes)
Find a text element in the currently displayed Selenium driven web browser
by a set of tag attributes and type the specified text into it.
|
int |
browserFindAndType(String textToType,
String... attributes)
Find a text element in the currently displayed Selenium driven web browser
by a set of tag attributes and type the specified text into it.
|
int |
browserOpen(String browser,
String url)
Open the specified browser and load the specified web page.
|
int |
browserOpenRemote(String hub,
String url,
String... capabilities)
Open the specified remote browser and load the specified web
page.The method provides access to the Browser open
functionality.
|
int |
callProcedure(String procedureName,
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 |
clickImage(File[] templates)
Look for a component (a button, field, ...) on the screen by the
specified image(s) and click it.
|
int |
clickImage(File[] templates,
float passRate,
int number,
Rectangle cmpArea,
String timeout,
String sort,
float[] scale,
String wait)
Look for a component (a button, field, ...) on the screen by the
specified image(s) and click it.
|
int |
clickImage(File[] templates,
int number)
Look for a component (a button, field, ...) on the screen by the
specified image(s) and click it.
|
int |
clickImage(File[] templates,
int button,
int modifiers,
int count,
float passRate,
int number,
Rectangle cmpArea,
String timeout,
String sort,
float[] scale,
String wait)
Look for a component (a button, field, ...) on the screen by the
specified image(s) and click it.
|
int |
clickImage(File[] templates,
int button,
int modifiers,
int count,
Point move,
float passRate,
int number,
Rectangle cmpArea,
String timeout,
String sort,
float[] scale,
String stepName,
boolean continueScript,
String wait)
Look for a component (a button, field, ...) on the screen by the
specified image(s) and click it.
|
int |
clickImage(File[] templates,
int number,
String wait)
Look for a component (a button, field, ...) on the screen by the
specified image(s) and click it.
|
int |
clickImage(Image[] templates,
int button,
int modifiers,
int count,
float passRate,
int number,
Rectangle cmpArea,
String timeout,
String sort,
float[] scale,
String wait)
Look for a component (a button, field, ...) on the screen by the
specified image(s) and click it.
|
int |
clickImage(Image[] templates,
int button,
int modifiers,
int count,
Point move,
float passRate,
int number,
Rectangle cmpArea,
String timeout,
String sort,
float[] scale,
String stepName,
boolean continueScript,
String wait)
Look for a component (a button, field, ...) on the screen by the
specified image(s) and click it.
|
int |
clickObject(Color color)
Look for an object/component on the screen by the specified color and
click it.
|
int |
clickObject(Color color,
Integer rgbTolerance,
String wait)
Look for an object/component on the screen by the specified color and
click it.
|
int |
clickObject(int number,
Color color)
Look for an object/component on the screen by the specified color and
click it.
|
int |
clickObject(int number,
Color color,
Dimension min,
Dimension max)
Look for an object/component on the screen by the specified color and
click it.
|
int |
clickObject(int number,
Color color,
Integer rgbTolerance,
Dimension min,
Dimension max,
String wait)
Look for an object/component on the screen by the specified color and
click it.
|
int |
clickObject(int number,
Color color,
Integer rgbTolerance,
String wait)
Look for an object/component on the screen by the specified color and
click it.
|
int |
clickObject(int button,
int modifiers,
int count,
int number,
Point move,
Rectangle cmpArea,
String timeout,
Color color,
Integer rgbTolerance,
Dimension min,
Dimension max,
String stepName,
boolean continueScript,
String wait)
Look for an object/component on the screen by the specified color and
click it.
|
int |
clickObject(int button,
int modifiers,
int count,
int number,
Rectangle cmpArea,
String timeout,
Color color,
Integer rgbTolerance,
Dimension min,
Dimension max,
String wait)
Look for an object/component on the screen by the specified color and
click it.
|
int |
clickText(int button,
int modifiers,
int count,
int number,
Point move,
Rectangle cmpArea,
String timeout,
String language,
float scale,
int mode,
String text,
int textDistance,
String stepName,
boolean continueScript,
String wait) |
int |
clickText(int button,
int modifiers,
int count,
int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
int mode,
String text,
int distance,
String wait) |
int |
clickText(int button,
int modifiers,
int count,
int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
String text,
int distance,
String wait) |
int |
clickText(int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
String text,
int distance,
String wait) |
int |
clickText(int number,
String text) |
int |
clickText(int number,
String text,
int distance,
String wait) |
int |
clickText(String text) |
int |
clickText(String text,
int distance) |
int |
clickTextPattern(int button,
int modifiers,
int count,
int number,
Point move,
Rectangle cmpArea,
String timeout,
String language,
float scale,
int mode,
String pattern,
String stepName,
boolean continueScript,
String wait) |
int |
clickTextPattern(int button,
int modifiers,
int count,
int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
int mode,
String pattern,
String wait) |
int |
clickTextPattern(int button,
int modifiers,
int count,
int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
String pattern,
String wait) |
int |
clickTextPattern(int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
String pattern,
String wait) |
int |
clickTextPattern(int number,
String pattern,
String wait) |
int |
clickTextPattern(String pattern) |
int |
compareTo(File[] templates)
|
int |
compareTo(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(File[] templates,
float passRate,
Rectangle cmpArea,
boolean removeBg,
String bgColor,
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(File[] templates,
float passRate,
Rectangle cmpArea,
boolean removeBg,
String bgColor,
Integer minAlpha,
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(File[] templates,
float passRate,
Rectangle cmpArea,
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(File[] templates,
float passRate,
Rectangle cmpArea,
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(File[] templates,
float passRate,
Rectangle cmpArea,
String text,
int distance,
String pattern)
Recognize the text on the screen by a character image collection
using the Image Based Text Recognition comparison method.
|
int |
compareTo(File[] template,
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(File[] templates,
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(File[] templates,
String method,
float passRate,
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(File[] templates,
String method,
float passRate,
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(File[] templates,
String method,
float passRate,
Rectangle cmpArea,
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(File[] templates,
String method,
String methodParams,
float passRate,
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(File template,
Float passRate,
Rectangle cmpArea,
Color color,
Color[] bridgeColors,
Integer rgbTolerance,
Integer rotations,
Boolean draw,
Boolean clear)
Analyze the current remote desktop image using the Object Search Method.
|
int |
compareTo(File template,
Float passRate,
Rectangle cmpArea,
Color color,
Color[] bridgeColors,
Integer rgbTolerance,
Integer rotations,
Boolean draw,
Boolean clear,
Dimension min,
Dimension max)
Analyze the current remote desktop image using the Object Search Method.
|
int |
compareTo(Image[] templates,
ImageComparisonModule module,
float passRate,
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(Image[] templates,
ImageComparisonModule module,
float passRate,
Rectangle cmpArea,
Boolean removeBg,
Color bgColor,
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(Image[] templates,
ImageComparisonModule module,
float passRate,
Rectangle cmpArea,
Boolean removeBg,
Color bgColor,
Integer minAlpha,
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(Image[] templates,
ImageComparisonModule module,
float passRate,
Rectangle cmpArea,
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(Image template,
Float passRate,
Rectangle cmpArea,
Color color,
Color[] bridgeColors,
Integer rgbTolerance,
Integer rotations,
Boolean draw,
Boolean clear)
Analyze the current remote desktop image using the Object Search Method.
|
int |
compareTo(Image template,
Float passRate,
Rectangle cmpArea,
Color color,
Color[] bridgeColors,
Integer rgbTolerance,
Integer rotations,
Boolean draw,
Boolean clear,
Dimension min,
Dimension max)
Analyze the current remote desktop image using the Object Search Method.
|
int |
compareTo(Rectangle cmpArea,
String language)
Perform Optical Character Recognition (OCR) using the Tesseract engine.
|
int |
compareTo(Rectangle cmpArea,
String language,
float scale,
String text,
int distance,
String pattern)
Perform Optical Character Recognition (OCR) using the Tesseract engine.
|
int |
compareTo(Rectangle cmpArea,
String language,
float scale,
String text,
int distance,
String pattern,
int mode,
int filter,
int fontSize)
Perform Optical Character Recognition (OCR) using the Tesseract engine.
|
int |
compareTo(Rectangle cmpArea,
String language,
String text,
String pattern)
Perform Optical Character Recognition (OCR) using the Tesseract engine.
|
int |
compareTo(String name)
Test out if a variable exists.
|
int |
connect()
Connect to the local desktop.
|
int |
connect(int screen)
Connect to the local desktop.
|
int |
connect(int screen,
boolean force)
Connect to the local desktop.
|
int |
connect(String host)
|
int |
connect(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(String deviceName,
File iosApplication,
boolean startAtHomeScreen,
boolean force)
Deprecated.
5.0.4
|
int |
connect(String deviceName,
File wdaPath,
File iosApplication,
boolean force)
Connect to an iOS device through the "iOS over Xcode" connection.
|
int |
connect(String deviceName,
File wdaPath,
File iosApplication,
boolean forceUSB,
boolean force)
Connect to an iOS device through the "iOS over Xcode" connection.
|
int |
connect(String host,
String password)
Connect to a server which may or may not require a password.
|
int |
connect(String adbSerialNo,
String screen,
boolean force)
Connect to an Android device or simulator using the Android Over ADB
connection.
|
int |
connect(String host,
String password,
boolean force,
String iosDevice)
Connect to an iOS device.
|
int |
connect(String host,
String user,
String password,
boolean force)
Connect to a server using the specified user and password.
|
int |
connect(String host,
String user,
String password,
Dimension screenSize,
boolean force)
Connect to an RDP server using the specified user and password.
|
int |
connect(String host,
String user,
String password,
Map<String,Object> params,
boolean force)
Connect to a desktop.
|
int |
connect(String host,
String user,
String password,
String params,
String paramSeparator,
boolean force)
Connect to a desktop.
|
int |
date(String outFormat)
Save the current date in the specified format to the
_DATE
variable. |
int |
date(String date,
String inFormat,
String outFormat)
Read a date, format it and save it to the
_DATE variable. |
int |
date(String date,
String inFormat,
String add,
String outFormat,
String var)
Parse and manipulate a date.The method provides access to the
Date functionality.
|
int |
disconnect()
|
int |
doubleClickImage(File[] templates)
Look for a component (a button, field, ...) on the screen by the
specified image(s) and double click it.
|
int |
doubleClickImage(File[] templates,
float passRate,
int number,
Point move,
Rectangle cmpArea,
String timeout,
String sort,
float[] scale,
String stepName,
boolean continueScript,
String wait)
Look for a component (a button, field, ...) on the screen by the
specified image(s) and double click it.
|
int |
doubleClickImage(File[] templates,
float passRate,
int number,
Rectangle cmpArea,
String timeout,
String sort,
float[] scale,
String wait)
Look for a component (a button, field, ...) on the screen by the
specified image(s) and double click it.
|
int |
doubleClickImage(File[] templates,
int number)
Look for a component (a button, field, ...) on the screen by the
specified image(s) and double click it.
|
int |
doubleClickImage(File[] templates,
int number,
String wait)
Look for a component (a button, field, ...) on the screen by the
specified image(s) and double click it.
|
int |
doubleClickObject(Color color)
Look for an object/component on the screen by the specified color and
double click it.
|
int |
doubleClickObject(Color color,
Integer rgbTolerance,
String wait)
Look for an object/component on the screen by the specified color and
double click it.
|
int |
doubleClickObject(int number,
Color color)
Look for an object/component on the screen by the specified color and
double click it.
|
int |
doubleClickObject(int number,
Color color,
Dimension min,
Dimension max)
Look for an object/component on the screen by the specified color and
double click it.
|
int |
doubleClickObject(int number,
Color color,
Integer rgbTolerance,
Dimension min,
Dimension max,
String wait)
Look for an object/component on the screen by the specified color and
double click it.
|
int |
doubleClickObject(int number,
Color color,
Integer rgbTolerance,
String wait)
Look for an object/component on the screen by the specified color and
double click it.
|
int |
doubleClickObject(int number,
Point move,
Color color,
Integer rgbTolerance,
Dimension min,
Dimension max,
String stepName,
boolean continueScript,
String wait)
Look for an object/component on the screen by the specified color and
double click it.
|
int |
doubleClickText(int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
String text,
int distance,
String wait) |
int |
doubleClickText(int number,
String text) |
int |
doubleClickText(int number,
String text,
int distance,
String wait) |
int |
doubleClickText(String text) |
int |
doubleClickText(String text,
int distance) |
int |
doubleClickTextPattern(int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
int mode,
String pattern,
String wait) |
int |
doubleClickTextPattern(int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
String pattern,
String wait) |
int |
doubleClickTextPattern(int number,
String pattern,
String wait) |
int |
doubleClickTextPattern(String pattern) |
int |
dragImage(File[] templates,
int button,
int modifiers,
float passRate,
int number,
File[] targetTemplates,
int targetNumber,
Rectangle cmpArea,
String timeout,
String sort,
float[] scale,
boolean continueScript,
String step,
String wait)
Look for a component (a button, field, ...) on the screen by the
specified image(s) and drag it.
|
int |
dragImage(File[] templates,
int button,
int modifiers,
float passRate,
int number,
File[] targetTemplates,
int targetNumber,
Rectangle cmpArea,
String timeout,
String sort,
float[] scale,
String wait) |
int |
dragImage(File[] templates,
int button,
int modifiers,
float passRate,
int number,
Point relativeTargetCoords) |
int |
dragImage(File[] templates,
int button,
int modifiers,
float passRate,
int number,
Point relativeTargetCoords,
Rectangle cmpArea,
String timeout,
String sort,
float[] scale,
boolean continueScript,
String step,
String wait) |
int |
dragImage(File[] templates,
int button,
int modifiers,
float passRate,
int number,
Point relativeTargetCoords,
Rectangle cmpArea,
String timeout,
String sort,
float[] scale,
String wait) |
int |
dragImage(File[] templates,
int button,
Point relativeTargetCoords) |
int |
dragImage(File[] templates,
Point relativeTargetCoords) |
int |
dragObject(Color color,
Integer rgbTolerance,
Dimension min,
Dimension max,
Point relativeTargetCoords) |
int |
dragObject(Color color,
Point relativeTargetCoords) |
int |
dragObject(int button,
Color color,
Integer rgbTolerance,
Dimension min,
Dimension max,
int number,
Point relativeTargetCoords,
String wait) |
int |
dragObject(int button,
int modifiers,
int number,
Rectangle cmpArea,
String timeout,
Color color,
Integer rgbTolerance,
Dimension min,
Dimension max,
File[] targetTemplates,
int targetNumber,
boolean continueScript,
String step,
String wait)
Look for a component (a button, field, ...) on the screen by the
specified color and drag it.
|
int |
dragObject(int button,
int modifiers,
int number,
Rectangle cmpArea,
String timeout,
Color color,
Integer rgbTolerance,
Dimension min,
Dimension max,
File[] targetTemplates,
int targetNumber,
String wait) |
int |
dragObject(int button,
int modifiers,
Rectangle cmpArea,
String timeout,
Color color,
Integer rgbTolerance,
Dimension min,
Dimension max,
int number,
Point relativeTargetCoords,
boolean continueScript,
String step,
String wait) |
int |
dragObject(int button,
int modifiers,
Rectangle cmpArea,
String timeout,
Color color,
Integer rgbTolerance,
Dimension min,
Dimension max,
int number,
Point relativeTargetCoords,
String wait) |
int |
dragText(int button,
int modifiers,
int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
int mode,
String text,
int distance,
File[] targetTemplates,
int targetNumber,
boolean continueScript,
String step,
String wait) |
int |
dragText(int button,
int modifiers,
int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
int mode,
String text,
int distance,
File[] targetTemplates,
int targetNumber,
String wait) |
int |
dragText(int button,
int modifiers,
int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
int mode,
String text,
int distance,
Point relativeTargetCoords,
boolean continueScript,
String step,
String wait) |
int |
dragText(int button,
int modifiers,
int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
int mode,
String text,
int distance,
Point relativeTargetCoords,
String wait) |
int |
dragText(int button,
int modifiers,
int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
String text,
int distance,
File[] targetTemplates,
int targetNumber,
String wait) |
int |
dragText(int button,
int modifiers,
int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
String text,
int distance,
Point relativeTargetCoords,
String wait) |
int |
dragText(int button,
int number,
String language,
float scale,
String text,
int distance,
Point relativeTargetCoords) |
int |
dragText(String text,
int distance,
Point relativeTargetCoords) |
int |
dragText(String text,
Point relativeTargetCoords) |
int |
dragTextPattern(int button,
int modifiers,
int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
int mode,
String pattern,
File[] targetTemplates,
int targetNumber,
boolean continueScript,
String step,
String wait) |
int |
dragTextPattern(int button,
int modifiers,
int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
int mode,
String pattern,
File[] targetTemplates,
int targetNumber,
String wait) |
int |
dragTextPattern(int button,
int modifiers,
int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
int mode,
String pattern,
Point relativeTargetCoords,
boolean continueScript,
String step,
String wait) |
int |
dragTextPattern(int button,
int modifiers,
int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
int mode,
String pattern,
Point relativeTargetCoords,
String wait) |
int |
dragTextPattern(int button,
int modifiers,
int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
String pattern,
File[] targetTemplates,
int targetNumber,
String wait) |
int |
dragTextPattern(int button,
int modifiers,
int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
String pattern,
Point relativeTargetCoords,
String wait) |
int |
dragTextPattern(int button,
int number,
String language,
float scale,
String pattern,
Point relativeTargetCoords) |
int |
dragTextPattern(String pattern,
Point relativeTargetCoords) |
int |
excelClose(String id,
boolean save)
|
int |
excelCopy(String rows,
String columns,
String sheet,
String id)
Mark cells for copying (since v4.4.4).
|
int |
excelCreate(File outputFile,
String sheetName,
String id)
Create a new Microsoft Excel document for reading and writing.
|
int |
excelCreate(File outputFile,
String sheetName,
String id,
String password)
|
int |
excelCreate(OutputStream outputStream,
String sheetName,
String id)
Create a Microsoft Excel document and associate it with an output stream.
|
int |
excelCreate(OutputStream outputStream,
String sheetName,
String id,
String password)
Create a Microsoft Excel document and associate it with an output stream.
|
int |
excelCreate(String sheetName,
String id)
Create and select a new sheet in the current or specified Excel document.
|
int |
excelFind(Object value,
String type,
boolean evaluate,
Object sheet,
String id)
|
int |
excelFind(String pattern,
boolean evaluate,
String type,
Object sheet,
String id)
Search the specified sheet for a cell whose value (and optionally also type)
matches the given regular expression.
|
int |
excelOpen(File inputFile,
File outputFile,
String sheet,
String id)
Open a Microsoft Excel file for reading and writing.
|
int |
excelOpen(File inputFile,
File outputFile,
String sheet,
String id,
String password)
|
int |
excelOpen(File inputFile,
String id)
Open a Microsoft Excel file for reading and writing and select automatically
the first sheet.
|
int |
excelOpen(InputStream inputStream,
OutputStream outputStream,
String sheet,
String id)
Open a Microsoft Excel file.
|
int |
excelOpen(InputStream inputStream,
OutputStream outputStream,
String sheet,
String id,
String password)
Open a Microsoft Excel file.
|
int |
excelPaste(int row,
String column,
String sheet,
String id)
Copy cells selected previously by
Excel select to the
specified location (cell). |
int |
excelPaste(String ref,
String sheet,
String id)
Copy cells selected previously by
Excel select to the
specified location (cell). |
int |
excelSelect(int row,
String column,
boolean evaluate,
String id)
|
int |
excelSelect(int row,
String column,
String sheet,
boolean evaluate,
String id)
Select a cell and retrieve its value and type to the context variables.
|
int |
excelSelect(String ref,
boolean evaluate,
String id)
Select a cell from the current sheet and retrieve its value and type to the context variables.
|
int |
excelSelect(String sheet,
String id)
Select (open) a sheet.
|
int |
excelSelect(String ref,
String sheet,
boolean evaluate,
String id)
Select a cell and retrieve its value and type to the context variables.
|
int |
excelSet(int row,
String column,
Object sheet,
Color fg,
Color bg,
int width,
int height,
String id)
Set attributes of the specified cell such as the background and
foreground colors and/or the column width and/or the row height.
|
int |
excelSet(int row,
String column,
Object value,
Object sheet,
String type,
String id)
Set value and/or type of the specified cell.
|
int |
excelSet(int row,
String column,
Object value,
Object sheet,
String type,
String format,
String informat,
Color fg,
Color bg,
int width,
int height,
String id)
Set value and/or type of the specified cell.The method provides access to functionality of the
Excel set scripting language command.
|
int |
excelSet(int row,
String column,
Object value,
Object sheet,
String type,
String format,
String informat,
String id)
Set value and/or type of the specified cell.
|
int |
excelSet(int row,
String column,
Object value,
String id)
Set value of the specified cell in the currently selected sheet.
|
int |
excelSet(int row,
String column,
Object value,
String type,
String id)
Set value and/or type of the specified cell in the currently selected sheet.
|
int |
excelSet(Object value,
String id)
Set value of the currently selected (previously used) cell in the
currently selected sheet.
|
int |
excelSet(String ref,
Object value,
Object sheet,
String type,
String id)
Set value and/or type of the specified cell.
|
int |
excelSet(String ref,
Object value,
String id)
Set value of the specified cell in the currently selected sheet.
|
int |
excelSet(String ref,
Object value,
String type,
String id)
Set value and/or type of the specified cell in the currently selected sheet.
|
int |
exec(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(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(String command,
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(String command,
OutputStream out,
boolean nowait,
int count,
String wait)
Execute a command of the local operating system.
|
int |
exec(String command,
OutputStream out,
int count,
String wait)
Execute a command of the local operating system.
|
int |
exec(String command,
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(String command,
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(String command,
Writer out,
boolean nowait,
int count,
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(String command,
Writer out,
int count,
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(String url)
A convenience method to open a web browser on the local operating system.
|
int |
exit(Integer exitCode)
Set the test script exit status.
|
int |
exit(Integer exitCode,
String description)
Set the test script exit status.
|
int |
fileAppend(String text,
String id)
|
int |
fileClose(String id,
boolean save)
|
int |
fileCreate(File outputFile,
String id)
|
int |
fileCreate(OutputStream outputStream,
String id)
Create a text or CSV file and associate it with an output stream.
|
int |
fileDelete(int line,
int column,
int length,
String id)
|
int |
fileFind(String text,
int line,
int column,
String direction,
String scope,
String id)
|
int |
fileInsert(String text,
int line,
int column,
String id)
|
int |
fileOpen(File inputFile,
File outputFile,
String id)
|
int |
fileOpen(InputStream inputStream,
OutputStream outputStream,
String id)
Open a text or CSV file.
|
int |
fileParse(int line,
String id)
Parse the specified CSV line into values using the rules defined by
the RFC 4180.
|
int |
fileParse(int line,
String pattern,
boolean trim,
String id)
Parse the specified line into values by the given
java.util.regex.Pattern compatible
regular expression. |
int |
fileParse(int line,
String separator,
String delimeter,
boolean trim,
String id)
|
int |
fileRead(int line,
int column,
int length,
String id)
|
int |
gestureClear()
Clear the gesture buffer content, i.e.
|
int |
gestureExecute()
Execute the gesture buffer content, i.e.
|
int |
gestureExecute(Point start,
String duration)
Execute the gesture buffer content, i.e.
|
int |
gestureExecute(String name)
Execute the gesture.
|
int |
gestureExecute(String name,
Point start,
String duration)
Execute the gesture.
|
int |
gestureExecute(String name,
Point start,
String duration,
Boolean clear,
int count,
String wait)
Execute the gesture.
|
int |
gestureMove(int finger,
Point to)
Record move (drag) of a finger to the gesture buffer.
|
int |
gesturePress(int finger,
Point to)
Record a finger press (touch) to the gesture buffer.
|
int |
gestureRelease(int finger)
Record release of a finger to the gesture buffer.
|
int |
gestureSave(String name,
Boolean clear)
Save the gesture recorded to the gesture buffer under the specified name.
|
int |
getExitCode()
Return result of the last executed command (method).
|
TestWrapper |
getRootWrapper()
Get the root test wrapper.
|
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(String file)
Include a TPR test script (.tpr).
|
boolean |
isPass()
Return result of the last executed command (method).
|
int |
log(String message,
Level level)
Log a message to the script execution log.
|
int |
log(String message,
Level level,
boolean terminal)
Log a message to the script execution log.
|
int |
log(String message,
Level level,
boolean terminal,
boolean history)
Log a message to the script execution log.
|
int |
mailDelete()
Delete all messages retrieved through the previous call of any of the
mailGet() methods.
|
int |
mailDelete(String uid)
Delete one or more emails.
|
int |
mailDelete(String protocol,
String server,
String user,
String password,
String uid)
Delete one or more emails.
|
int |
mailDelete(String protocol,
String security,
String server,
String user,
String password,
String uid)
Delete one or more emails.
|
int |
mailGet(String uid)
Get a single mail specified by the UID from a POP3 or IMAP server.
|
int |
mailGet(String folder,
int max,
String from,
String subject,
String body,
String attachment,
Boolean read)
Get mail from a POP3 or IMAP server and filter it by the specified
parameters.
|
int |
mailGet(String protocol,
String server,
String user,
String password,
String folder,
String uid,
int max,
String from,
String subject,
String body,
String attachment,
Boolean read)
Get mail from a POP3 or IMAP server and filter it by the specified
parameters.
|
int |
mailGet(String protocol,
String security,
String server,
String user,
String password,
String folder,
String uid,
int max,
String from,
String subject,
String body,
String attachment,
Boolean read)
Get mail from a POP3 or IMAP server and filter it by the specified
parameters.The method provides access to the Mail
functionality.
|
int |
mailSet(Boolean read)
Set the "Seen" ("Read") flag of all messages retrieved through the
previous call of any of the mailGet() method.
|
int |
mailSet(String uid,
Boolean read)
Set the "Seen" ("Read") flag of one or more emails.
|
int |
mailSet(String protocol,
String server,
String user,
String password,
String uid,
Boolean read)
Set the "Seen" ("Read") flag of one or more emails.
|
int |
mailSet(String protocol,
String security,
String server,
String user,
String password,
String uid,
Boolean read)
Set the "Seen" ("Read") flag of one or more emails.
|
int |
mouseClick(int x,
int y)
|
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,
String wait)
Perform left mouse click(s) on the currently connected desktop.
|
int |
mouseClick(Point to)
Perform a single left mouse click on the currently connected desktop.
|
int |
mouseClick(Point to,
int count)
Perform left mouse click(s) on the currently connected desktop.
|
int |
mouseClick(Point to,
int modifiers,
int button,
int count,
String wait)
Perform left mouse click(s) on the currently connected desktop.
|
int |
mouseClick(Point to,
int count,
String wait)
Perform left mouse click(s) on the currently connected desktop.
|
int |
mouseClick(Point to,
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,
String wait)
Perform a double left mouse click on the currently connected desktop.
|
int |
mouseDoubleClick(Point to)
Perform a double left mouse click on the current desktop client.
|
int |
mouseDoubleClick(Point to,
String wait)
Perform a double left mouse click on the current desktop client.
|
int |
mouseDrag(Point from,
Point to,
int modifiers,
int button,
String wait)
Perform a left button mouse drag on the currently connected desktop.
|
int |
mouseEvent(String action,
int modifiers,
int button,
Point from,
Point to,
int count,
String wait)
Perform a generic mouse action on the currently connected desktop.
|
int |
mouseEvent(String action,
Point center,
int start,
int end,
int count,
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,
String wait)
Perform a mouse move on the currently connected desktop with optional modifier key(s) pressed.
|
int |
mouseMove(int x,
int y,
String wait)
Perform a mouse move on the currently connected desktop.
|
int |
mouseMove(Point to)
Perform a mouse move on the currently connected desktop.
|
int |
mouseMove(Point to,
int modifiers,
String wait)
Perform a mouse move on the currently connected desktop with optional modifier key(s) pressed.
|
int |
mouseMove(Point to,
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,
String wait)
Perform a pinch action with the default center point and the start/end
distances on the currently connected desktop.
|
int |
mousePinch(Point center,
int start,
int end,
int count,
String wait)
Perform a pinch action on the currently connected desktop.
|
int |
mousePress(int button,
int modifiers,
Point to,
String wait)
Press the specified mouse button without releasing it.
|
int |
mousePress(Point to,
String wait)
Press the left mouse button without releasing it.
|
int |
mouseRelease(int button,
int modifiers,
Point to,
String wait)
Release the specified mouse button.
|
int |
mouseRelease(Point to,
String wait)
Release the left mouse button.
|
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,
String wait)
Perform right mouse click(s) on the currently connected desktop.
|
int |
mouseRightClick(Point to)
Perform a single right mouse click on the currently connected desktop.
|
int |
mouseRightClick(Point to,
int count)
Perform right mouse click(s) on the currently connected desktop.
|
int |
mouseRightClick(Point to,
int modifiers,
int count,
String wait)
Perform right mouse click(s) on the currently connected desktop.
|
int |
mouseRightClick(Point to,
int count,
String wait)
Perform right mouse click(s) on the currently connected desktop.
|
int |
mouseRightDrag(Point from,
Point to,
int modifiers,
String wait)
Perform a right button mouse drag on the currently connected desktop.
|
int |
mouseRightPress(Point to,
String wait)
Press the right mouse button without releasing it.
|
int |
mouseRightRelease(Point to,
String wait)
Release the right mouse button.
|
int |
mouseWheelDown(int x,
int y,
int modifiers,
int count,
String wait)
Scroll down the mouse wheel on the current desktop.
|
int |
mouseWheelDown(Point to,
int modifiers,
int count,
String wait)
Scroll down the mouse wheel on the current desktop.
|
int |
mouseWheelUp(int x,
int y,
int modifiers,
int count,
String wait)
Scroll up the mouse wheel on the current desktop.
|
int |
mouseWheelUp(Point to,
int modifiers,
int count,
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,
String wait)
Perform a zoom action with the default center point and the start/end
distances on the currently connected desktop.
|
int |
mouseZoom(Point center,
int start,
int end,
int count,
String wait)
Perform a zoom action on the currently connected desktop.
|
int |
paste(String text)
Paste text on the current desktop.
|
int |
paste(String text,
int count,
String wait)
Paste text on the current desktop.
|
int |
pause()
|
int |
pause(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,
String wait)
|
int |
press(char c,
int location,
int count,
String delay,
String wait)
Press a character with optional modifiers on the current desktop once or more times.
|
int |
press(String key)
Press a key with optional modifiers on the current desktop.
|
int |
press(String key,
int location)
Press a key with optional modifiers on the current desktop.
|
int |
press(String key,
int location,
int count,
Boolean release,
String delay,
String wait)
Press a key with optional modifiers on the current desktop once or more times.
|
int |
press(String key,
int location,
int count,
String wait)
Press a key with optional modifiers on the current desktop once or more times.
|
int |
press(String key,
int location,
int count,
String delay,
String wait)
Press a key with optional modifiers on the current desktop once or more times.
|
int |
press(String key,
int location,
String wait)
Press a key with optional modifiers on the current desktop.
|
int |
press(String key,
String wait)
Press a key with optional modifiers on the current desktop.
|
int |
press(String key,
String wait,
int count)
Press a key with optional modifiers on the current desktop once or more times.
|
int |
report(File out)
Start the default report provider to generate a report on test script
execution.
|
int |
report(File[] out,
String description)
Start the Enterprise report provider to generate a report on test
script execution.
|
int |
report(File[] out,
String description,
boolean onExit)
Start the Enterprise report provider to generate a report on test
script execution.
|
int |
report(File out,
String description)
Start the default report provider to generate a report on test script
execution.
|
int |
report(File out,
String description,
boolean onExit)
Start the enterprise report provider to generate a report on test script
execution.
|
int |
report(File out,
String provider,
String description)
Start the specified report provider to generate a report on test script
execution.
|
int |
report(File out,
String provider,
String description,
String scope)
Start the specified report provider to generate a report on test script
execution.
|
int |
rightClickImage(File[] templates)
Look for a component (a button, field, ...) on the screen by the
specified image(s) and right click it.
|
int |
rightClickImage(File[] templates,
float passRate,
int number,
Point move,
Rectangle cmpArea,
String timeout,
String sort,
float[] scale,
String stepName,
boolean continueScript,
String wait)
Look for a component (a button, field, ...) on the screen by the
specified image(s) and right click it.
|
int |
rightClickImage(File[] templates,
float passRate,
int number,
Rectangle cmpArea,
String timeout,
String sort,
float[] scale,
String wait)
Look for a component (a button, field, ...) on the screen by the
specified image(s) and right click it.
|
int |
rightClickImage(File[] templates,
int number)
Look for a component (a button, field, ...) on the screen by the
specified image(s) and right click it.
|
int |
rightClickImage(File[] templates,
int number,
String wait)
Look for a component (a button, field, ...) on the screen by the
specified image(s) and right click it.
|
int |
rightClickObject(Color color)
Look for an object/component on the screen by the specified color and
right click it.
|
int |
rightClickObject(Color color,
Integer rgbTolerance,
String wait)
Look for an object/component on the screen by the specified color and
right click it.
|
int |
rightClickObject(int number,
Color color)
Look for an object/component on the screen by the specified color and
right click it.
|
int |
rightClickObject(int number,
Color color,
Dimension min,
Dimension max)
Look for an object/component on the screen by the specified color and
right click it.
|
int |
rightClickObject(int number,
Color color,
Integer rgbTolerance,
Dimension min,
Dimension max,
String wait)
Look for an object/component on the screen by the specified color and
right click it.
|
int |
rightClickObject(int number,
Color color,
Integer rgbTolerance,
String wait)
Look for an object/component on the screen by the specified color and
right click it.
|
int |
rightClickObject(int number,
Point move,
Color color,
Integer rgbTolerance,
Dimension min,
Dimension max,
String stepName,
boolean continueScript,
String wait)
Look for an object/component on the screen by the specified color and
right click it.
|
int |
rightClickText(int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
String text,
int distance,
String wait) |
int |
rightClickText(int number,
String text) |
int |
rightClickText(int number,
String text,
int distance,
String wait) |
int |
rightClickText(String text) |
int |
rightClickText(String text,
int distance) |
int |
rightClickTextPattern(int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
int mode,
String pattern,
String wait) |
int |
rightClickTextPattern(int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
String pattern,
String wait) |
int |
rightClickTextPattern(int number,
String pattern,
String wait) |
int |
rightClickTextPattern(String pattern) |
int |
run(String script)
Execute a TPR test script (.tpr) or a source
Java file (.java) or instantiate and execute a Java test script specified
by a fully qualified class name (with package).
|
int |
run(String script,
Object... parameters)
Execute a test script with optional parameters.
|
int |
screenshot(File file)
|
int |
screenshot(File file,
Rectangle area)
Take a screen shot of the remote desktop or its part and save it to a file.
|
int |
screenshot(File file,
String description)
Take a screen shot of the remote desktop and save it to a file.
|
int |
screenshot(File file,
String description,
Rectangle area)
Take a screen shot of the remote desktop or its part and save it to a file.
|
int |
screenshot(File file,
String description,
Rectangle area,
File[] templates,
float passRate,
Rectangle cmpArea,
boolean removeBg,
String bgColor,
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(File file,
String description,
Rectangle area,
File[] templates,
float passRate,
Rectangle cmpArea,
boolean removeBg,
String bgColor,
Integer minAlpha,
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(File file,
String description,
Rectangle area,
File[] templates,
float passRate,
Rectangle cmpArea,
boolean removeBg,
String bgColor,
Integer minAlpha,
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(File file,
String description,
Rectangle area,
File[] templates,
float passRate,
Rectangle cmpArea,
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(File file,
String description,
Rectangle area,
File[] templates,
float passRate,
Rectangle cmpArea,
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(File file,
String description,
Rectangle area,
File[] templates,
float passRate,
Rectangle cmpArea,
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(File file,
String description,
Rectangle area,
File[] templates,
float passRate,
Rectangle cmpArea,
String text,
int distance,
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(File file,
String description,
Rectangle area,
File[] templates,
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(File file,
String description,
Rectangle area,
File[] templates,
String method,
float passRate,
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(File file,
String description,
Rectangle area,
File[] templates,
String method,
float passRate,
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(File file,
String description,
Rectangle area,
File[] templates,
String method,
String methodParams,
float passRate,
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(File file,
String description,
Rectangle area,
File[] templates,
String method,
String methodParams,
float passRate,
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(File file,
String description,
Rectangle area,
File[] templates,
String method,
String methodParams,
float passRate,
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(File file,
String description,
Rectangle area,
File[] templates,
String method,
String methodParams,
float passRate,
Rectangle cmpArea,
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(File file,
String description,
Rectangle area,
File[] templates,
String method,
String methodParams,
float passRate,
Rectangle cmpArea,
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(File file,
String description,
Rectangle area,
File template,
float passRate,
Rectangle cmpArea,
Color color,
Color[] bridgeColors,
Integer rgbTolerance,
Integer rotations,
Boolean draw,
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(File file,
String description,
Rectangle area,
File template,
float passRate,
Rectangle cmpArea,
Color color,
Color[] bridgeColors,
Integer rgbTolerance,
Integer rotations,
Boolean draw,
Boolean clear,
Dimension min,
Dimension max)
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(File file,
String description,
Rectangle area,
Image[] templates,
float passRate,
Rectangle cmpArea,
boolean removeBg,
String bgColor,
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(File file,
String description,
Rectangle area,
Image[] templates,
float passRate,
Rectangle cmpArea,
boolean removeBg,
String bgColor,
Integer minAlpha,
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(File file,
String description,
Rectangle area,
Image[] templates,
float passRate,
Rectangle cmpArea,
boolean removeBg,
String bgColor,
Integer minAlpha,
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(File file,
String description,
Rectangle area,
Image[] templates,
String method,
String methodParams,
float passRate,
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(File file,
String description,
Rectangle area,
Image[] templates,
String method,
String methodParams,
float passRate,
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(File file,
String description,
Rectangle area,
Image[] templates,
String method,
String methodParams,
float passRate,
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(File file,
String description,
Rectangle area,
Rectangle cmpArea,
String language,
float scale,
String text,
int distance,
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(File file,
String description,
Rectangle area,
Rectangle cmpArea,
String language,
float scale,
String text,
int distance,
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(File file,
String description,
Rectangle area,
Rectangle cmpArea,
String language,
String text,
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(String number,
boolean isEnd,
String name)
|
int |
script(String number,
String action,
String name)
Define start or end of a script (test case).
|
int |
scriptEnd(String number)
Define end of a script (test case).
|
int |
scriptEnd(String number,
String name)
Define end of a script (test case).
|
int |
scriptStart(String number)
Define start of a script (test case).
|
int |
scriptStart(String number,
String name)
Define start of a script (test case).
|
int |
sendMail(String subject,
String text)
|
int |
sendMail(String subject,
String text,
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(String password,
String subject,
String text)
Send an E-mail of the specified subject and text to one or
more recipients through an SMTP server.
|
int |
sendMail(String password,
String subject,
String text,
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(String server,
String user,
String password,
String from,
String to,
String subject,
String text,
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(String server,
String user,
String password,
String from,
String to,
String subject,
String text,
File[] attachments,
boolean delayed,
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(String server,
String user,
String password,
String from,
String to,
String cc,
String bcc,
String subject,
String text,
File[] attachments,
boolean delayed,
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(String server,
String user,
String security,
String password,
String from,
String to,
String cc,
String bcc,
String subject,
String text,
File[] attachments,
boolean delayed,
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(String dir)
|
void |
setTemplateDir(String dir)
|
int |
setVariable(String... params)
Set one or more context variables.
|
int |
step(String name,
String result,
String instructions,
String expected,
String actual,
String notes)
|
int |
stepFail(String name,
String instructions)
Define a failed (unsuccessful) test step.
|
int |
stepFailed(String name,
String instructions,
String expected,
String actual,
String notes)
Define a failed (unsuccessful) test step.
|
int |
stepNotAvailable(String name,
String instructions,
String expected,
String actual,
String notes)
Define a test step whose result is not available.
|
int |
stepNotTested(String name,
String instructions,
String expected,
String actual,
String notes)
Define a test step which was not (yet) tested.
|
int |
stepPassed(String name,
String instructions)
Define a passed (successful) test step.
|
int |
stepPassed(String name,
String instructions,
String expected,
String actual,
String notes)
Define a passed (successful) test step.
|
int |
stringIndexOf(String text,
String string)
The method provides access to functionality of the String indexof command.
|
int |
stringIndexOf(String text,
String string,
int distance)
|
int |
stringIndexOf(String text,
String string,
int start,
int end,
int distance,
String variableName)
The method provides access to functionality of the String indexof command.
|
int |
stringIndexOf(String text,
String string,
int start,
int end,
String variableName)
The method provides access to functionality of the String indexof command.
|
int |
stringIndexOf(String text,
String string,
int distance,
String variableName)
The method provides access to functionality of the String indexof command.
|
int |
stringIndexOf(String text,
String string,
String variableName)
The method provides access to functionality of the String indexof command.
|
int |
stringLength(String text)
The method provides access to functionality of the String length command.
|
int |
stringLength(String text,
String variableName)
The method provides access to functionality of the String length command.
|
int |
stringMatches(String text,
String pattern)
The method provides access to functionality of the String matches command.
|
int |
stringMatches(String text,
String string,
int distance)
The method provides access to functionality of the String matches
command performing fuzzy text matching.
|
int |
stringMatches(String text,
String string,
int distance,
String variableName)
The method provides access to functionality of the String matches
command performing fuzzy text matching.
|
int |
stringMatches(String text,
String pattern,
String variableName)
The method provides access to functionality of the String matches command.
|
int |
stringReplace(String text,
String string,
String replacement)
The method provides access to functionality of the String replace command.
|
int |
stringReplace(String text,
String string,
String replacement,
String variableName)
The method provides access to functionality of the String replace command.
|
int |
stringReplacePattern(String text,
String pattern,
String replacement)
The method provides access to functionality of the String replace command.
|
int |
stringReplacePattern(String text,
String pattern,
String replacement,
String variableName)
The method provides access to functionality of the String replace command.
|
int |
stringSplit(String text,
String delimeter)
The method provides access to functionality of the String split command.
|
int |
stringSplit(String text,
String delimeter,
String variableName)
The method provides access to functionality of the String split command.
|
int |
stringSplitByPattern(String text,
String pattern)
The method provides access to functionality of the String split command.
|
int |
stringSplitByPattern(String text,
String pattern,
String variableName)
The method provides access to functionality of the String split command.
|
int |
stringSubstring(String text,
Integer start,
Integer end)
The method provides access to functionality of the String substring command.
|
int |
stringSubstring(String text,
Integer start,
Integer end,
String variableName)
The method provides access to functionality of the String substring command.
|
int |
stringToString(String codeList)
The method provides access to functionality of the String tostring command.
|
int |
stringToString(String codeList,
String variableName)
The method provides access to functionality of the String tostring command.
|
int |
stringTrim(String text,
String variableName)
The method provides access to functionality of the String trim command.
|
void |
test()
Empty test method implementing the
JavaTestScript interface. |
int |
timer(String names,
String description)
Create and/or configure timer(s).
|
int |
timer(String names,
String description,
long value,
long referenceValue)
Create and/or configure timer(s).
|
int |
timer(String names,
String description,
long value,
long referenceValue,
String group,
String ungroup,
File referenceFile)
Create and/or configure timer(s) and/or timer groups.
|
int |
timerGroup(String names,
String group)
Associate timer(s) with a timer group or groups.
|
int |
timerLoad(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(String names)
Start timer(s).
|
int |
timerStart(String names,
String description,
long value,
long referenceValue,
String group,
String ungroup)
Create and/or configure timer(s) and/or timer groups and start it
(them).
|
int |
timerStop(String names)
Stop timer(s) and/or timer groups.
|
int |
timerStop(String names,
String description,
long value,
long referenceValue,
String group,
String ungroup)
Stop timer(s) and/or timer groups.
|
int |
timerUngroup(String names,
String ungroup)
Remove timer(s) from a timer group or groups.
|
int |
type(String text)
|
int |
type(String text,
int count,
int location,
String wait)
Type a text on the current desktop.
|
int |
type(String text,
int count,
String wait)
Type a text on the current desktop.
|
int |
type(String text,
String wait)
Type a text on the current desktop.
|
int |
typeLine(String text)
|
int |
typeLine(String text,
int count,
int location,
String wait)
Type a text and press an Enter key on the current desktop once or more times.
|
int |
typeLine(String text,
int count,
String wait)
Type a text and press an Enter key on the current desktop once or more times.
|
int |
typeLine(String text,
String wait)
Type a text and press an Enter key on the current desktop.
|
int |
vargDelete(String name)
Delete variables of the specified name from all scopes.
|
int |
vargDelete(String name,
String scope)
Delete a global, script or local variable.
|
int |
vargSet(String name,
String value,
String scope)
Create or set a global, script or local variable.
|
int |
wait(String time)
|
int |
waitForBell(int count,
String timeout,
String wait)
|
int |
waitForBell(String timeout)
Wait until the remote desktop beeps (rings a bell).
|
int |
waitForBell(String timeout,
String wait)
Wait until the remote desktop beeps (rings a bell).
|
int |
waitForClipboard(String timeout)
Wait for a clipboard update.
|
int |
waitForClipboard(String timeout,
String wait)
|
int |
waitForMatch(File[] templates)
|
int |
waitForMatch(File[] templates,
float passRate,
Rectangle cmpArea,
String interval,
String timeout,
String text,
int distance,
String pattern,
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(File[] templates,
float passRate,
String interval,
Rectangle cmpArea,
String timeout,
boolean removeBg,
String bgColor,
Integer minAlpha,
Integer rgbTolerance,
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(File[] templates,
float passRate,
String interval,
Rectangle cmpArea,
String timeout,
boolean removeBg,
String bgColor,
Integer minAlpha,
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(File[] templates,
float passRate,
String method,
Rectangle cmpArea,
String timeout,
String wait) |
int |
waitForMatch(File[] templates,
float passRate,
String interval,
Rectangle cmpArea,
String timeout,
String sort,
float[] scale,
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(File[] templates,
float passRate,
String interval,
Rectangle cmpArea,
String timeout,
String sort,
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(File[] templates,
float passRate,
String method,
String timeout) |
int |
waitForMatch(File[] templates,
float passRate,
String interval,
String method,
String methodParams,
Rectangle cmpArea,
String timeout,
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(File[] templates,
String timeout) |
int |
waitForMatch(File[] templates,
String method,
String timeout) |
int |
waitForMatch(File template,
float passRate,
String interval,
Rectangle cmpArea,
String timeout,
Color color,
Color[] bridgeColors,
Integer rgbTolerance,
Integer rotations,
Boolean draw,
Boolean clear,
Dimension min,
Dimension max,
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(File template,
float passRate,
String interval,
Rectangle cmpArea,
String timeout,
Color color,
Color[] bridgeColors,
Integer rgbTolerance,
Integer rotations,
Boolean draw,
Boolean clear,
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(Image[] templates,
float passRate,
String interval,
Rectangle cmpArea,
String timeout,
boolean removeBg,
String bgColor,
Integer minAlpha,
Integer rgbTolerance,
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(Image[] templates,
float passRate,
String interval,
Rectangle cmpArea,
String timeout,
boolean removeBg,
String bgColor,
Integer minAlpha,
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(Image[] templates,
float passRate,
String interval,
String method,
String methodParams,
Rectangle cmpArea,
String timeout,
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(Image template,
float passRate,
String interval,
Rectangle cmpArea,
String timeout,
Color color,
Color[] bridgeColors,
Integer rgbTolerance,
Integer rotations,
Boolean draw,
Boolean clear,
Dimension min,
Dimension max,
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(Image template,
float passRate,
String interval,
Rectangle cmpArea,
String timeout,
Color color,
Color[] bridgeColors,
Integer rgbTolerance,
Integer rotations,
Boolean draw,
Boolean clear,
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(String interval,
Rectangle cmpArea,
String timeout,
String language,
float scale,
String text,
int distance,
String pattern,
int mode,
int filter,
int fontSize,
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(String interval,
Rectangle cmpArea,
String timeout,
String language,
float scale,
String text,
int distance,
String pattern,
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(String interval,
Rectangle cmpArea,
String timeout,
String language,
String text,
String pattern,
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(String name,
String interval,
String timeout,
String wait)
Wait for a variable to be created.
|
int |
waitForMismatch(File[] templates)
|
int |
waitForMismatch(File[] templates,
float passRate,
Rectangle cmpArea,
String interval,
String timeout,
String text,
int distance,
String pattern,
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(File[] templates,
float passRate,
String interval,
Rectangle cmpArea,
String timeout,
boolean removeBg,
String bgColor,
Integer minAlpha,
Integer rgbTolerance,
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(File[] templates,
float passRate,
String interval,
Rectangle cmpArea,
String timeout,
boolean removeBg,
String bgColor,
Integer minAlpha,
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(File[] templates,
float passRate,
String method,
Rectangle cmpArea,
String timeout,
String wait) |
int |
waitForMismatch(File[] templates,
float passRate,
String interval,
Rectangle cmpArea,
String timeout,
String sort,
float[] scale,
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(File[] templates,
float passRate,
String interval,
Rectangle cmpArea,
String timeout,
String sort,
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(File[] templates,
float passRate,
String method,
String timeout) |
int |
waitForMismatch(File[] templates,
float passRate,
String interval,
String method,
String methodParams,
Rectangle cmpArea,
String timeout,
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(File[] templates,
String timeout) |
int |
waitForMismatch(File[] templates,
String method,
String timeout) |
int |
waitForMismatch(File template,
float passRate,
String interval,
Rectangle cmpArea,
String timeout,
Color color,
Color[] bridgeColors,
Integer rgbTolerance,
Integer rotations,
Boolean draw,
Boolean clear,
Dimension min,
Dimension max,
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(File template,
float passRate,
String interval,
Rectangle cmpArea,
String timeout,
Color color,
Color[] bridgeColors,
Integer rgbTolerance,
Integer rotations,
Boolean draw,
Boolean clear,
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(Image[] templates,
float passRate,
String interval,
Rectangle cmpArea,
String timeout,
boolean removeBg,
String bgColor,
Integer minAlpha,
Integer rgbTolerance,
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(Image[] templates,
float passRate,
String interval,
Rectangle cmpArea,
String timeout,
boolean removeBg,
String bgColor,
Integer minAlpha,
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(Image[] templates,
float passRate,
String interval,
String method,
String methodParams,
Rectangle cmpArea,
String timeout,
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(Image template,
float passRate,
String interval,
Rectangle cmpArea,
String timeout,
Color color,
Color[] bridgeColors,
Integer rgbTolerance,
Integer rotations,
Boolean draw,
Boolean clear,
Dimension min,
Dimension max,
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(Image template,
float passRate,
String interval,
Rectangle cmpArea,
String timeout,
Color color,
Color[] bridgeColors,
Integer rgbTolerance,
Integer rotations,
Boolean draw,
Boolean clear,
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(String interval,
Rectangle cmpArea,
String timeout,
String language,
float scale,
String text,
int distance,
String pattern,
int mode,
int filter,
int fontSize,
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(String interval,
Rectangle cmpArea,
String timeout,
String language,
float scale,
String text,
int distance,
String pattern,
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(String interval,
Rectangle cmpArea,
String timeout,
String language,
String text,
String pattern,
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(String name,
String interval,
String timeout,
String wait)
Wait for a variable to be created.
|
int |
waitForUpdate(Rectangle area,
String extent,
boolean cumulative,
String timeout,
String wait)
Wait until the remote desktop refreshes the screen or its particular area.
|
int |
waitForUpdate(Rectangle area,
String extent,
String timeout)
Wait until the remote desktop refreshes the screen or its particular area.
|
int |
waitForUpdate(Rectangle area,
String extent,
String timeout,
String wait)
|
int |
waitForUpdate(String extent,
String timeout)
Wait until the remote desktop refreshes the whole screen.
|
int |
warning(String text)
|
int |
warning(String text,
File image)
Add a warning to be picked up by a report provider.
|
callByName, getContext, getDocument, 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, toStringpublic void test()
JavaTestScript interface.
Override this method with your own test code to create a Java test
script.public TestWrapper getRootWrapper()
TestWrapper.public int connect(String host, String user, String password, Map<String,Object> params, boolean force) throws 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.
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.IOException - if an I/O error happens during client-server communication.public int connect(String host, String user, String password, String params, String paramSeparator, boolean force) throws 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:
connect("localhost", null, null, false) will attempt to connect
to the RFB (VNC) server running on the default port 5900 of the local system.
As no password is provided, the server is expected to require no authentication.connect("rfb://localhost:5901", null, "welcome", false) will attempt to connect
to the RFB (VNC) server running on the port 5901 of the local system. This is a typical setup
on Linux/Unix where the default port of 5900 is occupied by the system X-server.
The host string can be in this case also specified as "localhost:1" or "localhost::5901".
As a password is provided, the client will use it to authenticate if the server requests it. User
name may be null because RFB requires just a password.connect("java://192.168.1.1:1099", null, null, false) will connect
to the display of the host with IP address 192.168.1.1 through the Java
native client using RMI. The host machine must have Java installed and it
must be executing T-Plan Robot Enterprise in the Java server mode. See the Java
client documentation for more.connect("java://localhost", null, null, false) will connect
to the local system display (meaning the very same desktop you see on your
screen or other display device) through the Java native client.connect("rdp://192.168.1.1:1234", "Administrator", "welcome", true) will connect
to an RDP server running on port 1234 of the system with IP address 192.168.1.1.
If T-Plan Robot Enterprise is already connected to the given system, the connection is
terminated and the application reconnects because the force
is set to true. The server is expected to require a user name and plain password
authentication. Note that this example is just illustrative because RDP is not
yet directly supoported..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.IOException - if an I/O error happens during client-server communication.public int connect(String host, String password, boolean force, String iosDevice) throws IOException
Connect to an iOS device. The method provides access to functionality of the
Connect scripting language command. The host argument
must be a valid URL in form of <apple>://<host_or_IP>[:<port>].
For more information on the host string format see documentation of the
iOS Mirror connection.
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.
For connection examples see the Automation chapter of the iOS Mirror documentation.
host - host connection URI. It can not be null. See the method
description for information about its format.password - password for plain text password authentication. It is used only
for VNC connections.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.iosDevice - name of the iOS device. When this parameter is populated the
command will connect over the Lightning USB cable. If the it is null it will
fall back to the mirror app screen transfer.IOException - if an I/O error happens during client-server communication.public int connect(String adbSerialNo, String screen, boolean force) throws IOException
Connect to an Android device or simulator using the Android Over ADB
connection. The method provides access to functionality of the
Connect scripting language command where the URL
is like adb://[number] where [number] is either
the "default" keyword or a valid Android device serial number.
adbSerialNo - the Android device serial No. To fall back to the
first discovered device connected to the USB use null or an empty string
or the "default" keyword. The argument may be either the serial No. or
the full connect string of adb://[number].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.screen - the screen transfer method:"adb" is the default screen transfer through the ADB's
screenshot functionality. It is usually slow but features the best compatibility
across devices."minicap" is the top performance screen mirror introduced
in the 5.0.6 release."mirror" is the legacy screen transfer through the Stream
Screen Mirroring application.adb.IOException - if an I/O error happens during client-server communication.public int connect()
throws IOException
Connect to the local desktop. If the local environment has multiple screens (displays)
it will connect to all of them. The method provides access to functionality of the
Connect scripting language command where the URL is the local desktop
one (java://localhost).
IOException - if an I/O error happens during client-server communication.public int connect(int screen,
boolean force)
throws IOException
Connect to the local desktop. The method provides access to functionality of the
Connect scripting language command where the URL is the local desktop
one (java://localhost).
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.screen - the screen ordinary number to connect to (starting from 1)
or a number equal to or lower than zero to connect to all screens.IOException - if an I/O error happens during client-server communication.public int connect(int screen)
throws IOException
Connect to the local desktop. The method provides access to functionality of the
Connect scripting language command where the URL is the local desktop
one (java://localhost).
screen - the screen ordinary number to connect to (starting from 1)
or a number equal to or lower than zero to connect to all screens.IOException - if an I/O error happens during client-server communication.public int connect(String host, String user, String password, boolean force) throws 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.
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.IOException - if an I/O error happens during client-server communication.public int connect(String host, String password) throws 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.
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.IOException - if an I/O error happens during client-server communication.public int connect(String host, boolean force) throws 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.
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.IOException - if an I/O error happens during client-server communication.public int connect(String host) throws 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.
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.IOException - if an I/O error happens during client-server communication.public int connect(String deviceName, File iosApplication, boolean startAtHomeScreen, boolean force) throws IOException
Connect to an iOS device through the "iOS over Xcode" connection. This
requires that Robot runs on a Mac with a local Xcode installation while the
iOS device is connected to the Mac though the Lightning USB cable.
The method provides access to functionality of the
Connect scripting language command. The host argument
must be a valid URL in form of <apple>://<host_or_IP>[:<port>].
For more information on the host string format see documentation of the
iOS over Xcode connection.
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.
iosApplication - path to the tested application stored on the local Mac machine.
It may be either a .ipa file or an .app folder.startAtHomeScreen - the value of true will push the app to the background immediately
after the connection gets established to give you access to the home screen.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.deviceName - name of the iOS device.IOException - if an I/O error happens during client-server communication.public int connect(String deviceName, File wdaPath, File iosApplication, boolean forceUSB, boolean force) throws IOException
Connect to an iOS device through the "iOS over Xcode" connection. This
requires that Robot runs on a Mac with a local Xcode installation while the
iOS device is connected to the Mac though the Lightning USB cable.
The method provides access to functionality of the
Connect scripting language command. The host argument
must be a valid URL in form of <apple>://<host_or_IP>[:<port>].
For more information on the host string format see documentation of the
iOS over Xcode connection.
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.
iosApplication - optional path to the tested application stored on the local Mac machine.
It may be either a .ipa file or an .app folder.wdaPath - path to the WebDriverAgent application (mandatory).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.forceUSB - the value of "true" will force tunneling of the network
connection through the USB cable. This allows to connect to devices which
are not connected to network or to a different one than Robot. It can be
also used to avoid transfer of data over the network, for example when
the network connection is slow or unreliable. Supported since 6.1.2.deviceName - name of the iOS device (mandatory).IOException - if an I/O error happens during client-server communication.public int connect(String deviceName, File wdaPath, File iosApplication, boolean force) throws IOException
Connect to an iOS device through the "iOS over Xcode" connection. This
requires that Robot runs on a Mac with a local Xcode installation while the
iOS device is connected to the Mac though the Lightning USB cable.
The method provides access to functionality of the
Connect scripting language command. The host argument
must be a valid URL in form of <apple>://<host_or_IP>[:<port>].
For more information on the host string format see documentation of the
iOS over Xcode connection.
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.
iosApplication - optional path to the tested application stored on the local Mac machine.
It may be either a .ipa file or an .app folder.wdaPath - path to the WebDriverAgent application (mandatory).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.deviceName - name of the iOS device (mandatory).IOException - if an I/O error happens during client-server communication.public int connect(String host, String user, String password, Dimension screenSize, boolean force) throws IOException
Connect to an RDP server using the specified user and password.
host - host connection URI, for example "rdp://myserver.com". 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 - the user name.password - the password.screenSize - the desired RDP screen size. To fall back to the
default size use null or an empty dimension (width or height is 0).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.IOException - if an I/O error happens during client-server
communication.public int disconnect()
throws 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.
IOException - if an I/O error happens during the connection shutdown.public int mouseEvent(String action, int modifiers, int button, Point from, Point to, int count, String wait) throws 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.
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_MASKbutton - 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.IOException - if an I/O error happens during client-server
communication or if no desktop is connected.public int mousePress(int button,
int modifiers,
Point to,
String wait)
throws IOException
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.modifiers - modifier mask as specified in the
InputEvent. For example, to specify Ctrl+Alt use
InputEvent.CTRL_MASK | InputEvent.ALT_MASKto - location to apply the press to. 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.IOException - if an I/O error happens during client-server
communication or if no desktop is connected.public int mousePress(Point to, String wait) throws IOException
to - location to apply the press to. 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.IOException - if an I/O error happens during client-server
communication or if no desktop is connected.public int mouseRightPress(Point to, String wait) throws IOException
to - location to apply the press to. 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.IOException - if an I/O error happens during client-server
communication or if no desktop is connected.public int mouseRelease(int button,
int modifiers,
Point to,
String wait)
throws IOException
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.modifiers - modifier mask as specified in the
InputEvent. For example, to specify Ctrl+Alt use
InputEvent.CTRL_MASK | InputEvent.ALT_MASKto - location to apply the release to. 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.IOException - if an I/O error happens during client-server
communication or if no desktop is connected.public int mouseRelease(Point to, String wait) throws IOException
to - location to apply the release to. 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.IOException - if an I/O error happens during client-server
communication or if no desktop is connected.public int mouseRightRelease(Point to, String wait) throws IOException
to - location to apply the release to. 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.IOException - if an I/O error happens during client-server
communication or if no desktop is connected.public int mouseMove(Point to, String wait) throws 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.
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.IOException - if an I/O error happens during client-server communication.public int mouseMove(Point to, int modifiers, String wait) throws 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.
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_MASKwait - 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.IOException - if an I/O error happens during client-server communication.public int mouseMove(Point to) throws 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.
to - location or target point of the mouse event. If the argument is null,
it defaults to the current desktop mouse pointer position.IOException - if an I/O error happens during client-server communication.public int mouseMove(int x,
int y,
String wait)
throws 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.
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.IOException - if an I/O error happens during client-server communication.public int mouseMove(int x,
int y,
int modifiers,
String wait)
throws 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.
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_MASKwait - 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.IOException - if an I/O error happens during client-server communication.public int mouseMove(int x,
int y)
throws 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.
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.IOException - if an I/O error happens during client-server communication.public int mouseClick(Point to, int modifiers, int button, int count, String wait) throws 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.
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_MASKbutton - 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.IOException - if an I/O error happens during client-server communication.public int mouseClick(Point to, int count, String wait) throws 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.
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.IOException - if an I/O error happens during client-server communication.public int mouseClick(Point to, int count) throws 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.
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.IOException - if an I/O error happens during client-server communication.public int mouseClick(Point to, String wait) throws 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.
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.IOException - if an I/O error happens during client-server communication.public int mouseClick(Point to) throws 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.
to - location or target point of the mouse event. If the argument is null,
it defaults to the current desktop mouse pointer position.IOException - if an I/O error happens during client-server communication.public int mouseClick(int x,
int y,
int count,
String wait)
throws 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.
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.IOException - if an I/O error happens during client-server communication.public int mouseClick(int x,
int y,
int count)
throws 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.
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.IOException - if an I/O error happens during client-server communication.public int mouseClick(int x,
int y)
throws 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.
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.IOException - if an I/O error happens during client-server communication.public int mouseRightClick(Point to, int modifiers, int count, String wait) throws 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.
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_MASKcount - 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.IOException - if an I/O error happens during client-server communication.public int mouseRightClick(Point to, int count, String wait) throws 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.
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.IOException - if an I/O error happens during client-server communication.public int mouseRightClick(Point to, int count) throws 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.
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.IOException - if an I/O error happens during client-server communication.public int mouseRightClick(Point to) throws 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.
to - mouse click point. If the argument is null,
it defaults to the current desktop mouse pointer position.IOException - if an I/O error happens during client-server communication.public int mouseRightClick(int x,
int y,
int count,
String wait)
throws 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.
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.IOException - if an I/O error happens during client-server communication.public int mouseRightClick(int x,
int y,
int count)
throws 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.
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.IOException - if an I/O error happens during client-server communication.public int mouseRightClick(int x,
int y)
throws 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.
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.IOException - if an I/O error happens during client-server communication.public int mouseDoubleClick(Point to, String wait) throws 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.
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.IOException - if an I/O error happens during client-server communication.public int mouseDoubleClick(Point to) throws 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.
to - mouse click point. If the argument is null,
it defaults to the current desktop mouse pointer position.IOException - if an I/O error happens during client-server communication.public int mouseDoubleClick(int x,
int y,
String wait)
throws 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.
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.IOException - if an I/O error happens during client-server communication.public int mouseDoubleClick(int x,
int y)
throws 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.
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.IOException - if an I/O error happens during client-server communication.public int mouseDrag(Point from, Point to, int modifiers, int button, String wait) throws 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.
modifiers - modifier mask as specified in the InputEvent.
For example, to specify Ctrl+Alt use InputEvent.CTRL_MASK | InputEvent.ALT_MASKbutton - 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.IOException - if an I/O error happens during client-server communication.public int mouseRightDrag(Point from, Point to, int modifiers, String wait) throws 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.
modifiers - modifier mask as specified in the InputEvent.
For example, to specify Ctrl+Alt use InputEvent.CTRL_MASK | InputEvent.ALT_MASKfrom - 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.IOException - if an I/O error happens during client-server communication.public int mouseWheelUp(Point to, int modifiers, int count, String wait) throws 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.
modifiers - modifier mask as specified in the InputEvent.
For example, to specify Ctrl+Alt use InputEvent.CTRL_MASK | InputEvent.ALT_MASKto - 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.IOException - if an I/O error happens during client-server communication.public int mouseWheelUp(int x,
int y,
int modifiers,
int count,
String wait)
throws 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.
modifiers - modifier mask as specified in the InputEvent.
For example, to specify Ctrl+Alt use InputEvent.CTRL_MASK | InputEvent.ALT_MASKx - 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.IOException - if an I/O error happens during client-server communication.public int mouseWheelDown(Point to, int modifiers, int count, String wait) throws 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.
modifiers - modifier mask as specified in the InputEvent.
For example, to specify Ctrl+Alt use InputEvent.CTRL_MASK | InputEvent.ALT_MASKto - 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.IOException - if an I/O error happens during client-server communication.public int mouseWheelDown(int x,
int y,
int modifiers,
int count,
String wait)
throws 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.
modifiers - modifier mask as specified in the InputEvent.
For example, to specify Ctrl+Alt use InputEvent.CTRL_MASK | InputEvent.ALT_MASKx - 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.IOException - if an I/O error happens during client-server communication.public int mouseEvent(String action, Point center, int start, int end, int count, String wait) throws 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.
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.IOException - if an I/O error happens during client-server
communication or if no desktop is connected.public int mousePinch(Point center, int start, int end, int count, String wait) throws 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.
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.IOException - if an I/O error happens during client-server
communication or if no desktop is connected.public int mousePinch(int count,
String wait)
throws 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.
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.IOException - if an I/O error happens during client-server
communication or if no desktop is connected.public int mousePinch()
throws 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.
IOException - if an I/O error happens during client-server
communication or if no desktop is connected.public int mouseZoom(Point center, int start, int end, int count, String wait) throws 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.
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.IOException - if an I/O error happens during client-server
communication or if no desktop is connected.public int mouseZoom(int count,
String wait)
throws 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.
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.IOException - if an I/O error happens during client-server
communication or if no desktop is connected.public int mouseZoom()
throws 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.
IOException - if an I/O error happens during client-server
communication or if no desktop is connected.public int type(String text, int count, int location, String wait) throws 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.
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.IOException - if an I/O error happens during client-server communication.public int type(String text, int count, String wait) throws 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.
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.IOException - if an I/O error happens during client-server communication.public int type(String text, String wait) throws 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.
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.IOException - if an I/O error happens during client-server communication.public int type(String text) throws 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.
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.IOException - if an I/O error happens during client-server communication.public int typeLine(String text, int count, int location, String wait) throws 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.
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.IOException - if an I/O error happens during client-server communication.public int typeLine(String text, int count, String wait) throws 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.
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.IOException - if an I/O error happens during client-server communication.public int typeLine(String text, String wait) throws 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.
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.IOException - if an I/O error happens during client-server communication.public int typeLine(String text) throws 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.
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.IOException - if an I/O error happens during client-server communication.public int paste(String text, int count, String wait) throws IOException
Paste text on the current desktop. The method provides access to functionality of the Paste scripting language command.
Instead of typing the text character by character on the keyboard the method copies it into the clipboard and simulates pressing of Ctrl+V (Command+V on Mac OS X) to trigger the system Paste action. This is much faster than typing the text through Type/Typeline.
The command targets connections which support clipboard operations, such as the Local Desktop one. For other connections the command silently falls back to the Type command functionality.
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.
text - a text to paste. 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.count - how many times to repeat pasting (typing) of the text.
The default value is 1 (paste once).wait - how long to wait after the text is pasted. 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.IOException - if an I/O error happens during client-server communication.public int paste(String text) throws IOException
Paste text on the current desktop. The method provides access to functionality of the Paste scripting language command.
Instead of typing the text character by character on the keyboard the method copies it into the clipboard and simulates pressing of Ctrl+V (Command+V on Mac OS X) to trigger the system Paste action. This is much faster than typing the text through Type/Typeline.
The command targets connections which support clipboard operations, such as the Local Desktop one. For other connections the command silently falls back to the Type command functionality.
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.
text - a text to paste. 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.IOException - if an I/O error happens during client-server communication.public int press(String key, int location, int count, Boolean release, String delay, String wait) throws 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.
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.IOException - if an I/O error happens during client-server communication.public int press(String key, int location, int count, String delay, String wait) throws 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.
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.IOException - if an I/O error happens during client-server communication.public int press(String key, int location, int count, String wait) throws 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.
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.IOException - if an I/O error happens during client-server communication.public int press(String key, String wait, int count) throws 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.
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.IOException - if an I/O error happens during client-server communication.public int press(char c,
int location,
int count,
String delay,
String wait)
throws 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.
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.IOException - if an I/O error happens during client-server communication.public int press(char c,
int location,
int count,
String wait)
throws 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.
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.IOException - if an I/O error happens during client-server communication.public int press(String key, int location, String wait) throws 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.
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.IOException - if an I/O error happens during client-server communication.public int press(String key, int location) throws 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.
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.IOException - if an I/O error happens during client-server communication.public int press(String key, String wait) throws 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.
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.IOException - if an I/O error happens during client-server communication.public int press(String key) throws 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.
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.IOException - if an I/O error happens during client-server communication.public int wait(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.
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.public int screenshot(File file, String description, Rectangle area, Image[] templates, float passRate, Rectangle cmpArea, boolean removeBg, String bgColor, Integer minAlpha, Integer rgbTolerance, boolean drawResults, boolean drawDiff) throws 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.
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.IOException - when an I/O error occurs.public int screenshot(File file, String description, Rectangle area, Image[] templates, float passRate, Rectangle cmpArea, boolean removeBg, String bgColor, Integer minAlpha, Integer rgbTolerance, boolean drawResults) throws 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.
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.IOException - when an I/O error occurs.public int screenshot(File file, String description, Rectangle area, Image[] templates, float passRate, Rectangle cmpArea, boolean removeBg, String bgColor, Integer minAlpha, boolean drawResults) throws 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.
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.IOException - when an I/O error occurs.public int screenshot(File file, String description, Rectangle area, Image[] templates, String method, String methodParams, float passRate, Rectangle cmpArea, boolean drawResults, boolean drawDiff) throws 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.
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.IOException - when an I/O error occurs.public int screenshot(File file, String description, Rectangle area, Image[] templates, String method, String methodParams, float passRate, Rectangle cmpArea, boolean drawResults) throws 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.
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.IOException - when an I/O error occurs.public int screenshot(File file, String description, Rectangle area, Image[] templates, String method, String methodParams, float passRate, Rectangle cmpArea) throws 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.
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.IOException - when an I/O error occurs.public int screenshot(File file, String description, Rectangle area, File[] templates, String method, String methodParams, float passRate, Rectangle cmpArea, Integer rgbTolerance, boolean drawResults, boolean drawDiff) throws 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.
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.IOException - when an I/O error occurs.public int screenshot(File file, String description, Rectangle area, File[] templates, String method, String methodParams, float passRate, Rectangle cmpArea, Integer rgbTolerance, boolean drawResults) throws 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.
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.IOException - when an I/O error occurs.public int screenshot(File file, String description, Rectangle area, File[] templates, float passRate, Rectangle cmpArea, String sort, boolean drawResults, boolean drawDiff) throws 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.
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)."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.IOException - when an I/O error occurs.public int screenshot(File file, String description, Rectangle area, File[] templates, float passRate, Rectangle cmpArea, String sort, float[] scale, boolean drawResults, boolean drawDiff) throws 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.
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)."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:
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.IOException - when an I/O error occurs.public int screenshot(File file, String description, Rectangle area, File[] templates, float passRate, Rectangle cmpArea, String sort, boolean drawResults) throws 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.
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)."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.IOException - when an I/O error occurs.public int screenshot(File file, String description, Rectangle area, Rectangle cmpArea, String language, String text, String pattern) throws 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.
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.IOException - when an I/O error occurs.public int screenshot(File file, String description, Rectangle area, Rectangle cmpArea, String language, float scale, String text, int distance, String pattern) throws 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.
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.IOException - when an I/O error occurs.public int screenshot(File file, String description, Rectangle area, Rectangle cmpArea, String language, float scale, String text, int distance, String pattern, int mode, int filter, int fontSize) throws 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.
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:"-psm 3" CLI switch). This value is compatible with
the Robot releases prior to 3.5.-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."-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:
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.
IOException - when an I/O error occurs.public int screenshot(File file, String description, Rectangle area, File[] templates, float passRate, Rectangle cmpArea, String text, int distance, String pattern, boolean drawResults) throws 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.
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.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.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.IOException - on an I/O error (can't read an image file and/or
can't get image of the remote desktop).public int screenshot(File file, String description, Rectangle area, File[] templates, String method, String methodParams, float passRate, Rectangle cmpArea, boolean drawResults, boolean drawDiff) throws 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.
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.IOException - when an I/O error occurs.public int screenshot(File file, String description, Rectangle area, File[] templates, String method, String methodParams, float passRate, Rectangle cmpArea, boolean drawResults) throws 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.
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.IOException - when an I/O error occurs.public int screenshot(File file, String description, Rectangle area, File[] templates, float passRate, Rectangle cmpArea, boolean removeBg, String bgColor, Integer minAlpha, Integer rgbTolerance, boolean drawResults, boolean drawDiff) throws 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.
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.IOException - when an I/O error occurs.public int screenshot(File file, String description, Rectangle area, File[] templates, float passRate, Rectangle cmpArea, boolean removeBg, String bgColor, Integer minAlpha, Integer rgbTolerance, boolean drawResults) throws 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.
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.IOException - when an I/O error occurs.public int screenshot(File file, String description, Rectangle area, File[] templates, float passRate, Rectangle cmpArea, boolean removeBg, String bgColor, Integer minAlpha, boolean drawResults) throws 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.
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.IOException - when an I/O error occurs.public int screenshot(File file, String description, Rectangle area, File[] templates, String method, String methodParams, float passRate, Rectangle cmpArea) throws 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.
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.IOException - when an I/O error occurs.public int screenshot(File file, String description, Rectangle area, File template, float passRate, Rectangle cmpArea, Color color, Color[] bridgeColors, Integer rgbTolerance, Integer rotations, Boolean draw, Boolean clear, Dimension min, Dimension max) throws 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.
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.min - the minimum object size. The dimension may contain zero
width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a minimum
width of 30 pixels use new Dimension(30, -1). To set off
filtering by minimum size use null.max - the maximum object size. The dimension may contain zero
width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a maximum
width of 100 pixels use new Dimension(100, -1). To set off
filtering by maximum size use null.IOException - when an I/O error occurs.public int screenshot(File file, String description, Rectangle area, File template, float passRate, Rectangle cmpArea, Color color, Color[] bridgeColors, Integer rgbTolerance, Integer rotations, Boolean draw, Boolean clear) throws 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.
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.IOException - when an I/O error occurs.public int screenshot(File file, String description, Rectangle area, File[] templates, String method, float passRate, Rectangle cmpArea) throws 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.
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.IOException - when an I/O error occurs.public int screenshot(File file, String description, Rectangle area, File[] templates, String method, float passRate) throws 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.
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.IOException - when an I/O error occurs.public int screenshot(File file, String description, Rectangle area, File[] templates, String method, float passRate, Integer rgbTolerance) throws 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.
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.
IOException - when an I/O error occurs.public int screenshot(File file, String description, Rectangle area) throws 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.
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.IOException - when an I/O error occurs.public int screenshot(File file, String description) throws 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.
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.IOException - when an I/O error occurs.public int screenshot(File file, Rectangle area) throws 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.
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.IOException - when an I/O error occurs.public int screenshot(File file) throws 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.
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.IOException - when an I/O error occurs.public int sendMail(String server, String user, String security, String password, String from, String to, String cc, String bcc, String subject, String text, File[] attachments, boolean delayed, boolean debug) throws 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).
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.security - the security type (since 6.2.3). Supported values are
EmailConstants.SECURITY_NONE for anonymous SMTP servers,
EmailConstants.SECURITY_PASSWORD for plain password authentication
or one of EmailConstants.SECURITY_GOOGLE or
EmailConstants.SECURITY_MICROSOFT for OAuth2 authentication to GMail
or Outlook SMTP servers. If the parameter is null the method falls back
to either EmailConstants.SECURITY_NONE or
EmailConstants.SECURITY_PASSWORD depending on whether a password
is specified.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.cc - one or more CC recipient address(es) separated by comma (optional).
Supported since 5.0.3.bcc - one or more recipient address(es) separated by comma (optional).
Supported since 5.0.3.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 "<html>" (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.delayed - when set to true the mail will be sent until after the calling
script finishes. Supported since 4.1.3.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.IOException - when an I/O error occurs.public int sendMail(String server, String user, String password, String from, String to, String cc, String bcc, String subject, String text, File[] attachments, boolean delayed, boolean debug) throws 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).
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.cc - one or more CC recipient address(es) separated by comma (optional).
Supported since 5.0.3.bcc - one or more recipient address(es) separated by comma (optional).
Supported since 5.0.3.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 "<html>" (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.delayed - when set to true the mail will be sent until after the calling
script finishes. Supported since 4.1.3.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.IOException - when an I/O error occurs.public int sendMail(String server, String user, String password, String from, String to, String subject, String text, File[] attachments, boolean delayed, boolean debug) throws 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).
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 "<html>" (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.delayed - when set to true the mail will be sent until after the calling
script finishes. Supported since 4.1.3.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.IOException - when an I/O error occurs.public int sendMail(String server, String user, String password, String from, String to, String subject, String text, File[] attachments, boolean debug) throws 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).
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 "<html>" (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.IOException - when an I/O error occurs.public int sendMail(String password, String subject, String text, File[] attachments, boolean debug) throws 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.
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 "<html>" (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.IOException - when an I/O error occurs.public int sendMail(String password, String subject, String text) throws 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.
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 "<html>" (not case sensitive), the content type is
set to "text/html". Otherwise the mail body is sent as plain text ("text/plain").IOException - when an I/O error occurs.public int sendMail(String subject, String text, File[] attachments) throws 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.
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 "<html>" (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.IOException - when an I/O error occurs.public int sendMail(String subject, String text) throws 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.
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 "<html>" (not case sensitive), the content type is
set to "text/html". Otherwise the mail body is sent as plain text ("text/plain").IOException - when an I/O error occurs.public int exec(String command, OutputStream out, int count, String wait) throws IOException
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.IOException - if an I/O error happens during client-server communication.public int exec(String command, OutputStream out, boolean nowait, int count, String wait) throws IOException
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.IOException - if an I/O error happens during client-server communication.public int exec(String command, OutputStream out) throws IOException
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).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.IOException - if an I/O error happens during client-server communication.public int exec(String command, Writer out, int count, String wait) throws IOException
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.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.IOException - if an I/O error happens during client-server communication.public int exec(String command, Writer out, boolean nowait, int count, String wait) throws IOException
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.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.IOException - if an I/O error happens during client-server communication.public int exec(String command, Writer out) throws IOException
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).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.IOException - if an I/O error happens during client-server communication.public int exec(String command, String wait) throws IOException
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).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.IOException - if an I/O error happens during client-server communication.public int exec(String command, boolean nowait) throws IOException
exec(java.lang.String, java.io.OutputStream, int, java.lang.String)
method to execute a command without any further options.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.IOException - if an I/O error happens during client-server communication.public int exec(String command) throws IOException
exec(java.lang.String, java.io.OutputStream, int, java.lang.String)
method to execute a command without any further options.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.IOException - if an I/O error happens during client-server communication.public int execBrowser(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.
url - a document URL to open.public int report(File out, String provider, String description, String scope) throws 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.
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.IOException - if an I/O error happens during client-server communication.public int report(File[] out, String description) throws IOException
Start the Enterprise 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.
out - a file to save the report to.description - report description.IOException - if an I/O error happens during client-server communication.public int report(File[] out, String description, boolean onExit) throws IOException
Start the Enterprise 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.
out - a file to save the report to.description - report description.onExit - the value of true will not refresh the report on the fly
but create it just twice, when the method gets called and then after the
script gets finished. This mode is recommended for large scripts
creating multiple reportable objects where frequent report refreshing may
lead to degraded performance. The default value is false. Supported since
v4.1.3.IOException - if an I/O error happens during client-server communication.public int report(File out, String provider, String description) throws 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.
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.IOException - if an I/O error happens during client-server communication.public int report(File out, String description) throws 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.
out - a file to save the report to.description - report description.IOException - if an I/O error happens during client-server communication.public int report(File out, String description, boolean onExit) throws IOException
Start the enterprise 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.
out - a file to save the report to.description - report description.onExit - the value of true will not refresh the report on the fly
but create it just twice, when the method gets called and then after the
script gets finished. This mode is recommended for large scripts
creating multiple reportable objects where frequent report refreshing may
lead to degraded performance. The default value is false. Supported since
v4.1.3.IOException - if an I/O error happens during client-server communication.public int report(File out) throws 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.
out - a file to save the report to.IOException - if an I/O error happens during client-server communication.public int compareTo(Image[] templates, ImageComparisonModule module, float passRate, Rectangle cmpArea, Boolean removeBg, Color bgColor, Integer minAlpha, Integer rgbTolerance) throws 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.
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.
IOException - on an I/O error (can't read file and/or
can't get image of the remote desktop).public int compareTo(Image template, Float passRate, Rectangle cmpArea, Color color, Color[] bridgeColors, Integer rgbTolerance, Integer rotations, Boolean draw, Boolean clear, Dimension min, Dimension max) throws 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.
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.min - the minimum object size. The dimension may contain zero
width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a minimum
width of 30 pixels use new Dimension(30, -1). To set off
filtering by minimum size use null.max - the maximum object size. The dimension may contain zero
width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a maximum
width of 100 pixels use new Dimension(100, -1). To set off
filtering by maximum size use null.IOException - on an I/O error (can't read file and/or
can't get image of the remote desktop).public int compareTo(Image template, Float passRate, Rectangle cmpArea, Color color, Color[] bridgeColors, Integer rgbTolerance, Integer rotations, Boolean draw, Boolean clear) throws 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.
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.IOException - on an I/O error (can't read file and/or
can't get image of the remote desktop).public int compareTo(File template, Float passRate, Rectangle cmpArea, Color color, Color[] bridgeColors, Integer rgbTolerance, Integer rotations, Boolean draw, Boolean clear, Dimension min, Dimension max) throws 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.
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.min - the minimum object size. The dimension may contain zero
width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a minimum
width of 30 pixels use new Dimension(30, -1). To set off
filtering by minimum size use null.max - the maximum object size. The dimension may contain zero
width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a maximum
width of 100 pixels use new Dimension(100, -1). To set off
filtering by maximum size use null.IOException - on an I/O error (can't read file and/or
can't get image of the remote desktop).public int compareTo(File template, Float passRate, Rectangle cmpArea, Color color, Color[] bridgeColors, Integer rgbTolerance, Integer rotations, Boolean draw, Boolean clear) throws 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.
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.IOException - on an I/O error (can't read file and/or
can't get image of the remote desktop).public int compareTo(Image[] templates, ImageComparisonModule module, float passRate, Rectangle cmpArea, Boolean removeBg, Color bgColor, Integer minAlpha) throws 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.
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.IOException - on an I/O error (can't read file and/or
can't get image of the remote desktop).public int compareTo(Image[] templates, ImageComparisonModule module, float passRate, Rectangle cmpArea, Integer rgbTolerance) throws 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.
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.
IOException - on an I/O error (can't read file and/or
can't get image of the remote desktop).public int compareTo(Image[] templates, ImageComparisonModule module, float passRate, Rectangle cmpArea) throws 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 image 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.
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.IOException - on an I/O error (can't read file and/or
can't get image of the remote desktop).public int compareTo(File[] templates, float passRate, Rectangle cmpArea, boolean removeBg, String bgColor, Integer minAlpha, Integer rgbTolerance) throws 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.
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.
IOException - on an I/O error (can't read file and/or
can't get image of the remote desktop).public int compareTo(File[] templates, float passRate, Rectangle cmpArea, boolean removeBg, String bgColor, Integer minAlpha) throws 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.
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.IOException - on an I/O error (can't read file and/or
can't get image of the remote desktop).public int compareTo(File[] templates, float passRate, Rectangle cmpArea, String sort) throws 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.
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)."best" one.IOException - on an I/O error (can't read file and/or
can't get image of the remote desktop).public int compareTo(File[] templates, float passRate, Rectangle cmpArea, String sort, float[] scale) throws 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.
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)."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:
IOException - on an I/O error (can't read file and/or
can't get image of the remote desktop).public int compareTo(Rectangle cmpArea, String language, String text, String pattern) throws 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.
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.IOException - on an I/O error (can't read file and/or
can't get image of the remote desktop).public int compareTo(Rectangle cmpArea, String language) throws 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.
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.IOException - on an I/O error (can't read file and/or
can't get image of the remote desktop).public int compareTo(Rectangle cmpArea, String language, float scale, String text, int distance, String pattern) throws 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.
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.IOException - on an I/O error (can't read file and/or
can't get image of the remote desktop).public int compareTo(Rectangle cmpArea, String language, float scale, String text, int distance, String pattern, int mode, int filter, int fontSize) throws 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.
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:"-psm 3" CLI switch). This value is compatible with
the Robot releases prior to 3.5.-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."-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.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.IOException - on an I/O error (can't read file and/or
can't get image of the remote desktop).public int compareTo(File[] templates, String method, String methodParams, float passRate, Rectangle cmpArea) throws 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.
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.IOException - on an I/O error (can't read file and/or
can't get image of the remote desktop).public int compareTo(File[] templates, String method, float passRate, Rectangle cmpArea) throws 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.
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.IOException - on an I/O error (can't read file and/or
can't get image of the remote desktop).public int compareTo(File[] templates, String method, float passRate, Rectangle cmpArea, Integer rgbTolerance) throws 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.
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.
IOException - on an I/O error (can't read file and/or
can't get image of the remote desktop).public int compareTo(File[] templates, String method, float passRate) throws 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.
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).IOException - on an I/O error (can't read file and/or
can't get image of the remote desktop).public int compareTo(File[] templates, String method, float passRate, Integer rgbTolerance) throws 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.
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.
IOException - on an I/O error (can't read file and/or
can't get image of the remote desktop).public int compareTo(File[] templates, float passRate) throws 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();
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).IOException - on an I/O error (can't read file and/or
can't get image of the remote desktop).public int compareTo(File[] templates, float passRate, Rectangle cmpArea, String text, int distance, String pattern) throws 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.
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 - 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.IOException - on an I/O error (can't read an image file and/or
can't get image of the remote desktop).public int compareTo(File[] template, String method) throws 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.
template - list of template images (File 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.IOException - on an I/O error (can't read file and/or
can't get image of the remote desktop).public int compareTo(File[] templates) throws 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();
templates - list of template images (Image instances).IOException - on an I/O error (can't read file and/or
can't get image of the remote desktop).public int compareTo(String name) throws IOException
Test out if a variable exists. It is usually used with session variables created through the Varg command to synchronize the script with other script(s) running in parallel. The method provides access to functionality of the Compareto scripting language command with the comparison method name fixed to "variable".
name - the variable name.IOException - the exception is declared but never thrown
because the 'variable' method doesn't rely on a desktop connection.public int pause(String reason) throws 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.
reason - an optional description of why the script was paused. It may be picked
up by report providers to display it in the report.IOException - if an I/O error happens during client-server communication.public int pause()
throws 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.
IOException - if an I/O error happens during client-server communication.public int exit(Integer exitCode, String description) throws IOException
Set the test script exit status. The method can be used only to record the argument exit code and the optional description to the script result set for reporting purposes.
To exit a script execution instantly (scope=process)
use the System.exit(int) method instead. Alternatively where
termination of the JVM is not desired throw an exception and catch
it at the end of the test() method. Other exit scopes such as
procedure, block and file must be
implemented indirectly using Java language capabilities.
Besides recording of the data the method also sets the internal stop
flag which is observed by all commands. Unless the script is terminated
through System.exit(int) or an exception the Java code
will continue to execute but all automation methods defined in this
class will do nothing until the end of the test script code is reached.
exitCode - numeric exit code to be recorded to the test results.description - optional description which will be saved to the test
results in form of a variable and it will be displayed in the report.IOException - on an I/O error. Declared but rarely thrown
because this method doesn't do any I/O operations.public int exit(Integer exitCode) throws IOException
Set the test script exit status. The method can be used only to record the argument exit code to the script result set for reporting purposes.
To exit a script execution instantly (scope=process)
use the System.exit(int) method instead. Alternatively where
termination of the JVM is not desired throw an exception and catch
it at the end of the test() method. Other exit scopes such as
procedure, block and file must be
implemented indirectly using Java language capabilities.
Besides recording of the data the method also sets the internal stop
flag which is observed by all commands. Unless the script is terminated
through System.exit(int) or an exception the Java code
will continue to execute but all automation methods defined in this
class will do nothing until the end of the test script code is reached.
exitCode - numeric exit code to be recorded to the test results.IOException - on an I/O error. Declared but rarely thrown
because this method doesn't do any I/O operations.public int warning(String text, 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.
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.public int warning(String text) throws 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.
text - warning text.IOException - the exception is declared but never thrown because
the command doesn't deal with the I/O.public int waitForBell(int count,
String timeout,
String wait)
throws IOException
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).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.public int waitForBell(String timeout, String wait) throws IOException
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).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.public int waitForBell(String timeout) throws IOException
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).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.public int waitForUpdate(Rectangle area, String extent, boolean cumulative, String timeout, String wait) throws IOException
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).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.public int waitForUpdate(Rectangle area, String extent, String timeout, String wait) throws IOException
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.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).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.public int waitForUpdate(Rectangle area, String extent, String timeout) throws IOException
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.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).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.public int waitForUpdate(String extent, String timeout) throws IOException
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.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).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.public int waitForMatch(Image[] templates, float passRate, String interval, Rectangle cmpArea, String timeout, boolean removeBg, String bgColor, Integer minAlpha, String wait) throws 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.
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).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.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.public int waitForMatch(Image[] templates, float passRate, String interval, Rectangle cmpArea, String timeout, boolean removeBg, String bgColor, Integer minAlpha, Integer rgbTolerance, String wait) throws 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.
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.
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.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.public int waitForMatch(String interval, Rectangle cmpArea, String timeout, String language, String text, String pattern, String wait) throws 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.
TesseractOCR
class documentation for details on how to install and configure Tesseract.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.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.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.public int waitForMatch(File[] templates, float passRate, Rectangle cmpArea, String interval, String timeout, String text, int distance, String pattern, String wait) throws 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.
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.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.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). 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).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).IOException - on an I/O error (can't read an image file and/or
can't get image of the remote desktop).public int waitForMatch(String interval, Rectangle cmpArea, String timeout, String language, float scale, String text, int distance, String pattern, String wait) throws 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.
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.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).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.public int waitForMatch(String interval, Rectangle cmpArea, String timeout, String language, float scale, String text, int distance, String pattern, int mode, int filter, int fontSize, String wait) throws 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.
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:"-psm 3" CLI switch). This value is compatible with
the Robot releases prior to 3.5.-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."-psm 8" CLI switch.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.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.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.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).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.public int waitForMatch(Image[] templates, float passRate, String interval, String method, String methodParams, Rectangle cmpArea, String timeout, String wait) throws 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).
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).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.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.public int waitForMatch(File[] templates, float passRate, String interval, Rectangle cmpArea, String timeout, boolean removeBg, String bgColor, Integer minAlpha, Integer rgbTolerance, String wait) throws 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.
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.
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.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.public int waitForMatch(File[] templates, float passRate, String interval, Rectangle cmpArea, String timeout, String sort, float[] scale, String wait) throws 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.
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 - the 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 value is null the command will wait forever until the required
condition (positive image comparison result) is met.wait - the time to wait after the component is found. 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).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)."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:
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.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.public int waitForMatch(File[] templates, float passRate, String interval, Rectangle cmpArea, String timeout, String sort, String wait) throws 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.
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)."best" one.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).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.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.public int waitForMatch(File[] templates, float passRate, String interval, Rectangle cmpArea, String timeout, boolean removeBg, String bgColor, Integer minAlpha, String wait) throws 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.
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).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.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.public int waitForMatch(File[] templates, float passRate, String interval, String method, String methodParams, Rectangle cmpArea, String timeout, String wait) throws 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).
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).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.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.public int waitForMatch(File template, float passRate, String interval, Rectangle cmpArea, String timeout, Color color, Color[] bridgeColors, Integer rgbTolerance, Integer rotations, Boolean draw, Boolean clear, Dimension min, Dimension max, String wait) throws 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.
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).min - the minimum object size. The dimension may contain zero or
negative width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a minimum
width of 30 pixels use new Dimension(30, -1). To set off
filtering by minimum size use null.max - the maximum object size. The dimension may contain zero or
negative width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a maximum
width of 100 pixels use new Dimension(100, -1). To set off
filtering by maximum size use null.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.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.public int waitForMatch(File template, float passRate, String interval, Rectangle cmpArea, String timeout, Color color, Color[] bridgeColors, Integer rgbTolerance, Integer rotations, Boolean draw, Boolean clear, String wait) throws 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.
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).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.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.public int waitForMatch(Image template, float passRate, String interval, Rectangle cmpArea, String timeout, Color color, Color[] bridgeColors, Integer rgbTolerance, Integer rotations, Boolean draw, Boolean clear, Dimension min, Dimension max, String wait) throws 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.
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).min - the minimum object size. The dimension may contain zero
width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a minimum
width of 30 pixels use new Dimension(30, -1). To set off
filtering by minimum size use null.max - the maximum object size. The dimension may contain zero
width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a maximum
width of 100 pixels use new Dimension(100, -1). To set off
filtering by maximum size use null.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.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.public int waitForMatch(Image template, float passRate, String interval, Rectangle cmpArea, String timeout, Color color, Color[] bridgeColors, Integer rgbTolerance, Integer rotations, Boolean draw, Boolean clear, String wait) throws 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.
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).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.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.public int waitForMatch(File[] templates, float passRate, String method, Rectangle cmpArea, String timeout, String wait) throws IOException
IOExceptionpublic int waitForMatch(File[] templates, float passRate, String method, String timeout) throws IOException
IOExceptionpublic int waitForMatch(File[] templates, String method, String timeout) throws IOException
IOExceptionpublic int waitForMatch(File[] templates, String timeout) throws IOException
IOExceptionpublic int waitForMatch(File[] templates) throws 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%.
templates - list of template images (File instances).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.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.public int waitForMatch(String name, String interval, String timeout, String wait) throws IOException
Wait for a variable to be created. Use with session variables created through the Varg command to synchronize the script with other script(s) running in parallel. The method provides access to functionality of the Waitfor scripting language command with the comparison method name fixed to "variable".
name - the variable name.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).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.IOException - the exception is declared but never thrown
because the 'variable' method doesn't rely on a desktop connection.public int waitForMismatch(Image[] templates, float passRate, String interval, Rectangle cmpArea, String timeout, boolean removeBg, String bgColor, Integer minAlpha, Integer rgbTolerance, String wait) throws 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.
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).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.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.public int waitForMismatch(File[] templates, float passRate, String interval, Rectangle cmpArea, String timeout, String sort, float[] scale, String wait) throws 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.
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)."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:
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).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.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.public int waitForMismatch(File[] templates, float passRate, String interval, Rectangle cmpArea, String timeout, String sort, String wait) throws 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.
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)."best" one.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).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.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.public int waitForMismatch(File template, float passRate, String interval, Rectangle cmpArea, String timeout, Color color, Color[] bridgeColors, Integer rgbTolerance, Integer rotations, Boolean draw, Boolean clear, Dimension min, Dimension max, String wait) throws 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, overlaid 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.
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).min - the minimum object size. The dimension may contain zero
width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a minimum
width of 30 pixels use new Dimension(30, -1). To set off
filtering by minimum size use null.max - the maximum object size. The dimension may contain zero
width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a maximum
width of 100 pixels use new Dimension(100, -1). To set off
filtering by maximum size use null.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.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.public int waitForMismatch(File template, float passRate, String interval, Rectangle cmpArea, String timeout, Color color, Color[] bridgeColors, Integer rgbTolerance, Integer rotations, Boolean draw, Boolean clear, String wait) throws 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, overlaid 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.
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).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.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.public int waitForMismatch(Image template, float passRate, String interval, Rectangle cmpArea, String timeout, Color color, Color[] bridgeColors, Integer rgbTolerance, Integer rotations, Boolean draw, Boolean clear, Dimension min, Dimension max, String wait) throws 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.
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).min - the minimum object size. The dimension may contain zero
width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a minimum
width of 30 pixels use new Dimension(30, -1). To set off
filtering by minimum size use null.max - the maximum object size. The dimension may contain zero
width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a maximum
width of 100 pixels use new Dimension(100, -1). To set off
filtering by maximum size use null.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.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.public int waitForMismatch(Image template, float passRate, String interval, Rectangle cmpArea, String timeout, Color color, Color[] bridgeColors, Integer rgbTolerance, Integer rotations, Boolean draw, Boolean clear, String wait) throws 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.
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).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.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.public int waitForMismatch(String interval, Rectangle cmpArea, String timeout, String language, String text, String pattern, String wait) throws 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.
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.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.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.public int waitForMismatch(String interval, Rectangle cmpArea, String timeout, String language, float scale, String text, int distance, String pattern, String wait) throws 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.
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.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).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.public int waitForMismatch(String interval, Rectangle cmpArea, String timeout, String language, float scale, String text, int distance, String pattern, int mode, int filter, int fontSize, String wait) throws 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.
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:"-psm 3" CLI switch). This value is compatible with
the Robot releases prior to 3.5.-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."-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.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.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).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.public int waitForMismatch(File[] templates, float passRate, Rectangle cmpArea, String interval, String timeout, String text, int distance, String pattern, String wait) throws 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.
templates - list of template images (File instances).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.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).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).IOException - on an I/O error (can't read an image file and/or
can't get image of the remote desktop).public int waitForMismatch(Image[] templates, float passRate, String interval, Rectangle cmpArea, String timeout, boolean removeBg, String bgColor, Integer minAlpha, String wait) throws 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.
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).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.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.public int waitForMismatch(Image[] templates, float passRate, String interval, String method, String methodParams, Rectangle cmpArea, String timeout, String wait) throws 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).
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).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.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.public int waitForMismatch(File[] templates, float passRate, String interval, Rectangle cmpArea, String timeout, boolean removeBg, String bgColor, Integer minAlpha, Integer rgbTolerance, String wait) throws 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.
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).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.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.public int waitForMismatch(File[] templates, float passRate, String interval, Rectangle cmpArea, String timeout, boolean removeBg, String bgColor, Integer minAlpha, String wait) throws 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.
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).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.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.public int waitForMismatch(File[] templates, float passRate, String interval, String method, String methodParams, Rectangle cmpArea, String timeout, String wait) throws 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).
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).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.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.public int waitForMismatch(File[] templates, float passRate, String method, Rectangle cmpArea, String timeout, String wait) throws IOException
IOExceptionpublic int waitForMismatch(File[] templates, float passRate, String method, String timeout) throws IOException
IOExceptionpublic int waitForMismatch(File[] templates, String method, String timeout) throws IOException
IOExceptionpublic int waitForMismatch(File[] templates, String timeout) throws IOException
IOExceptionpublic int waitForMismatch(File[] templates) throws 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%.
templates - list of template images (File instances).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.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.public int waitForMismatch(String name, String interval, String timeout, String wait) throws IOException
Wait for a variable to be created. Use with session variables created through the Varg command to synchronize the script with other script(s) running in parallel. The method provides access to functionality of the Waitfor scripting language command with the comparison method name fixed to "variable".
name - the variable name.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).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.IOException - the exception is declared but never thrown
because the 'variable' method doesn't rely on a desktop connection.public int waitForClipboard(String timeout, String wait) throws IOException
Wait for a clipboard update. This method is rarely used because this functionality is not supported by most of the supported connections. It is listed here for compatibility reasons.
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). command exit code as is specified in the Waitfor specification.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.IOException - on a connection I/O error.public int waitForClipboard(String timeout) throws IOException
Wait for a clipboard update. This method is rarely used because this functionality is not supported by most of the supported connections. It is listed here for compatibility reasons.
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.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.IOException - on a connection I/O error.public int script(String number, boolean isEnd, String name) throws 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.
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.IOException - though the exception is declared, it should
be never throws because the command doesn't interact with the desktop.public int script(String number, String action, String name) throws 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.
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.action - "start" or "end".name - optional script name to be displayed in the report.IOException - though the exception is declared, it should
be never throws because the command doesn't interact with the desktop.public int scriptStart(String number, String name) throws 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.
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.IOException - though the exception is declared, it should
be never throws because the command doesn't interact with the desktop.public int scriptStart(String number) throws 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.
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.IOException - though the exception is declared, it should
be never throws because the command doesn't interact with the desktop.public int scriptEnd(String number, String name) throws 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.
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.IOException - though the exception is declared, it should
be never throws because the command doesn't interact with the desktop.public int scriptEnd(String number) throws 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.
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.IOException - though the exception is declared, it should
be never throws because the command doesn't interact with the desktop.public int step(String name, String result, String instructions, String expected, String actual, String notes) throws 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.
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")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.IOException - though the exception is declared, it should
be never throws because the command doesn't interact with the desktop.public int stepPassed(String name, String instructions, String expected, String actual, String notes) throws 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.
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.IOException - though the exception is declared, it should
be never throws because the command doesn't interact with the desktop.public int stepPassed(String name, String instructions) throws 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.
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").IOException - though the exception is declared, it should
be never throws because the command doesn't interact with the desktop.public int stepFailed(String name, String instructions, String expected, String actual, String notes) throws 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.
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.IOException - though the exception is declared, it should
be never throws because the command doesn't interact with the desktop.public int stepFail(String name, String instructions) throws 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.
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").IOException - though the exception is declared, it should
be never throws because the command doesn't interact with the desktop.public int stepNotTested(String name, String instructions, String expected, String actual, String notes) throws 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.
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.IOException - though the exception is declared, it should
be never throws because the command doesn't interact with the desktop.public int stepNotAvailable(String name, String instructions, String expected, String actual, String notes) throws 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.
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.IOException - though the exception is declared, it should
be never throws because the command doesn't interact with the desktop.public int excelOpen(File inputFile, File outputFile, String sheet, String id, String password) throws IOException
Open a Microsoft Excel file for reading and writing. The method provides access to functionality of the Excel open scripting language command.
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.password - the spread sheet password. Supported since 6.1.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).public int excelOpen(File inputFile, File outputFile, String sheet, String id) throws IOException
Open a Microsoft Excel file for reading and writing. The method provides access to functionality of the Excel open scripting language command.
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.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).public int excelOpen(File inputFile, String id) throws 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.
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.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).public int excelOpen(InputStream inputStream, OutputStream outputStream, String sheet, String id, String password) throws 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();
}
}
}
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.password - the spread sheet password. Supported since 6.1.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).public int excelOpen(InputStream inputStream, OutputStream outputStream, String sheet, String id) throws 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();
}
}
}
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.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).public int excelCreate(File outputFile, String sheetName, String id, String password) throws IOException
Create a new Microsoft Excel document for reading and writing. The method provides access to functionality of the Excel create scripting language command.
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"..password - the spread sheet password. Supported since 6.1.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).public int excelCreate(File outputFile, String sheetName, String id) throws IOException
Create a new Microsoft Excel document for reading and writing. The method provides access to functionality of the Excel create scripting language command.
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"..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).public int excelCreate(OutputStream outputStream, String sheetName, String id, String password) throws 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.
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"..password - the spread sheet password. Supported since 6.1.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).public int excelCreate(OutputStream outputStream, String sheetName, String id) throws 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.
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"..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).public int excelCreate(String sheetName, String id) throws 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.
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.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).public int excelClose(String id, boolean save) throws IOException
Close and eventually save the specified Excel document. The method provides access to functionality of the Excel close scripting language command.
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.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).public int excelSelect(String ref, String sheet, boolean evaluate, String id) throws 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.
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.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).public int excelSelect(int row,
String column,
String sheet,
boolean evaluate,
String id)
throws 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.
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.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).public int excelSelect(String ref, boolean evaluate, String id) throws 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.
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.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).public int excelSelect(int row,
String column,
boolean evaluate,
String id)
throws 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.
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.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).public int excelSelect(String sheet, String id) throws IOException
Select (open) a sheet. The method provides access to functionality of the Excel select scripting language command.
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.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.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).public int excelFind(Object value, String type, boolean evaluate, Object sheet, String id) throws IOException
Search the specified sheet for a cell of the given type and/or value.
The sheet is searched in the same mode as humans read text, row by row
from left to right until the first matching cell is located. If the cell is
located successfully the method populates the _EXCEL_CELL_ROW, _EXCEL_CELL_COLUMN,
_EXCEL_CELL_REF, _EXCEL_CELL_TYPE and _EXCEL_CELL_VALUE variables with the cell coordinates (row/column,
reference), type and value. These can be retrieved through the AbstractJavaTestScript.getVariable(java.lang.String) method.
The method provides access to functionality of the
Excel find scripting language command.
value - value to search for. The method internally compares the value
object type with the cell type and tries to convert it where needed. For
example, when the argument is a number specified as String instance and
the search is not limited to a specific cell type through the "type" parameter,
the method compares the value to a Number when comparing it with a cell whose
type is NUMERIC. The value parameter is mandatory and may not be null.type - cell type to limit the search to; 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. Ths parameter
is optional and when it is null all sheet cells are searched regardless of
their type.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.sheet - sheet to search. 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.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.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).public int excelFind(String pattern, boolean evaluate, String type, Object sheet, String id) throws IOException
Search the specified sheet for a cell whose value (and optionally also type)
matches the given regular expression.
The sheet is searched in the same mode as humans read text, row by row
from left to right until the first matching cell is located. If the cell is
located successfully the method populates the _EXCEL_CELL_ROW, _EXCEL_CELL_COLUMN,
_EXCEL_CELL_REF, _EXCEL_CELL_TYPE and _EXCEL_CELL_VALUE variables with the cell coordinates (row/column,
reference), type and value. These can be retrieved through the AbstractJavaTestScript.getVariable(java.lang.String) method.
The method provides access to functionality of the
Excel find scripting language command.
pattern - a regular expression complying with the Java Pattern specification.
The parameter is mandatory and may not be null. The method internally converts
each cell value to a String and then matches it with the pattern.type - cell type to limit the search to; 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. Ths parameter
is optional and when it is null all sheet cells are searched regardless of
their type.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.sheet - sheet to search. 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.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.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).public int excelSet(int row,
String column,
Object value,
Object sheet,
String type,
String format,
String informat,
Color fg,
Color bg,
int width,
int height,
String id)
throws IOException
Set value and/or type of the specified cell.The method provides access to functionality of the Excel set scripting language command.
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".type - cell type to set; 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. This parameter
is optional and when it is null the method guesses the type by the value object.sheet - sheet containing the cell. 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.value - new cell value.format - an
Excel format string to format the cell data with.informat - a
Java compatible date format to parse the value value with.
The parsed date will be converted to the internal Excel date format which
is the number of days elapsed since 1 Jan 1900 and stored to the NUMERIC
type cell. Do not use this field for other cell types.fg - the cell font color (since 6.3.3).bg - the cell background (fill) color (since 6.3.3).width - the column width to be set in the Excel units (since 6.3.3).height - the row height to be set in the Excel units (since 6.3.3).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.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).public int excelSet(int row,
String column,
Object sheet,
Color fg,
Color bg,
int width,
int height,
String id)
throws IOException
Set attributes of the specified cell such as the background and foreground colors and/or the column width and/or the row height. The method provides access to functionality of the Excel set scripting language command.
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 containing the cell. 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.fg - the cell font color (since 6.3.3).bg - the cell background (fill) color (since 6.3.3).width - the column width to be set in the Excel units (since 6.3.3).height - the row height to be set in the Excel units (since 6.3.3).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.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).public int excelSet(int row,
String column,
Object value,
Object sheet,
String type,
String format,
String informat,
String id)
throws IOException
Set value and/or type of the specified cell. The method provides access to functionality of the Excel set scripting language command.
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".type - cell type to set; 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. This parameter
is optional and when it is null the method guesses the type by the value object.sheet - sheet containing the cell. 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.value - new cell value.format - an
Excel format string to format the cell data with.informat - a
Java compatible date format to parse the value value with.
The parsed date will be converted to the internal Excel date format which
is the number of days elapsed since 1 Jan 1900 and stored to the NUMERIC
type cell. Do not use this field for other cell types.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.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).public int excelSet(int row,
String column,
Object value,
Object sheet,
String type,
String id)
throws IOException
Set value and/or type of the specified cell. The method provides access to functionality of the Excel set scripting language command.
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".type - cell type to set; 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. This parameter
is optional and when it is null the method guesses the type by the value object.sheet - sheet containing the cell. 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.value - new cell value.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.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).public int excelSet(String ref, Object value, Object sheet, String type, String id) throws IOException
Set value and/or type of the specified cell. The method provides access to functionality of the Excel set scripting language command.
ref - Excel compatible cell reference, for example "A1" or "K10".type - cell type to set; 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. This parameter
is optional and when it is null the method guesses the type by the value object.sheet - sheet containing the cell. 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.value - new cell value.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.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).public int excelSet(int row,
String column,
Object value,
String type,
String id)
throws IOException
Set value and/or type of the specified cell in the currently selected sheet. The method provides access to functionality of the Excel set scripting language command.
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".type - cell type to set; 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. This parameter
is optional and when it is null the method guesses the type by the value object.value - new cell value.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.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).public int excelSet(String ref, Object value, String type, String id) throws IOException
Set value and/or type of the specified cell in the currently selected sheet. The method provides access to functionality of the Excel set scripting language command.
ref - Excel compatible cell reference, for example "A1" or "K10".type - cell type to set; 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. This parameter
is optional and when it is null the method guesses the type by the value object.value - new cell value.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.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).public int excelSet(int row,
String column,
Object value,
String id)
throws IOException
Set value of the specified cell in the currently selected sheet. The method provides access to functionality of the Excel set scripting language command.
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".value - new cell value.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.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).public int excelSet(String ref, Object value, String id) throws IOException
Set value of the specified cell in the currently selected sheet. The method provides access to functionality of the Excel set scripting language command.
ref - Excel compatible cell reference, for example "A1" or "K10".value - new cell value.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.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).public int excelSet(Object value, String id) throws IOException
Set value of the currently selected (previously used) cell in the currently selected sheet. The method provides access to functionality of the Excel set scripting language command.
value - new cell value.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.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).public int excelCopy(String rows, String columns, String sheet, String id) throws IOException
Mark cells for copying (since v4.4.4). The selected data may be then copied
into another position within the same sheet or another one or even to a different
file using Excel pasteThe command does not make any
internal copy of the data from the selected cells. It merely saves a
reference to the selection. If the selected cells get changed between the
copy and paste operations the updated data will be copied.
The "rows" and "columns" parameters must be always present together. The command selects all cells at the specified rows and columns. For example, the parameters of "rows=1-2" and "columns=A-C" will select 6 cells at A1, A2, B1, B2, C1 and C2. As empty positions are ignored the specified ranges may exceed the actual sheet size.
The method provides access to functionality of the Excel copy scripting language command.
rows - The row(s) identifying the cells to be selected . Rows can be
specified as a single number ("1"), a range ("1-5") or a comma or
semicolon separated list of numbers and/or ranges ("1;3;5-6"). Numbering
starts from 1.columns - the column(s) to be selected. It supports the same syntax
as "rows" where letters may be used instead of numbers ("A;C;E-F").sheet - sheet to select the cells 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.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.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).public int excelPaste(int row,
String column,
String sheet,
String id)
throws IOException
Copy cells selected previously by Excel select to the
specified location (cell). The method provides access to functionality of the
Excel paste scripting language command.
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 cells 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.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.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).public int excelPaste(String ref, String sheet, String id) throws IOException
Copy cells selected previously by Excel select to the
specified location (cell). The method provides access to functionality of the
Excel paste scripting language command.
ref - Excel compatible cell reference, for example "A1" or "K10".sheet - sheet to select the cells 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.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.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).public int run(String script) throws IOException
Execute a TPR test script (.tpr) or a source Java file (.java) or instantiate and execute a Java test script specified by a fully qualified class name (with package). The method provides access to functionality of the Run scripting language command.
A special handling is required if a TPR script executed through this
method calls the Exit command without the "scope" parameter (such as "Exit 1")
or with the scope set to "process" ("Exit scope=process"). This will set the stop
flag on the underlying interpret which will cause any subsequent call of a test script method
to throw a StopRequestException. This behavior ensures that a TPR test script
is able to terminate the Java test script.
To bypass this behavior you may reset the stop flag right after the run()
method call as follows:
run(<script>);
getContext().getInterpret().setStop(this, false, false, null);script - script to execute (relative or absolute file path or fully qualified
Java class name).IOException - never thrown (just declared).IllegalArgumentException - when the specified file doesn't
exist or it has incorrect format.public int run(String script, Object... parameters) throws IOException
Execute a test script with optional parameters. The test script may be a regular one (a .tpr file) or a source Java file (.java) or a Java test script specified by a fully qualified class name (with package). The method provides access to functionality of the Run scripting language command.
Parameters must be specified as an object array of even length where
each pair of objects represents the parameter name and its value. The parameter
name is typically a String instance; other objects will be converted to String
using String.toString(). Values may be any objects; if the called test
script is however a .tpr one, the value is internally converted to String. A null
value is replaced by an empty string "". For
example, the command of
Run tests.MyTest file=C:\data.xls readonly
corresponds to a Java call:
run("tests.MyTest", "file", "C:\data.xls", "readonly", null);
As parameters are stored to the context in form of variables, the example above may be also coded as:
getContext().setVariable("file", "C:\data.xls");
getContext().setVariable("readonly", "");
run("tests.MyTest");
A special handling is required if a TPR script executed through this
method calls the Exit command without the "scope" parameter (such as "Exit 1")
or with the scope set to "process" ("Exit scope=process"). This will set the stop
flag on the underlying interpret which will cause any subsequent call of a test script method
to throw a StopRequestException. This behavior ensures that a TPR test script
is able to terminate the Java test script.
To bypass this behavior you may reset the stop flag right after the run()
method call as follows:
run(<script>, ...);
getContext().getInterpret().setStop(this, false, false, null);
script - script to execute (relative or absolute file path) or a fully qualified
Java test script name (the corresponding class must be on the Robot's class path).parameters - a variable array of parameters. If a parameter consists of a
name and value it must be specified as two arguments, the name followed by the value.
For example, a command like "Run XXX myparam=myvalue" must be passed as
run("XXX", "myparam", "myvalue").IOException - never thrown (just declared).IllegalArgumentException - when the specified file doesn't
exist or it has incorrect format.public int include(String file) throws IOException
Include a TPR test script (.tpr).
The method provides access to functionality of the
Include scripting language command and allows to import
variables and procedures from a .tpr script. Variables can be then retrieved
through the getContext().getVariable()
method or any of the convenience getVariableAsXXX() ones. Procedures
defined in the included .tpr script may be executed through the callProcedure(java.lang.String, java.lang.String[])
method.
file - script to include (relative or absolute file path).IOException - never thrown (just declared).IllegalArgumentException - when the specified file doesn't
exist or it has incorrect format.public int callProcedure(String procedureName, String... args) throws IllegalArgumentException
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).
.
The method provides access to procedure calls as they are specified in the
Procedures chapter of the scripting language specification.
procedureName - procedure name to call. It is not case sensitive.args - procedure arguments. Note that the method internally passes
the procedure name as the very first argument to comply with the procedure
specification. This variable length parameter is supposed to contain just
the optional arguments indexed from 1. For example, a procedure call
in the scripting language like "myProcedure true 1" is equal to the
method call of callProcedure("myProcedure", "true", "1");.IllegalArgumentException - when procedure of the given name doesn't exist.public int timerLoad(File referenceFile) throws IOException
The method loads Timer reference data from an XML file previously generated
through the Report command (see also report(java.io.File)).
As this method stores the reference data internally and updates all already
existing as well as the to-be-created timers, it may be called anywhere
in the script and not necessarily at the script beginning.
Reference times as well the difference from the actually measured values
are then written into the resulting XML report. This system allows to keep track
of performance changes.
If the file is relative, it is resolved
in the same way as the Report file (meaning against the output path
specified by the _REPORT_DIR context variable, respectively against the path returned by
ScriptingContext.getOutputDir()). The XML is parsed for timer data
which is then used as reference values for any timer(s) with matching name(s).
Note that loading of reference data from XML has a
priority over the referenceValue parameter provided in other
timer methods in this class.
For more details on timers see the base timer() method
and the Timer command specification.
referenceFile - XML file with reference data.IOException - declared but never thrown because errors are reported
through returned exit codes.public int timer(String names, String description, long value, long referenceValue, String group, String ungroup, File referenceFile) throws IOException
Create and/or configure timer(s) and/or timer groups.
Timers are objects allowing to measure time elapsed by a command, block of commands or a script and report it through the test results, usually for performance testing purposes. Important timer and timer group features:
"value=0" parameter.To get current value of a timer use
ScriptingContext.getTimerValue(java.lang.String).
To find out whether a timer exists and/or is running use
ScriptingContext.isTimerRunning(java.lang.String).
Parameters specified by this method represent a sequence of tasks to be applied to the specified timer or a list of timers. These are performed in the following order:
names parameter into a list of timers and
create those which do not exist yet. If the list contains one or more group names,
they are expanded into (replaced by) list of timers which are currently members
of the group(s).ungroup parameter is not null.group parameter not null.load parameter is present.names - a timer name or a comma separated list of timer/group names to create or to apply
the parameters to. A unique name (or names) will create a new timer (timers).
If the name corresponds to a group previously created by a method call with the
group parameter, it is expanded into a list of timers which are
currently members of that group.description - optional timer description. It is displayed in the resulting
XML report together with the timer name. Use null for no description.value - initial timer value in milliseconds (optional).
The default value is zero. Setting of a value of a started timer will
stop it and it is necessary to restart it. Use the value of -1 to make the
method ignore this parameter and leave the timer value on whatever value
it contains.referenceValue - reference time value in milliseconds. It plays no
role during the script execution and it is used exclusively for reporting
purposes. When the reference value is specified, the timer entry in resulting
XML file created by the Report command will contain the reference value as well
as the relative difference (percentage) from the actually measured time. This
functionality allows to track performance changes across testing of two
application versions. Use the value of -1 to make the
method ignore this parameter and leave the timer reference value on whatever
it contains. Be also aware that reference values are overwritten by any call
of the load parameter which has higher priority than referenceValue.group - an optional group or a comma separated list of group names to associate
the timer(s) specified in the names parameter with. If any of
the specified group names contains a space, the whole list must be enclosed
in double quotes. A unique name (or names) will create a new group (groups).
A group name may not be the same as name of an already existing timer.ungroup - an optional group or comma separated list of group names to remove the timer(s) from.
If any of the specified group names contains a space, the whole list must be enclosed in
double quotes. If the timer(s) specified by the names parameter is a member of
the specified group or groups, it is removed from there.referenceFile - XML file with reference data for the specified timers. Unlike
the timerLoad(java.io.File) method this parameter loads reference data
just for the timers referenced by the names parameter and all other
timer data from XML are discarded.IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int timer(String names, String description, long value, long referenceValue) throws IOException
Create and/or configure timer(s). This
method is a shorter version of timer(java.lang.String, java.lang.String, long, long, java.lang.String, java.lang.String, java.io.File)
without support of grouping.
Parameters specified by this method represent a sequence of tasks to be applied to the specified timer or a list of timers. These are performed in the following order:
names parameter into a list of timers and
create those which do not exist yet. If the list contains one or more group names,
they are expanded into (replaced by) list of timers which are currently members
of the group(s).For more details on timers see the base timer() method
and the Timer command specification.
names - a timer name or a comma separated list of timer/group names to create or to apply
the parameters to. A unique name (or names) will create a new timer (timers).
If the name corresponds to a group previously created by a method call with the
group parameter, it is expanded into a list of timers which are
currently members of that group.description - optional timer description. It is displayed in the resulting
XML report together with the timer name. Use null for no description.value - initial timer value in milliseconds (optional).
The default value is zero. Setting of a value of a started timer will
stop it and it is necessary to restart it. Use the value of -1 to make the
method ignore this parameter and leave the timer value on whatever value
it contains.referenceValue - reference time value in milliseconds. It plays no
role during the script execution and it is used exclusively for reporting
purposes. When the reference value is specified, the timer entry in resulting
XML file created by the Report command will contain the reference value as well
as the relative difference (percentage) from the actually measured time. This
functionality allows to track performance changes across testing of two
application versions. Use the value of -1 to make the
method ignore this parameter and leave the timer reference value on whatever
it contains. Be also aware that reference values are overwritten by any call
of the load parameter which has higher priority than referenceValue.IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int timer(String names, String description) throws IOException
Create and/or configure timer(s). This method is a shorter
version of timer(java.lang.String, java.lang.String, long, long, java.lang.String, java.lang.String, java.io.File)
without support of grouping and value setting and it should be used
as for plain creation of a timer or a number of timers.
For more details on timers see the base timer() method
and the Timer command specification.
names - a timer name or a comma separated list of timer/group names to create or to apply
the parameters to. A unique name (or names) will create a new timer (timers).
If the name corresponds to a group previously created by a method call with the
group parameter, it is expanded into a list of timers which are
currently members of that group.description - optional timer description. It is displayed in the resulting
XML report together with the timer name. Use null for no description.IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int timerStart(String names, String description, long value, long referenceValue, String group, String ungroup) throws IOException
Create and/or configure timer(s) and/or timer groups and start it
(them). This method is equivalent to timer(java.lang.String, java.lang.String, long, long, java.lang.String, java.lang.String, java.io.File)
where the timers specified through the names are in addition started.
Parameters specified by this method represent a sequence of tasks to be applied to the specified timer or a list of timers. These are performed in the following order:
names parameter into a list of timers and
create those which do not exist yet. If the list contains one or more group names,
they are expanded into (replaced by) list of timers which are currently members
of the group(s).ungroup parameter is not null.group parameter not null.For more details on timers see the base timer() method
and the Timer command specification.
names - a timer name or a comma separated list of timer/group names to start and to apply
the parameters to.
A unique name (or names) will create a new timer (timers).
If the name corresponds to a group previously created by a method call with the
group parameter, it is expanded into a list of timers which are
currently members of that group.description - optional timer description. It is displayed in the resulting
XML report together with the timer name. Use null for no description.value - initial timer value in milliseconds (optional).
The default value is zero. Setting of a value of a started timer will
stop it and it is necessary to restart it. Use the value of -1 to make the
method ignore this parameter and leave the timer value on whatever value
it contains.referenceValue - reference time value in milliseconds. It plays no
role during the script execution and it is used exclusively for reporting
purposes. When the reference value is specified, the timer entry in resulting
XML file created by the Report command will contain the reference value as well
as the relative difference (percentage) from the actually measured time. This
functionality allows to track performance changes across testing of two
application versions. Use the value of -1 to make the
method ignore this parameter and leave the timer reference value on whatever
it contains. Be also aware that reference values are overwritten by any call
of the load parameter which has higher priority than referenceValue.group - an optional group or a comma separated list of group names to associate
the timer(s) specified in the names parameter with. If any of
the specified group names contains a space, the whole list must be enclosed
in double quotes. A unique name (or names) will create a new group (groups).
A group name may not be the same as name of an already existing timer.ungroup - an optional group or comma separated list of group names to remove the timer(s) from.
If any of the specified group names contains a space, the whole list must be enclosed in
double quotes. If the timer(s) specified by the names parameter is a member of
the specified group or groups, it is removed from there.IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int timerStart(String names) throws IOException
Start timer(s). This method is equivalent to a call of
timerStart(names, null, -1, -1, null, null)
and it simply starts one or more timers and/or timer groups.
For more details on timers see the base timer() method
and the Timer command specification.
names - a timer name or a comma separated list of timer/group names to start.
A unique name (or names) will create a new timer (timers).
If the name corresponds to a group previously created by a method call with the
group parameter, it is expanded into a list of timers which are
currently members of that group.IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int timerStop(String names, String description, long value, long referenceValue, String group, String ungroup) throws IOException
Stop timer(s) and/or timer groups. This method is equivalent to timer(java.lang.String, java.lang.String, long, long, java.lang.String, java.lang.String, java.io.File)
where the timers specified through the names parameter are in addition stopped.
Timers which are not running are not stopped but their properties
will be changed through the parameters of desc, value, refvalue, group
and ungroup unless they are null (or negative number).
Parameters specified by this method represent a sequence of tasks to be applied to the specified timer or a list of timers. These are performed in the following order:
names parameter into a list of timers and
create those which do not exist yet. If the list contains one or more group names,
they are expanded into (replaced by) list of timers which are currently members
of the group(s).ungroup parameter is not null.group parameter not null.For more details on timers see the base timer() method
and the Timer command specification.
names - a timer name or a comma separated list of timer/group names to stop and
to apply and parameters to. A unique name (or names) will create a new timer (timers).
If the name corresponds to a group previously created by a method call with the
group parameter, it is expanded into a list of timers which are
currently members of that group.description - optional timer description. It is displayed in the resulting
XML report together with the timer name. Use null for no description.value - initial timer value in milliseconds (optional).
The default value is zero. Setting of a value of a started timer will
stop it and it is necessary to restart it. Use the value of -1 to make the
method ignore this parameter and leave the timer value on whatever value
it contains.referenceValue - reference time value in milliseconds. It plays no
role during the script execution and it is used exclusively for reporting
purposes. When the reference value is specified, the timer entry in resulting
XML file created by the Report command will contain the reference value as well
as the relative difference (percentage) from the actually measured time. This
functionality allows to track performance changes across testing of two
application versions. Use the value of -1 to make the
method ignore this parameter and leave the timer reference value on whatever
it contains. Be also aware that reference values are overwritten by any call
of the load parameter which has higher priority than referenceValue.group - an optional group or a comma separated list of group names to associate
the timer(s) specified in the names parameter with. If any of
the specified group names contains a space, the whole list must be enclosed
in double quotes. A unique name (or names) will create a new group (groups).
A group name may not be the same as name of an already existing timer.ungroup - an optional group or comma separated list of group names to remove the timer(s) from.
If any of the specified group names contains a space, the whole list must be enclosed in
double quotes. If the timer(s) specified by the names parameter is a member of
the specified group or groups, it is removed from there.IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int timerStop(String names) throws IOException
Stop timer(s) and/or timer groups. This method is equivalent to a call of
timerStop(names, null, -1, -1, null, null)
and it simply stops one or more timers and/or timer groups.
For more details on timers see the base timer() method
and the Timer command specification.
names - a timer name or a comma separated list of timer/group names to stop.
A unique name (or names) will create a new timer (timers).
If the name corresponds to a group previously created by a method call with the
group parameter, it is expanded into a list of timers which are
currently members of that group.IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int timerGroup(String names, String group) throws IOException
Associate timer(s) with a timer group or groups. This method is equivalent
to a call of timer(names, null, -1, -1, group, null, null)
and provides a quick way of adding timer or timers or even other groups
into one or more other timer groups.
For more details on timers see the base timer() method
and the Timer command specification.
names - a timer name or a comma separated list of timer/group names to stop and
to apply and parameters to. A unique name (or names) will create a new timer (timers).
If the name corresponds to a group previously created by a method call with the
group parameter, it is expanded into a list of timers which are
currently members of that group.group - an optional group or a comma separated list of group names to associate
the timer(s) specified in the names parameter with. If any of
the specified group names contains a space, the whole list must be enclosed
in double quotes. A unique name (or names) will create a new group (groups).
A group name may not be the same as name of an already existing timer.IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int timerUngroup(String names, String ungroup) throws IOException
Remove timer(s) from a timer group or groups. This method is equivalent
to a call of timer(names, null, -1, -1, null, ungroup, null)
and provides a quick way of removing timer or timers from one or more timer groups.
For more details on timers see the base timer() method
and the Timer command specification.
names - a timer name or a comma separated list of timer/group names to stop and
to apply and parameters to. A unique name (or names) will create a new timer (timers).
If the name corresponds to a group previously created by a method call with the
group parameter, it is expanded into a list of timers which are
currently members of that group.ungroup - an optional group or comma separated list of group names to remove the timer(s) from.
If any of the specified group names contains a space, the whole list must be enclosed in
double quotes. If the timer(s) specified by the names parameter is a member of
the specified group or groups, it is removed from there.IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int stringIndexOf(String text, String string, int start, int end, int distance, String variableName) throws IOException
The method provides access to functionality of the String indexof command. It searches the given text for the specified string and stores its location (index) to a variable in the test script context.
This method is intended to support safe conversion of TPR test scripts
into Java code. Test scripts which are being developed directly in Java
are rather expected to use a native call of String.indexOf(java.lang.String)
unless the method is used to perform a fuzzy text search using the
distance parameter.
The only difference is that the method stores the resulting index to a context variable
and returns a numeric exit code which typically indicates success or a failure
of some type.
text - text to be searched.string - a string to be searched for.start - optional start index to run the search from. Indexing starts
from zero. To set it off provide a negative value (-1 or less).end - optional end index to run the search to. Indexing starts
from zero. To set it off provide a negative value (-1 or less).distance - When the parameter is set to the default value of 0 (no
distance) the command falls back to plain string search where the
argument text is searched for the first occurrence of the provided
string. This behavior is equivalent to String.indexOf(java.lang.String).
The tolerant (fuzzy) text search is performed for the distance values of 1 and higher. The text is searched for an occurrence of a string which is similar enough to the specified one. The tolerance (similarity) is 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. The distance approximately specifies how many characters may be omitted or not recognized properly at a maximum to consider the sample text equivalent.
variableName - optional variable name to store the resulting index to. If the
parameter is null, the result will be stored to the default variable called _STRING.variableName parameter. If the string is not found, the variable value is
set to -1.IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int stringIndexOf(String text, String string, int start, int end, String variableName) throws IOException
The method provides access to functionality of the String indexof command. It searches the given text for the specified string and stores its location (index) to a variable in the test script context.
This method is intended to support safe conversion of TPR test scripts
into Java code. Test scripts which are being developed directly in Java
are rather expected to use a native call of String.indexOf(java.lang.String).
The only difference is that the method stores the resulting index to a context variable
and returns a numeric exit code which typically indicates success or a failure
of some type.
text - text to be searched.string - a string to be searched for.start - optional start index to run the search from. Indexing starts
from zero. To set it off provide a negative value (-1 or less).end - optional end index to run the search to. Indexing starts
from zero. To set it off provide a negative value (-1 or less).variableName - optional variable name to store the resulting index to. If the
parameter is null, the result will be stored to the default variable called _STRING.variableName parameter. If the string is not found, the variable value is
set to -1.IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int stringIndexOf(String text, String string, int distance, String variableName) throws IOException
The method provides access to functionality of the String indexof command. It searches the given text for the specified string and stores its location (index) to a variable in the test script context.
This method is intended to support safe conversion of TPR test scripts
into Java code. Test scripts which are being developed directly in Java
are rather expected to use a native call of String.indexOf(java.lang.String)
unless the method is used to perform a fuzzy text search using the
distance parameter.
The only difference is that the method stores the resulting index to a context variable
and returns a numeric exit code which typically indicates success or a failure
of some type.
text - text to be searched.string - a string to be searched for.distance - When the parameter is set to the default value of 0 (no
distance) the command falls back to plain string search where the
argument text is searched for the first occurrence of the provided
string. This behavior is equivalent to String.indexOf(java.lang.String).
The tolerant (fuzzy) text search is performed for the distance values of 1 and higher. The text is searched for an occurrence of a string which is similar enough to the specified one. The tolerance (similarity) is 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. The distance approximately specifies how many characters may be omitted or not recognized properly at a maximum to consider the sample text equivalent.
variableName - optional variable name to store the resulting index to. If the
parameter is null, the result will be stored to the default variable called _STRING.variableName parameter. If the string is not found, the variable value is
set to -1.IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int stringIndexOf(String text, String string, String variableName) throws IOException
The method provides access to functionality of the String indexof command. It searches the given text for the specified string and stores its location (index) to a variable in the test script context.
This method is intended to support safe conversion of TPR test scripts
into Java code. Test scripts which are being developed directly in Java
are rather expected to use a native call of String.indexOf(java.lang.String).
The only difference is that the method stores the resulting index to a context variable
and returns a numeric exit code which typically indicates success or a failure
of some type.
text - text to be searched.string - a string to be searched for.variableName - optional variable name to store the resulting index to. If the
parameter is null, the result will be stored to the default variable called _STRING.variableName parameter. If the string is not found, the variable value is
set to -1.IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int stringIndexOf(String text, String string, int distance) throws IOException
The method provides access to functionality of the String indexof command. It searches the given text for the specified string and stores its location (index) to a variable in the test script context.
This method is intended to support safe conversion of TPR test scripts
into Java code. Test scripts which are being developed directly in Java
are rather expected to use a native call of String.indexOf(java.lang.String)
unless the method is used to perform a fuzzy text search using the
distance parameter.
The only difference is that the method stores the resulting index to a context variable
and returns a numeric exit code which typically indicates success or a failure
of some type.
text - text to be searched.string - a string to be searched for.distance - When the parameter is set to the default value of 0 (no
distance) the command falls back to plain string search where the
argument text is searched for the first occurrence of the provided
string. This behavior is equivalent to String.indexOf(java.lang.String).
The tolerant (fuzzy) text search is performed for the distance values of 1 and higher. The text is searched for an occurrence of a string which is similar enough to the specified one. The tolerance (similarity) is 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. The distance approximately specifies how many characters may be omitted or not recognized properly at a maximum to consider the sample text equivalent.
IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int stringIndexOf(String text, String string) throws IOException
The method provides access to functionality of the String indexof command. It searches the given text for the specified string and stores its location (index) to a variable in the test script context.
This method is intended to support safe conversion of TPR test scripts
into Java code. Test scripts which are being developed directly in Java
are rather expected to use a native call of String.indexOf(java.lang.String).
The only difference is that the method stores the resulting index to a context variable
and returns a numeric exit code which typically indicates success or a failure
of some type.
text - text to be searched.string - a string to be searched for.IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int stringLength(String text, String variableName) throws IOException
The method provides access to functionality of the String length command. It stores the argument text length in characters to a variable in the test script context.
This method is intended to support safe conversion of TPR test scripts
into Java code. Test scripts which are being developed directly in Java
are rather expected to use a native call of String.length().
The only difference is that the method stores the resulting length to a context variable
and returns a numeric exit code which typically indicates success (zero) or a failure
of some type.
text - the text whose length is to be measured.variableName - optional variable name to store the resulting text length to. If the
parameter is null, the result will be stored to the default variable called _STRING.variableName parameter.IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int stringLength(String text) throws IOException
The method provides access to functionality of the String length command. It stores the argument text length in characters to a variable in the test script context.
This method is intended to support safe conversion of TPR test scripts
into Java code. Test scripts which are being developed directly in Java
are rather expected to use a native call of String.length().
The only difference is that the method stores the resulting length to a context variable
and returns a numeric exit code which typically indicates success (zero) or a failure
of some type.
text - the text whose length is to be measured.IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int stringMatches(String text, String pattern, String variableName) throws IOException
The method provides access to functionality of the String matches command. It tests whether the argument text matches the specified regular expression (pattern).
This method is intended to support safe conversion of TPR test scripts
into Java code. Test scripts which are being developed directly in Java
are rather expected to use a native call of String.matches(java.lang.String).
The only difference is that the method stores the resulting boolean value to a context variable
and returns a numeric exit code which typically indicates success (zero) or a failure
of some type.
text - the text to match against the regular expression.pattern - regular expression (pattern). It must be Pattern compliant.variableName - optional variable name to store the result to. If the
parameter is null, the result will be stored to the default variable called _STRING.variableName parameter which may be retrieved through AbstractJavaTestScript.getVariableAsInt(java.lang.String).IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int stringMatches(String text, String pattern) throws IOException
The method provides access to functionality of the String matches command. It tests whether the argument text matches the specified regular expression (pattern).
This method is intended to support safe conversion of TPR test scripts
into Java code. Test scripts which are being developed directly in Java
are rather expected to use a native call of String.matches(java.lang.String).
The only difference is that the method stores the resulting boolean value to a context variable
and returns a numeric exit code which typically indicates success (zero) or a failure
of some type.
text - the text to match against the regular expression.pattern - regular expression (pattern). It must be Pattern compliant.variableName parameter which may be retrieved through AbstractJavaTestScript.getVariableAsInt(java.lang.String).IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int stringMatches(String text, String string, int distance, String variableName) throws IOException
The method provides access to functionality of the String matches command performing fuzzy text matching. It tests whether the argument text matches (contains) the specified string within the tolerance given by the Levenshtein distance.
text - the text to match.string - the string to search for.distance - When the parameter is set to the default value of 0 (no
distance) the command falls back to plain string search where the
argument text is tested whether it contains the provided string.
The tolerant (fuzzy) text search is performed for the distance values of 1 and higher. It is 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. In other words the distance specifies how many characters may be omitted or not recognized properly at a maximum to consider the sample text equivalent. Unlike the regular expressions the tolerant matching always searches the recognized text for any occurrence of a string matching the given text and distance.
variableName - optional variable name to store the result to. If the
parameter is null, the result will be stored to the default variable called _STRING.variableName parameter which may be retrieved through
AbstractJavaTestScript.getVariableAsInt(java.lang.String).IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int stringMatches(String text, String string, int distance) throws IOException
The method provides access to functionality of the String matches command performing fuzzy text matching. It tests whether the argument text matches (contains) the specified string within the tolerance given by the Levenshtein distance.
text - the text to match.string - the string to search for.distance - When the parameter is set to the default value of 0 (no
distance) the command falls back to plain string search where the
argument text is tested whether it contains the provided string.
The tolerant (fuzzy) text search is performed for the distance values of 1 and higher. It is 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. In other words the distance specifies how many characters may be omitted or not recognized properly at a maximum to consider the sample text equivalent. Unlike the regular expressions the tolerant matching always searches the recognized text for any occurrence of a string matching the given text and distance.
variableName parameter which may be retrieved through
AbstractJavaTestScript.getVariableAsInt(java.lang.String).IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int stringReplace(String text, String string, String replacement, String variableName) throws IOException
The method provides access to functionality of the String replace command. It replaces all occurrences of the specified string with the replacement in the text.
This method is intended to support safe conversion of TPR test scripts
into Java code. Test scripts which are being developed directly in Java
are rather expected to use a native call of String.replace(java.lang.CharSequence, java.lang.CharSequence).
The only difference is that the method stores the resulting text to a context variable
and returns a numeric exit code which typically indicates success (zero) or a failure
of some type.
text - the text to process.string - to be replaced.replacement - replacement string.variableName - optional variable name to store the resulting text to. If the
parameter is null, the result will be stored to the default variable called _STRING.variableName parameter which can be retrieved through AbstractJavaTestScript.getVariableAsString(java.lang.String).IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int stringReplace(String text, String string, String replacement) throws IOException
The method provides access to functionality of the String replace command. It replaces all occurrences of the specified string with the replacement in the text.
This method is intended to support safe conversion of TPR test scripts
into Java code. Test scripts which are being developed directly in Java
are rather expected to use a native call of String.replace(java.lang.CharSequence, java.lang.CharSequence).
The only difference is that the method stores the resulting text to a context variable
and returns a numeric exit code which typically indicates success (zero) or a failure
of some type.
text - the text to process.string - to be replaced.replacement - replacement string.AbstractJavaTestScript.getVariableAsString(java.lang.String).IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int stringReplacePattern(String text, String pattern, String replacement, String variableName) throws IOException
The method provides access to functionality of the String replace command. It replaces all occurrences matching the specified regular expression with the replacement in the provided text.
This method is intended to support safe conversion of TPR test scripts
into Java code. Test scripts which are being developed directly in Java
are rather expected to use a native call of String.replaceAll(java.lang.String, java.lang.String).
The only difference is that the method stores the resulting text to a context variable
and returns a numeric exit code which typically indicates success (zero) or a failure
of some type.
text - the text to process.pattern - Pattern compliant regular expression to identify
locations for replacement.replacement - replacement string.variableName - optional variable name to store the resulting text to. If the
parameter is null, the result will be stored to the default variable called _STRING.variableName parameter which can be retrieved through AbstractJavaTestScript.getVariableAsString(java.lang.String).IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int stringReplacePattern(String text, String pattern, String replacement) throws IOException
The method provides access to functionality of the String replace command. It replaces all occurrences matching the specified regular expression with the replacement in the provided text.
This method is intended to support safe conversion of TPR test scripts
into Java code. Test scripts which are being developed directly in Java
are rather expected to use a native call of String.replaceAll(java.lang.String, java.lang.String).
The only difference is that the method stores the resulting text to a context variable
and returns a numeric exit code which typically indicates success (zero) or a failure
of some type.
text - the text to process.pattern - Pattern compliant regular expression to identify
locations for replacement.replacement - replacement string.AbstractJavaTestScript.getVariableAsString(java.lang.String).IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int stringSplit(String text, String delimeter, String variableName) throws IOException
The method provides access to functionality of the String split command. It splits the given text by the given delimeter string into a list of elements (substrings).
This method is intended to support safe conversion of TPR test scripts
into Java code. Test scripts which are being developed directly in Java
are rather expected to use the StringTokenizer class directly.
The only difference is that the method stores the resulting list to context variables
and returns a numeric exit code which typically indicates success (zero) or a failure
of some type.
text - the text to be split (parsed).delimeter - a delimeter to split the text by. It is typically a comma (for a primitive
CSV parsing), semicolon or a space but it may be any other complex string.variableName - optional variable base name to store the resulting parsed values to. If the
parameter is null, the resulting list will be stored to variables derived from the default variable
called _STRING, such as _STRING1, _STRING2 etc..variableName parameter.
Number of values is then stored to the _STRING_COUNT variable and
it may be retrieved using AbstractJavaTestScript.getVariableAsInt(java.lang.String).IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int stringSplit(String text, String delimeter) throws IOException
The method provides access to functionality of the String split command. It splits the given text by the given delimeter string into a list of elements (substrings).
This method is intended to support safe conversion of TPR test scripts
into Java code. Test scripts which are being developed directly in Java
are rather expected to use the StringTokenizer class directly.
The only difference is that the method stores the resulting list to context variables
and returns a numeric exit code which typically indicates success (zero) or a failure
of some type.
text - the text to be split (parsed).delimeter - a delimeter to split the text by. It is typically a comma (for a primitive
CSV parsing), semicolon or a space but it may be any other complex string._STRING_COUNT variable and
it may be retrieved using AbstractJavaTestScript.getVariableAsInt(java.lang.String).IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int stringSplitByPattern(String text, String pattern, String variableName) throws IOException
The method provides access to functionality of the String split command. It splits the given text by the given delimeter regular expression into a list of elements (substrings).
This method is intended to support safe conversion of TPR test scripts
into Java code. Test scripts which are being developed directly in Java
are rather expected to use the String.split(java.lang.String) method directly.
The only difference is that the method stores the resulting list to context variables
and returns a numeric exit code which typically indicates success (zero) or a failure
of some type.
text - the text to be split (parsed).pattern - a Pattern compliant regular expression to split the text by.
For example, to split the text by white characters use "\\s".variableName - optional variable base name to store the resulting parsed values to. If the
parameter is null, the resulting list will be stored to variables derived from the default variable
called _STRING, such as _STRING1, _STRING2 etc.variableName parameter.
Number of values is then stored to the _STRING_COUNT variable and
it may be retrieved using AbstractJavaTestScript.getVariableAsInt(java.lang.String).IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int stringSplitByPattern(String text, String pattern) throws IOException
The method provides access to functionality of the String split command. It splits the given text by the given delimeter regular expression into a list of elements (substrings).
This method is intended to support safe conversion of TPR test scripts
into Java code. Test scripts which are being developed directly in Java
are rather expected to use the String.split(java.lang.String) method directly.
The only difference is that the method stores the resulting list to context variables
and returns a numeric exit code which typically indicates success (zero) or a failure
of some type.
text - the text to be split (parsed).pattern - a Pattern compliant regular expression to split the text by.
For example, to split the text by white characters use "\\s"._STRING_COUNT variable and
it may be retrieved using AbstractJavaTestScript.getVariableAsInt(java.lang.String).IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int stringSubstring(String text, Integer start, Integer end, String variableName) throws IOException
The method provides access to functionality of the String substring command. It returns substring of the argument text defined by the start and end positions (indices).
This method is intended to support safe conversion of TPR test scripts
into Java code. Test scripts which are being developed directly in Java
are rather expected to use the String.substring(int, int) method directly.
The only difference is that the method stores the resulting text to a context variable
and returns a numeric exit code which typically indicates success (zero) or a failure
of some type.
text - the text to cut the substring fromstart - start position (index). If the parameter is null, the start index
defaults to 0.end - end position (index). If the parameter is null, the end index
defaults to the text length.variableName - optional variable name to store the resulting substring to. If the
parameter is null, the value will be stored to the default variable
called _STRING._STRING variable or the custom variable specified by the
variableName parameter and
it may be retrieved using AbstractJavaTestScript.getVariableAsString(java.lang.String).IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int stringSubstring(String text, Integer start, Integer end) throws IOException
The method provides access to functionality of the String substring command. It returns substring of the argument text defined by the start and end positions (indices).
This method is intended to support safe conversion of TPR test scripts
into Java code. Test scripts which are being developed directly in Java
are rather expected to use the String.substring(int, int) method directly.
The only difference is that the method stores the resulting text to a context variable
and returns a numeric exit code which typically indicates success (zero) or a failure
of some type.
text - the text to cut the substring fromstart - start position (index). If the parameter is null, the start index
defaults to 0.end - end position (index). If the parameter is null, the end index
defaults to the text length._STRING variable and
it may be retrieved using AbstractJavaTestScript.getVariableAsString(java.lang.String).IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int stringToString(String codeList, String variableName) throws IOException
The method provides access to functionality of the String tostring command. Creates a new text from one or more semicolon separated numeric ASCII or Unicode values. This can be used to produce special characters and/or characters of national alphabets. For example, the list of "49;43;49" will be converted to "1+1".
This method is intended to support safe conversion of TPR test scripts
into Java code. Though this functionality is not natively supported by Java, test scripts which are being developed in Java
may call the StringCommand.convertUnicodeToString(java.lang.String) static method instead to save the overhead
and get the value directly.
The only difference is that the method stores the resulting text to a context variable
and returns a numeric exit code which typically indicates success (zero) or a failure
of some type.
codeList - one or more semicolon separated ASCII or Unicode numeric codes. As each
code is parsed using the Integer.decode(java.lang.String) method, it may be
either decimal, octal or hexadecimal value. For example, the list of "49;43;49"
will be converted to "1+1".variableName - optional variable name to store the resulting string to. If the
parameter is null, the value will be stored to the default variable
called _STRING._STRING variable or to the custom variable specified by the
variableName parameter and
it may be retrieved using AbstractJavaTestScript.getVariableAsString(java.lang.String).IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int stringToString(String codeList) throws IOException
The method provides access to functionality of the String tostring command. Creates a new text from one or more semicolon separated numeric ASCII or Unicode values. This can be used to produce special characters and/or characters of national alphabets. For example, the list of "49;43;49" will be converted to "1+1".
This method is intended to support safe conversion of TPR test scripts
into Java code. Though this functionality is not natively supported by Java, test scripts which are being developed in Java
may call the StringCommand.convertUnicodeToString(java.lang.String) static method instead to save the overhead
and get the value directly.
The only difference is that the method stores the resulting text to a context variable
and returns a numeric exit code which typically indicates success (zero) or a failure
of some type.
codeList - one or more semicolon separated ASCII or Unicode numeric codes. As each
code is parsed using the Integer.decode(java.lang.String) method, it may be
either decimal, octal or hexadecimal value. For example, the list of "49;43;49"
will be converted to "1+1"._STRING variable and
it may be retrieved using AbstractJavaTestScript.getVariableAsString(java.lang.String).IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int stringTrim(String text, String variableName) throws IOException
The method provides access to functionality of the String trim command. It removes all leading and trailing white space characters such as spaces, new line characters and tabulators. For example, a text like " yellow banana " will be trimmed to "yellow banana".
This method is intended to support safe conversion of TPR test scripts
into Java code. Though this functionality is not natively supported by Java, test scripts which are being developed in Java
may call the String.trim() method instead to save the overhead
and get the value directly.
The only difference is that the script method stores the resulting text to a context variable
and returns a numeric exit code which typically indicates success (zero) or a failure
of some type.
text - a text to be trimmed.variableName - optional variable name to store the resulting string to. If the
parameter is null, the value will be stored to the default variable
called _STRING._STRING variable or to the custom variable specified by the
variableName parameter and
it may be retrieved using AbstractJavaTestScript.getVariableAsString(java.lang.String).IOException - the exception is declared but never thrown because the method
does not perform any I/O operations.public int fileOpen(File inputFile, File outputFile, String id) throws IOException
Open a text or CSV file for reading and writing. The method provides access to functionality of the File open scripting language command.
inputFile - the input file. Relative file paths
are resolved again 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 fileClose() 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 fileClose()
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 fileClose() 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 file at a time. Otherwise it may be null.
Once the ID is specified, it must be used in all subsequent File command calls.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).public int fileOpen(InputStream inputStream, OutputStream outputStream, String id) throws IOException
Open a text or CSV file. The method provides access to functionality of the File open scripting language command. This method allows to specify the I/O resources as streams. It is designed to allow loading of files bundled with the Java class and/or located in a directory known relatively to the script class. A typical code example loading the "data.txt" 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.txt");
int exitCode = fileOpen(in, null, null);
} catch (IOException ex) {
ex.printStackTrace();
}
}
}
inputStream - input stream to read the text 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 file at a time. Otherwise it may be null.
Once the ID is specified, it must be used in all subsequent File command calls.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).public int fileCreate(File outputFile, String id) throws IOException
Create a new text or CSV file for reading and writing. The method provides access to functionality of the File create scripting language command.
outputFile - mandatory output file. It is always created
even though there are no changes. This behavior may be suppressed by
calling the fileClose() with the save parameter
set to false.
Be aware that the file is not physically created until the document
is closed explicitly through the fileClose()
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 fileClose() 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 file at a time. Otherwise it may be null.
Once the ID is specified, it must be used in all subsequent File command calls.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).public int fileCreate(OutputStream outputStream, String id) throws IOException
Create a text or CSV file and associate it with an output stream. The method provides access to functionality of the File create scripting language command.
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 file and the ID was not specified,
the parameter must be null.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).public int fileClose(String id, boolean save) throws IOException
Close and eventually save the specified text/CSV file. The method provides access to functionality of the File close scripting language command.
id - unique document ID specified when the document was opened or created.
If the script works just with one file 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.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).public int fileAppend(String text, String id) throws IOException
Append text to the end of the text file. The method provides access to functionality of the File append scripting language command.
id - unique document ID specified when the document was opened or created.
If the script works just with one file and the ID was not specified
at the time of opening or creation the parameter must be null.text - the text to be appended.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).public int fileInsert(String text, int line, int column, String id) throws IOException
Insert text to the position specified by the line and column parameters. The method provides access to functionality of the File insert scripting language command.
id - unique document ID specified when the document was opened or created.
If the script works just with one file and the ID was not specified
at the time of opening or creation the parameter must be null.text - the text to be appended.line - the line number where the first line in the file has the number of 1.
This parameter is mandatory.column - the column number where column number 1 refers to the position
before the very first character on the line. This parameter is optional and
defaults to 1 (beginning of the line) if it is set to a value below zero.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).public int fileFind(String text, int line, int column, String direction, String scope, String id) throws IOException
Find the first position of the specified text in the file..
The method provides access to functionality of the
File find scripting language command. If the text is found
the method returns 0 and its position are saved as the _FILE_LINE_NUMBER and _FILE_LINE_COLUMN
variables to the context from where they can be retrieved through the AbstractJavaTestScript.getVariableAsInt(java.lang.String)
method.
id - unique document ID specified when the document was opened or created.
If the script works just with one file and the ID was not specified
at the time of opening or creation the parameter must be null.text - the text to be appended.line - the line number to start the search from. The first line in the file has the number of 1.
This parameter is mandatory.column - the column to start the search from. The column number 1 refers to the position
before the very first character on the line. This parameter is optional and
defaults to 1 (beginning of the line) if it is set to a value below zero.direction - the search direction. The acceptable values are "forward" and "backward".
If the parameter is unspecified (null) the search is performed in the forward direction.scope - the search scope. The acceptable values are "line" and "file".
When the value is "line" the search is performed only from the specified position to
the end or beginning of the line depending on the selected direction. When the value is
"file" the file is searched from the specified position to the end or beginning of file
depending on the selected direction. If the parameter is unspecified (null) it
defaults to the "file" scope..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).public int fileRead(int line,
int column,
int length,
String id)
throws IOException
Read text of a single line from the position specified by line, column and length parameters.
The method provides access to functionality of the
File read scripting language command. When the text is read correctly
the method returns 0 and saves it under the _FILE_READ
variable to the context from where it can be retrieved through the AbstractJavaTestScript.getVariableAsString(java.lang.String)
method.
id - unique document ID specified when the document was opened or created.
If the script works just with one file and the ID was not specified
at the time of opening or creation the parameter must be null.line - the line number where the first line in the file has the number of 1.
This parameter is mandatory.column - the column number where column number 1 refers to the position
before the very first character on the line. This parameter is optional and
defaults to 1 (beginning of the line) if it is set to a value below zero.length - the text length to be read. It must be lower than or equal to the
number of characters available between the specified position and the end of the line.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).public int fileParse(int line,
String separator,
String delimeter,
boolean trim,
String id)
throws IOException
Parse the specified line into values by the given separator and delimeter.
The method provides access to functionality of the
File parse scripting language command. When the text is parsed correctly
the method returns 0 and saves the value count to the _FILE_PARSE_COUNT
variable in the context from where they can be retrieved through the AbstractJavaTestScript.getVariableAsInt(java.lang.String)
method. The values are then saved to numbered variables like _FILE_PARSE_VALUE1, _FILE_PARSE_VALUE2 ...
When the separator is not specified it defaults to comma (,). When the delimeter is not specified it defaults to double quote ("). These two parameters together with the disabled trimming mode (trim=false) parse the text in a way which is compatible with the RFC 4180 defined Comma Separated Values (CSV) format.
id - unique document ID specified when the document was opened or created.
If the script works just with one file and the ID was not specified
at the time of opening or creation the parameter must be null.line - the line number where the first line in the file has the number of 1.
This parameter is mandatory.separator - the value separator. When it is null it defaults to comma (,).delimeter - the value delimeter. When it is null it defaults to double quote (").trim - the value of false leaves the values exactly as they were
parsed while the value of true trims all leading and trailing white spaces
from every single value through String.trim().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).public int fileParse(int line,
String id)
throws IOException
Parse the specified CSV line into values using the rules defined by
the RFC 4180.
The method provides access to functionality of the
File parse scripting language command with the default separator of
comma (,), the default delimeter of double quote (") and trimming set off. When the text is parsed correctly
the method returns 0 and saves the value count to the _FILE_PARSE_COUNT
variable in the context from where they can be retrieved through the AbstractJavaTestScript.getVariableAsInt(java.lang.String)
method. The values are then saved to numbered variables like _FILE_PARSE_VALUE1, _FILE_PARSE_VALUE2 ...
id - unique document ID specified when the document was opened or created.
If the script works just with one file and the ID was not specified
at the time of opening or creation the parameter must be null.line - the line number where the first line in the file has the number of 1.
This parameter is mandatory.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).public int fileParse(int line,
String pattern,
boolean trim,
String id)
throws IOException
Parse the specified line into values by the given java.util.regex.Pattern compatible
regular expression.
The method provides access to functionality of the
File parse scripting language command. When the text is parsed correctly
the method returns 0 and saves the value count to the _FILE_PARSE_COUNT
variable in the context from where they can be retrieved through the AbstractJavaTestScript.getVariableAsInt(java.lang.String)
method. The values are then saved to numbered variables like _FILE_PARSE_VALUE1, _FILE_PARSE_VALUE2 ...
id - unique document ID specified when the document was opened or created.
If the script works just with one file and the ID was not specified
at the time of opening or creation the parameter must be null.line - the line number where the first line in the file has the number of 1.
This parameter is mandatory.pattern - a java.util.regex.Pattern compatible
regular expression. It may not be null.trim - the value of false leaves the values exactly as they were
parsed while the value of true trims all leading and trailing white spaces
from every single value through String.trim().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).public int fileDelete(int line,
int column,
int length,
String id)
throws IOException
Delete the text specified by the line/column numbers and length.. The method provides access to functionality of the File delete scripting language command.
id - unique document ID specified when the document was opened or created.
If the script works just with one file and the ID was not specified
at the time of opening or creation the parameter must be null.line - the line number where the first line in the file has the number of 1.
This parameter is mandatory.column - the column number where column number 1 refers to the position
before the very first character on the line. This parameter is optional and
defaults to 1 (beginning of the line) if it is set to a value below zero.length - number of characters to be deleted. The resulting delete area defined by line/column and length
may exceed the text line bounds and in such a case the delete operation is applied
to the terminating new line character and then to the following line or lines. If the length
exceeds the the file size, all the content file content after the specified position is deleted.
If the length parameter is not specified (it is below 0) the method deletes all characters to the end of
the specified line including the terminating new line character.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).public int log(String message, Level level) throws IOException
Log a message to the script execution log. The method provides access to functionality of the Log scripting language command.
message - the log message.level - one of the levels defined in the Level class except
for the Level.OFF one.IOException - is declared but never thrown because the command
doesn't invoke any I/O operation (logs are stored just in the memory until
the script finishes).public int log(String message, Level level, boolean terminal, boolean history) throws IOException
Log a message to the script execution log. The method provides access to functionality of the Log scripting language command.
message - the log message.level - one of the levels defined in the Level class except
for the Level.OFF one.terminal - the value of true will print out the message also to the
terminal (command prompt). The default value is false (no terminal
output).history - The value of true will make the command record the most
recent script history into the log file. This includes the most recent
detailed logs and debug screen shots. Use it to track what had happened
before the script produced an error. If the script history recording
feature is disabled in the Log command preferences it is skipped.
The default value is 'false'. Supported since v4.4.2.IOException - is declared but never thrown because the command
doesn't invoke any I/O operation (logs are stored just in the memory until
the script finishes).public int log(String message, Level level, boolean terminal) throws IOException
Log a message to the script execution log. The method provides access to functionality of the Log scripting language command.
message - the log message.level - one of the levels defined in the Level class except
for the Level.OFF one.terminal - the value of true will print out the message also to the
terminal (command prompt). The default value is false (no terminal output).IOException - is declared but never thrown because the command
doesn't invoke any I/O operation (logs are stored just in the memory until
the script finishes).public int imageDoctorOn()
throws IOException
Set on the Image Doctor wizard. If the wizard is already on it does nothing. The method provides access to functionality of the ImageDoctor scripting language command.
IOException - is declared but never thrown because the command
doesn't invoke any I/O operation.public int imageDoctorOff()
throws IOException
Set off the Image Doctor wizard. If the wizard is already on it does nothing. The method provides access to functionality of the ImageDoctor scripting language command.
IOException - is declared but never thrown because the command
doesn't invoke any I/O operation.public int imageDoctorSkip()
throws IOException
Set on an internal flag which will make the Image Doctor wizard ignore result of the next comparison command (method call). If the wizard is off it will have no effect. The flag will be cleared after any call of image comparison.
The method provides access to functionality of the ImageDoctor scripting language command.
IOException - is declared but never thrown because the command
doesn't invoke any I/O operation.public int setVariable(String... params) throws IOException
Set one or more context variables. This is a convenience method which
provides mapping onto the Var,
Varf and Eval scripting
language commands. It was introduced in 3.5.1 to enable editing of
setVariable() calls through the "Properties" window
in the Java test script editor. When the Java code is being written
outside of the Robot GUI it is more efficient to set the variable
directly through the
getContext().setVariable(java.lang.String, java.lang.Object)
method.
params - an even number of variable [name, value] pairs. For
example, a call like var("test", "Line #1\nLine #2") will
store the two line text to the "test" context variable.IOException - the exception is just declared but never thrown.IllegalArgumentException - when the method is called with no
arguments or their number is odd.public int clickImage(File[] templates, int button, int modifiers, int count, Point move, float passRate, int number, Rectangle cmpArea, String timeout, String sort, float[] scale, String stepName, boolean continueScript, String wait) throws IOException
Look for a component (a button, field, ...) on the screen by the specified image(s) and click it. It provides access to functionality of the Click image scripting language command. The method combines functionality of the Waitfor match, Mouse click and Exit commands to perform the following sequence of tasks:
number parameter can be used to specify which instance
to click.number parameter the method calls the Exit
command to terminate the script.As the method is a synthetic one it naturally supports parameters of the two participating commands (Waitfor match, Mouse click) and the search2 algorithm.
templates - the list of template images and/or
image collections. This parameter is mandatory.button - the mouse button to click. Supported values are
MouseEvent.BUTTON1 (left button, 1), MouseEvent.BUTTON2
(middle button, 2) and MouseEvent.BUTTON3, 3 (right button). If
any other value is used the argument defaults to the left button.modifiers - modifier mask as specified in the
InputEvent. For example, to specify Ctrl+Alt use
InputEvent.CTRL_MASK | InputEvent.ALT_MASKcount - how many times to click. The default value is 1 (one click).
Delays among multiple clicks are defined by a value in the Mouse command
user preferences.passRate - the "search2" pass rate as a percentage between 0 and
100. The value of 100 indicates that exact match is required (100%
matching). To use the default pass rate of 50% set the parameter to a
value equal to or lower than zero.number - number of the component to apply the click to. The default
value is 1 (click the first component). The value of 0 (zero) will click
the last component. Negative values will click components in the reversed
order. For example, the value of -1 will click onto the second last
component, the value of -2 onto the third last component etc.
The order of located components is subject to the selected sort mode.
See the sort parameter for details. The default best
mode will put the best matching components to the top of the
list. If there are matches with the same match ratio they are sorted in
the reading order (from the top to the bottom, from the left to the
right). With this sort mode the number of 1 will click the
best matching location on the screen while the value of 0 will click the
worst matching one. This mechanism allows to deal with false matches
caused by the tolerant search for the pass rate lower than 100%.
cmpArea - the screen rectangle to limit the search to. To search the
whole screen set it to null.timeout - the maximum time to wait for the component to. 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 the method applies
the default Click command timeout of 30 seconds.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)."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:
stepName - step name (optional). When provided the method will
create a step of the specified name and add it to the report. The step
will be "pass" if the component is found and clicked successfully or
"fail" otherwise.move - relative coordinates allowing to apply the click to a
custom location (optional). Use this option to implement actions such as
"click XXX pixels to the right from the component". The coordinates are
calculated against the component center. The distance parameter overrides
the click point specified in the component image properties. To bypass
the click point and click the image center use the point of [0, 0].continueScript - the value of true will make the method
not to terminate the script when the component is not found.wait - the time to wait after the object is found and clicked. 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).number
parameter is higher than the number of components found).IOException - when one of the argument images doesn't exist or
cannot be read or when the underlying desktop connection throws an I/O
error.public int clickImage(File[] templates, int button, int modifiers, int count, float passRate, int number, Rectangle cmpArea, String timeout, String sort, float[] scale, String wait) throws IOException
Look for a component (a button, field, ...) on the screen by the specified image(s) and click it. It provides access to functionality of the Click image scripting language command. The method combines functionality of the Waitfor match, Mouse click and Exit commands to perform the following sequence of tasks:
number parameter can be used to specify which instance
to click.number parameter the method calls the Exit
command to terminate the script.As the method is a synthetic one it naturally supports parameters of the two participating commands (Waitfor match, Mouse click) and the search2 algorithm.
templates - the list of template images and/or
image collections. This parameter is mandatory.button - the mouse button to click. Supported values are
MouseEvent.BUTTON1 (left button, 1), MouseEvent.BUTTON2
(middle button, 2) and MouseEvent.BUTTON3, 3 (right button). If
any other value is used the argument defaults to the left button.modifiers - modifier mask as specified in the
InputEvent. For example, to specify Ctrl+Alt use
InputEvent.CTRL_MASK | InputEvent.ALT_MASKcount - how many times to click. The default value is 1 (one click).
Delays among multiple clicks are defined by a value in the Mouse command
user preferences.passRate - the "search2" pass rate as a percentage between 0 and
100. The value of 100 indicates that exact match is required (100%
matching). To use the default pass rate of 50% set the parameter to a
value equal to or lower than zero.number - number of the component to apply the click to. The default
value is 1 (click the first component). The value of 0 (zero) will click
the last component. Negative values will click components in the reversed
order. For example, the value of -1 will click onto the second last
component, the value of -2 onto the third last component etc.
The order of located components is subject to the selected sort mode.
See the sort parameter for details. The default best
mode will put the best matching components to the top of the
list. If there are matches with the same match ratio they are sorted in
the reading order (from the top to the bottom, from the left to the
right). With this sort mode the number of 1 will click the
best matching location on the screen while the value of 0 will click the
worst matching one. This mechanism allows to deal with false matches
caused by the tolerant search for the pass rate lower than 100%.
cmpArea - the screen rectangle to limit the search to. To search the
whole screen set it to null.timeout - the maximum time to wait for the component to. 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 the method applies
the default Click command timeout of 30 seconds.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)."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:
wait - the time to wait after the object is found and clicked. 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).number
parameter is higher than the number of components found).IOException - when one of the argument images doesn't exist or
cannot be read or when the underlying desktop connection throws an I/O
error.public int clickImage(Image[] templates, int button, int modifiers, int count, float passRate, int number, Rectangle cmpArea, String timeout, String sort, float[] scale, String wait) throws IOException
Look for a component (a button, field, ...) on the screen by the specified image(s) and click it. It provides access to functionality of the Click image scripting language command. The method combines functionality of the Waitfor match, Mouse click and Exit commands to perform the following sequence of tasks:
number parameter can be used to specify which instance
to click.number parameter the method calls the Exit
command to terminate the script.As the method is a synthetic one it naturally supports parameters of the two participating commands (Waitfor match, Mouse click) and the search2 algorithm.
templates - the list of template images and/or
image collections. This parameter is mandatory.button - the mouse button to click. Supported values are
MouseEvent.BUTTON1 (left button, 1), MouseEvent.BUTTON2
(middle button, 2) and MouseEvent.BUTTON3, 3 (right button). If
any other value is used the argument defaults to the left button.modifiers - modifier mask as specified in the
InputEvent. For example, to specify Ctrl+Alt use
InputEvent.CTRL_MASK | InputEvent.ALT_MASKcount - how many times to click. The default value is 1 (one click).
Delays among multiple clicks are defined by a value in the Mouse command
user preferences.passRate - the "search2" pass rate as a percentage between 0 and
100. The value of 100 indicates that exact match is required (100%
matching). To use the default pass rate of 50% set the parameter to a
value equal to or lower than zero.number - number of the component to apply the click to. The default
value is 1 (click the first component). The value of 0 (zero) will click
the last component. Negative values will click components in the reversed
order. For example, the value of -1 will click onto the second last
component, the value of -2 onto the third last component etc.
The order of located components is subject to the selected sort mode.
See the sort parameter for details. The default best
mode will put the best matching components to the top of the
list. If there are matches with the same match ratio they are sorted in
the reading order (from the top to the bottom, from the left to the
right). With this sort mode the number of 1 will click the
best matching location on the screen while the value of 0 will click the
worst matching one. This mechanism allows to deal with false matches
caused by the tolerant search for the pass rate lower than 100%.
cmpArea - the screen rectangle to limit the search to. To search the
whole screen set it to null.timeout - the maximum time to wait for the component to. 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 the method applies
the default Click command timeout of 30 seconds.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)."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:
wait - the time to wait after the object is found and clicked. 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).number
parameter is higher than the number of components found).IOException - when one of the argument images doesn't exist or
cannot be read or when the underlying desktop connection throws an I/O
error.public int clickImage(Image[] templates, int button, int modifiers, int count, Point move, float passRate, int number, Rectangle cmpArea, String timeout, String sort, float[] scale, String stepName, boolean continueScript, String wait) throws IOException
Look for a component (a button, field, ...) on the screen by the specified image(s) and click it. It provides access to functionality of the Click image scripting language command. The method combines functionality of the Waitfor match, Mouse click and Exit commands to perform the following sequence of tasks:
number parameter can be used to specify which instance
to click.number parameter the method calls the Exit
command to terminate the script.As the method is a synthetic one it naturally supports parameters of the two participating commands (Waitfor match, Mouse click) and the search2 algorithm.
templates - the list of template images and/or
image collections. This parameter is mandatory.button - the mouse button to click. Supported values are
MouseEvent.BUTTON1 (left button, 1), MouseEvent.BUTTON2
(middle button, 2) and MouseEvent.BUTTON3, 3 (right button). If
any other value is used the argument defaults to the left button.modifiers - modifier mask as specified in the
InputEvent. For example, to specify Ctrl+Alt use
InputEvent.CTRL_MASK | InputEvent.ALT_MASKcount - how many times to click. The default value is 1 (one click).
Delays among multiple clicks are defined by a value in the Mouse command
user preferences.passRate - the "search2" pass rate as a percentage between 0 and
100. The value of 100 indicates that exact match is required (100%
matching). To use the default pass rate of 50% set the parameter to a
value equal to or lower than zero.number - number of the component to apply the click to. The default
value is 1 (click the first component). The value of 0 (zero) will click
the last component. Negative values will click components in the reversed
order. For example, the value of -1 will click onto the second last
component, the value of -2 onto the third last component etc.
The order of located components is subject to the selected sort mode.
See the sort parameter for details. The default best
mode will put the best matching components to the top of the
list. If there are matches with the same match ratio they are sorted in
the reading order (from the top to the bottom, from the left to the
right). With this sort mode the number of 1 will click the
best matching location on the screen while the value of 0 will click the
worst matching one. This mechanism allows to deal with false matches
caused by the tolerant search for the pass rate lower than 100%.
cmpArea - the screen rectangle to limit the search to. To search the
whole screen set it to null.timeout - the maximum time to wait for the component to. 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 the method applies
the default Click command timeout of 30 seconds.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)."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:
stepName - step name (optional). When provided the method will
create a step of the specified name and add it to the report. The step
will be "pass" if the component is found and clicked successfully or
"fail" otherwise.move - relative coordinates allowing to apply the click to a
custom location (optional). Use this option to implement actions such as
"click XXX pixels to the right from the component". The coordinates are
calculated against the component center. The distance parameter overrides
the click point specified in the component image properties. To bypass
the click point and click the image center use the point of [0, 0].continueScript - the value of true will make the method
not to terminate the script when the component is not found.wait - the time to wait after the object is found and clicked. 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).number
parameter is higher than the number of components found).IOException - when one of the argument images doesn't exist or
cannot be read or when the underlying desktop connection throws an I/O
error.public int clickImage(File[] templates, float passRate, int number, Rectangle cmpArea, String timeout, String sort, float[] scale, String wait) throws IOException
Look for a component (a button, field, ...) on the screen by the specified image(s) and click it. It provides access to functionality of the Click image scripting language command.
This is a convenience method which calls the clickImage(java.io.File[], int, int, int, float, int, java.awt.Rectangle, java.lang.String, java.lang.String, float[], java.lang.String)
one to perform a single left mouse button click onto the target
component.
templates - the list of template images and/or
image collections. This parameter is mandatory.passRate - the "search2" pass rate as a percentage between 0 and
100. The value of 100 indicates that exact match is required (100%
matching). To use the default pass rate of 50% set the parameter to a
value equal to or lower than zero.number - number of the component to apply the click to. The default
value is 1 (click the first component). The value of 0 (zero) will click
the last component. Negative values will click components in the reversed
order. For example, the value of -1 will click onto the second last
component, the value of -2 onto the third last component etc.
The order of located components is subject to the selected sort mode.
See the sort parameter for details. The default best
mode will put the best matching components to the top of the
list. If there are matches with the same match ratio they are sorted in
the reading order (from the top to the bottom, from the left to the
right). With this sort mode the number of 1 will click the
best matching location on the screen while the value of 0 will click the
worst matching one. This mechanism allows to deal with false matches
caused by the tolerant search for the pass rate lower than 100%.
cmpArea - the screen rectangle to limit the search to. To search the
whole screen set it to null.timeout - the maximum time to wait for the component to. 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 the method applies
the default Click command timeout of 30 seconds.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)."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:
wait - the time to wait after the object is found and clicked. 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).number
parameter is higher than the number of components found).IOException - when one of the argument images doesn't exist or
cannot be read or when the underlying desktop connection throws an I/O
error.public int rightClickImage(File[] templates, float passRate, int number, Point move, Rectangle cmpArea, String timeout, String sort, float[] scale, String stepName, boolean continueScript, String wait) throws IOException
Look for a component (a button, field, ...) on the screen by the specified image(s) and right click it. It provides access to functionality of the Click image scripting language command.
This is a convenience method which calls the clickImage(java.io.File[], int, int, int, float, int, java.awt.Rectangle, java.lang.String, java.lang.String, float[], java.lang.String)
one to perform a single right mouse button click onto the target
component.
templates - the list of template images and/or
image collections. This parameter is mandatory.passRate - the "search2" pass rate as a percentage between 0 and
100. The value of 100 indicates that exact match is required (100%
matching). To use the default pass rate of 50% set the parameter to a
value equal to or lower than zero.number - number of the component to apply the click to. The default
value is 1 (click the first component). The value of 0 (zero) will click
the last component. Negative values will click components in the reversed
order. For example, the value of -1 will click onto the second last
component, the value of -2 onto the third last component etc.
The order of located components is subject to the selected sort mode.
See the sort parameter for details. The default best
mode will put the best matching components to the top of the
list. If there are matches with the same match ratio they are sorted in
the reading order (from the top to the bottom, from the left to the
right). With this sort mode the number of 1 will click the
best matching location on the screen while the value of 0 will click the
worst matching one. This mechanism allows to deal with false matches
caused by the tolerant search for the pass rate lower than 100%.
cmpArea - the screen rectangle to limit the search to. To search the
whole screen set it to null.timeout - the maximum time to wait for the component to. 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 the method applies
the default Click command timeout of 30 seconds.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)."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:
stepName - step name (optional). When provided the method will
create a step of the specified name and add it to the report. The step
will be "pass" if the component is found and clicked successfully or
"fail" otherwise.move - relative coordinates allowing to apply the click to a
custom location (optional). Use this option to implement actions such as
"click XXX pixels to the right from the component". The coordinates are
calculated against the component center. The distance parameter overrides
the click point specified in the component image properties. To bypass
the click point and click the image center use the point of [0, 0].continueScript - the value of true will make the method
not to terminate the script when the component is not found.wait - the time to wait after the object is found and clicked. 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).number
parameter is higher than the number of components found).IOException - when one of the argument images doesn't exist or
cannot be read or when the underlying desktop connection throws an I/O
error.public int rightClickImage(File[] templates, float passRate, int number, Rectangle cmpArea, String timeout, String sort, float[] scale, String wait) throws IOException
Look for a component (a button, field, ...) on the screen by the specified image(s) and right click it. It provides access to functionality of the Click image scripting language command.
This is a convenience method which calls the clickImage(java.io.File[], int, int, int, float, int, java.awt.Rectangle, java.lang.String, java.lang.String, float[], java.lang.String)
one to perform a single right mouse button click onto the target
component.
templates - the list of template images and/or
image collections. This parameter is mandatory.passRate - the "search2" pass rate as a percentage between 0 and
100. The value of 100 indicates that exact match is required (100%
matching). To use the default pass rate of 50% set the parameter to a
value equal to or lower than zero.number - number of the component to apply the click to. The default
value is 1 (click the first component). The value of 0 (zero) will click
the last component. Negative values will click components in the reversed
order. For example, the value of -1 will click onto the second last
component, the value of -2 onto the third last component etc.
The order of located components is subject to the selected sort mode.
See the sort parameter for details. The default best
mode will put the best matching components to the top of the
list. If there are matches with the same match ratio they are sorted in
the reading order (from the top to the bottom, from the left to the
right). With this sort mode the number of 1 will click the
best matching location on the screen while the value of 0 will click the
worst matching one. This mechanism allows to deal with false matches
caused by the tolerant search for the pass rate lower than 100%.
cmpArea - the screen rectangle to limit the search to. To search the
whole screen set it to null.timeout - the maximum time to wait for the component to. 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 the method applies
the default Click command timeout of 30 seconds.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)."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:
wait - the time to wait after the object is found and clicked. 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).number
parameter is higher than the number of components found).IOException - when one of the argument images doesn't exist or
cannot be read or when the underlying desktop connection throws an I/O
error.public int doubleClickImage(File[] templates, float passRate, int number, Point move, Rectangle cmpArea, String timeout, String sort, float[] scale, String stepName, boolean continueScript, String wait) throws IOException
Look for a component (a button, field, ...) on the screen by the specified image(s) and double click it. It provides access to functionality of the Click image scripting language command.
This is a convenience method which calls the clickImage(java.io.File[], int, int, int, float, int, java.awt.Rectangle, java.lang.String, java.lang.String, float[], java.lang.String)
one to perform a double left mouse button click onto the target
component.
templates - the list of template images and/or
image collections. This parameter is mandatory.passRate - the "search2" pass rate as a percentage between 0 and
100. The value of 100 indicates that exact match is required (100%
matching). To use the default pass rate of 50% set the parameter to a
value equal to or lower than zero.number - number of the component to apply the click to. The default
value is 1 (click the first component). The value of 0 (zero) will click
the last component. Negative values will click components in the reversed
order. For example, the value of -1 will click onto the second last
component, the value of -2 onto the third last component etc.
The order of located components is subject to the selected sort mode.
See the sort parameter for details. The default best
mode will put the best matching components to the top of the
list. If there are matches with the same match ratio they are sorted in
the reading order (from the top to the bottom, from the left to the
right). With this sort mode the number of 1 will click the
best matching location on the screen while the value of 0 will click the
worst matching one. This mechanism allows to deal with false matches
caused by the tolerant search for the pass rate lower than 100%.
cmpArea - the screen rectangle to limit the search to. To search the
whole screen set it to null.timeout - the maximum time to wait for the component to. 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 the method applies
the default Click command timeout of 30 seconds.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)."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:
stepName - step name (optional). When provided the method will
create a step of the specified name and add it to the report. The step
will be "pass" if the component is found and clicked successfully or
"fail" otherwise.move - relative coordinates allowing to apply the click to a
custom location (optional). Use this option to implement actions such as
"click XXX pixels to the right from the component". The coordinates are
calculated against the component center. The distance parameter overrides
the click point specified in the component image properties. To bypass
the click point and click the image center use the point of [0, 0].continueScript - the value of true will make the method
not to terminate the script when the component is not found.wait - the time to wait after the object is found and clicked. 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).number
parameter is higher than the number of components found).IOException - when one of the argument images doesn't exist or
cannot be read or when the underlying desktop connection throws an I/O
error.public int doubleClickImage(File[] templates, float passRate, int number, Rectangle cmpArea, String timeout, String sort, float[] scale, String wait) throws IOException
Look for a component (a button, field, ...) on the screen by the specified image(s) and double click it. It provides access to functionality of the Click image scripting language command.
This is a convenience method which calls the clickImage(java.io.File[], int, int, int, float, int, java.awt.Rectangle, java.lang.String, java.lang.String, float[], java.lang.String)
one to perform a double left mouse button click onto the target
component.
templates - the list of template images and/or
image collections. This parameter is mandatory.passRate - the "search2" pass rate as a percentage between 0 and
100. The value of 100 indicates that exact match is required (100%
matching). To use the default pass rate of 50% set the parameter to a
value equal to or lower than zero.number - number of the component to apply the click to. The default
value is 1 (click the first component). The value of 0 (zero) will click
the last component. Negative values will click components in the reversed
order. For example, the value of -1 will click onto the second last
component, the value of -2 onto the third last component etc.
The order of located components is subject to the selected sort mode.
See the sort parameter for details. The default best
mode will put the best matching components to the top of the
list. If there are matches with the same match ratio they are sorted in
the reading order (from the top to the bottom, from the left to the
right). With this sort mode the number of 1 will click the
best matching location on the screen while the value of 0 will click the
worst matching one. This mechanism allows to deal with false matches
caused by the tolerant search for the pass rate lower than 100%.
cmpArea - the screen rectangle to limit the search to. To search the
whole screen set it to null.timeout - the maximum time to wait for the component to. 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 the method applies
the default Click command timeout of 30 seconds.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)."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:
wait - the time to wait after the object is found and clicked. 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).number
parameter is higher than the number of components found).IOException - when one of the argument images doesn't exist or
cannot be read or when the underlying desktop connection throws an I/O
error.public int clickImage(File[] templates, int number, String wait) throws IOException
Look for a component (a button, field, ...) on the screen by the specified image(s) and click it. It provides access to functionality of the Click image scripting language command.
This is a convenience method which calls the clickImage(java.io.File[], int, int, int, float, int, java.awt.Rectangle, java.lang.String, java.lang.String, float[], java.lang.String)
one to perform a full screen search for the specified component with the
default values of timeout (30 seconds), the "search" pass rate (50%) and
sort mode (best matching locations first). If found the method applies
a single left mouse button click to the target component.
templates - the list of template images and/or
image collections. This parameter is mandatory.number - number of the component to apply the click to. The default
value is 1 (click the first component). The value of 0 (zero) will click
the last component. Negative values will click components in the reversed
order. For example, the value of -1 will click onto the second last
component, the value of -2 onto the third last component etc.
The order of located components is subject to the selected sort mode.
See the sort parameter for details. The default best
mode will put the best matching components to the top of the
list. If there are matches with the same match ratio they are sorted in
the reading order (from the top to the bottom, from the left to the
right). With this sort mode the number of 1 will click the
best matching location on the screen while the value of 0 will click the
worst matching one. This mechanism allows to deal with false matches
caused by the tolerant search for the pass rate lower than 100%.
wait - the time to wait after the object is found and clicked. 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).number
parameter is higher than the number of components found).IOException - when one of the argument images doesn't exist or
cannot be read or when the underlying desktop connection throws an I/O
error.public int rightClickImage(File[] templates, int number, String wait) throws IOException
Look for a component (a button, field, ...) on the screen by the specified image(s) and right click it. It provides access to functionality of the Click image scripting language command.
This is a convenience method which calls the clickImage(java.io.File[], int, int, int, float, int, java.awt.Rectangle, java.lang.String, java.lang.String, float[], java.lang.String)
one to perform a full screen search for the specified component with the
default values of timeout (30 seconds), the "search" pass rate (50%) and
sort mode (best matching locations first). If found the method applies
a single right mouse button click to the target component.
templates - the list of template images and/or
image collections. This parameter is mandatory.number - number of the component to apply the click to. The default
value is 1 (click the first component). The value of 0 (zero) will click
the last component. Negative values will click components in the reversed
order. For example, the value of -1 will click onto the second last
component, the value of -2 onto the third last component etc.
The order of located components is subject to the selected sort mode.
See the sort parameter for details. The default best
mode will put the best matching components to the top of the
list. If there are matches with the same match ratio they are sorted in
the reading order (from the top to the bottom, from the left to the
right). With this sort mode the number of 1 will click the
best matching location on the screen while the value of 0 will click the
worst matching one. This mechanism allows to deal with false matches
caused by the tolerant search for the pass rate lower than 100%.
wait - the time to wait after the object is found and clicked. 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).number
parameter is higher than the number of components found).IOException - when one of the argument images doesn't exist or
cannot be read or when the underlying desktop connection throws an I/O
error.public int doubleClickImage(File[] templates, int number, String wait) throws IOException
Look for a component (a button, field, ...) on the screen by the specified image(s) and double click it. It provides access to functionality of the Click image scripting language command.
This is a convenience method which calls the clickImage(java.io.File[], int, int, int, float, int, java.awt.Rectangle, java.lang.String, java.lang.String, float[], java.lang.String)
one to perform a full screen search for the specified component with the
default values of timeout (30 seconds), the "search" pass rate (50%) and
sort mode (best matching locations first). If found the method applies
a double left mouse button click to the target component.
templates - the list of template images and/or
image collections. This parameter is mandatory.number - number of the component to apply the click to. The default
value is 1 (click the first component). The value of 0 (zero) will click
the last component. Negative values will click components in the reversed
order. For example, the value of -1 will click onto the second last
component, the value of -2 onto the third last component etc.
The order of located components is subject to the selected sort mode.
See the sort parameter for details. The default best
mode will put the best matching components to the top of the
list. If there are matches with the same match ratio they are sorted in
the reading order (from the top to the bottom, from the left to the
right). With this sort mode the number of 1 will click the
best matching location on the screen while the value of 0 will click the
worst matching one. This mechanism allows to deal with false matches
caused by the tolerant search for the pass rate lower than 100%.
wait - the time to wait after the object is found and clicked. 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).number
parameter is higher than the number of components found).IOException - when one of the argument images doesn't exist or
cannot be read or when the underlying desktop connection throws an I/O
error.public int clickImage(File[] templates, int number) throws IOException
Look for a component (a button, field, ...) on the screen by the specified image(s) and click it. It provides access to functionality of the Click image scripting language command.
This is a convenience method which calls the clickImage(java.io.File[], int, int, int, float, int, java.awt.Rectangle, java.lang.String, java.lang.String, float[], java.lang.String)
one to perform a full screen search for the specified component with the
default values of timeout (30 seconds), the "search" pass rate (50%) and
sort mode (best matching locations first). If found the method applies
a single left mouse button click to the target component.
templates - the list of template images and/or
image collections. This parameter is mandatory.number - number of the component to apply the click to. The default
value is 1 (click the first component). The value of 0 (zero) will click
the last component. Negative values will click components in the reversed
order. For example, the value of -1 will click onto the second last
component, the value of -2 onto the third last component etc.
The order of located components is subject to the selected sort mode.
See the sort parameter for details. The default best
mode will put the best matching components to the top of the
list. If there are matches with the same match ratio they are sorted in
the reading order (from the top to the bottom, from the left to the
right). With this sort mode the number of 1 will click the
best matching location on the screen while the value of 0 will click the
worst matching one. This mechanism allows to deal with false matches
caused by the tolerant search for the pass rate lower than 100%.
number
parameter is higher than the number of components found).IOException - when one of the argument images doesn't exist or
cannot be read or when the underlying desktop connection throws an I/O
error.public int rightClickImage(File[] templates, int number) throws IOException
Look for a component (a button, field, ...) on the screen by the specified image(s) and right click it. It provides access to functionality of the Click image scripting language command.
This is a convenience method which calls the clickImage(java.io.File[], int, int, int, float, int, java.awt.Rectangle, java.lang.String, java.lang.String, float[], java.lang.String)
one to perform a full screen search for the specified component with the
default values of timeout (30 seconds), the "search" pass rate (50%) and
sort mode (best matching locations first). If found the method applies
a single right mouse button click to the target component.
templates - the list of template images and/or
image collections. This parameter is mandatory.number - number of the component to apply the click to. The default
value is 1 (click the first component). The value of 0 (zero) will click
the last component. Negative values will click components in the reversed
order. For example, the value of -1 will click onto the second last
component, the value of -2 onto the third last component etc.
The order of located components is subject to the selected sort mode.
See the sort parameter for details. The default best
mode will put the best matching components to the top of the
list. If there are matches with the same match ratio they are sorted in
the reading order (from the top to the bottom, from the left to the
right). With this sort mode the number of 1 will click the
best matching location on the screen while the value of 0 will click the
worst matching one. This mechanism allows to deal with false matches
caused by the tolerant search for the pass rate lower than 100%.
number
parameter is higher than the number of components found).IOException - when one of the argument images doesn't exist or
cannot be read or when the underlying desktop connection throws an I/O
error.public int doubleClickImage(File[] templates, int number) throws IOException
Look for a component (a button, field, ...) on the screen by the specified image(s) and double click it. It provides access to functionality of the Click image scripting language command.
This is a convenience method which calls the clickImage(java.io.File[], int, int, int, float, int, java.awt.Rectangle, java.lang.String, java.lang.String, float[], java.lang.String)
one to perform a full screen search for the specified component with the
default values of timeout (30 seconds), the "search" pass rate (50%) and
sort mode (best matching locations first). If found the method applies
a double left mouse button click to the target component.
templates - the list of template images and/or
image collections. This parameter is mandatory.number - number of the component to apply the click to. The default
value is 1 (click the first component). The value of 0 (zero) will click
the last component. Negative values will click components in the reversed
order. For example, the value of -1 will click onto the second last
component, the value of -2 onto the third last component etc.
The order of located components is subject to the selected sort mode.
See the sort parameter for details. The default best
mode will put the best matching components to the top of the
list. If there are matches with the same match ratio they are sorted in
the reading order (from the top to the bottom, from the left to the
right). With this sort mode the number of 1 will click the
best matching location on the screen while the value of 0 will click the
worst matching one. This mechanism allows to deal with false matches
caused by the tolerant search for the pass rate lower than 100%.
number
parameter is higher than the number of components found).IOException - when one of the argument images doesn't exist or
cannot be read or when the underlying desktop connection throws an I/O
error.public int clickImage(File[] templates) throws IOException
Look for a component (a button, field, ...) on the screen by the specified image(s) and click it. It provides access to functionality of the Click image scripting language command.
This is a convenience method which calls the clickImage(java.io.File[], int, int, int, float, int, java.awt.Rectangle, java.lang.String, java.lang.String, float[], java.lang.String)
one to perform a full screen search for the specified component with the
default values of timeout (30 seconds), the "search" pass rate (50%) and
sort mode (best matching locations first). If found the method applies
a left mouse button click to the first located component.
templates - the list of template images and/or
image collections. This parameter is mandatory.number
parameter is higher than the number of components found).IOException - when one of the argument images doesn't exist or
cannot be read or when the underlying desktop connection throws an I/O
error.public int rightClickImage(File[] templates) throws IOException
Look for a component (a button, field, ...) on the screen by the specified image(s) and right click it. It provides access to functionality of the Click image scripting language command.
This is a convenience method which calls the clickImage(java.io.File[], int, int, int, float, int, java.awt.Rectangle, java.lang.String, java.lang.String, float[], java.lang.String)
one to perform a full screen search for the specified component with the
default values of timeout (30 seconds), the "search" pass rate (50%) and
sort mode (best matching locations first). If found the method applies
a right mouse button click to the first located component.
templates - the list of template images and/or
image collections. This parameter is mandatory.number
parameter is higher than the number of components found).IOException - when one of the argument images doesn't exist or
cannot be read or when the underlying desktop connection throws an I/O
error.public int doubleClickImage(File[] templates) throws IOException
Look for a component (a button, field, ...) on the screen by the specified image(s) and double click it. It provides access to functionality of the Click image scripting language command.
This is a convenience method which calls the clickImage(java.io.File[], int, int, int, float, int, java.awt.Rectangle, java.lang.String, java.lang.String, float[], java.lang.String)
one to perform a full screen search for the specified component with the
default values of timeout (30 seconds), the "search" pass rate (50%) and
sort mode (best matching locations first). If found the method applies
a double left mouse button click to the first located component.
templates - the list of template images and/or
image collections. This parameter is mandatory.number
parameter is higher than the number of components found).IOException - when one of the argument images doesn't exist or
cannot be read or when the underlying desktop connection throws an I/O
error.public int clickObject(int button,
int modifiers,
int count,
int number,
Point move,
Rectangle cmpArea,
String timeout,
Color color,
Integer rgbTolerance,
Dimension min,
Dimension max,
String stepName,
boolean continueScript,
String wait)
throws IOException
Look for an object/component on the screen by the specified color and click it. It provides access to functionality of the Click object scripting language command. The method combines functionality of the Waitfor match, Mouse click and Exit commands to perform the following sequence of tasks:
number parameter can be used to specify which instance
to click.number parameter the method calls the Exit
command to terminate the script.
As the method is a synthetic one it naturally supports parameters of the
two participating commands of (Waitfor match,
Mouse click) and the
object algorithm. For simplicity some of the advanced and rarely used
object parameters are omitted, such as the rotations
, bridgecolors, overlapmode,
clear and draw ones. Should you need to apply
these parameters use the Component Capture to apply a sequence of WaitFor
and Mouse commands.
button - the mouse button to click. Supported values are
MouseEvent.BUTTON1 (left button, 1), MouseEvent.BUTTON2
(middle button, 2) and MouseEvent.BUTTON3, 3 (right button). If
any other value is used the argument defaults to the left button.modifiers - modifier mask as specified in the
InputEvent. For example, to specify Ctrl+Alt use
InputEvent.CTRL_MASK | InputEvent.ALT_MASKcount - how many times to click. The default value is 1 (one click).
Delays among multiple clicks are defined by a value in the Mouse command
user preferences.number - number of the object to apply the click to in the reading
order (from the top to the bottom, from the left to the right). The
default value is 1 (click the first object). The value of 0 (zero) will
click the last object. Negative values will click objects in the reversed
order. For example, the value of -1 will click onto the second last
object, the value of -2 onto the third last one etc.cmpArea - the screen rectangle to limit the search to. To search the
whole screen set it to null.timeout - the maximum time to wait for the object to. 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 the method applies
the default Click command timeout of 30 seconds.color - the object color.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_object documentation for details.
min - the minimum object size. The dimension may contain zero or
negative width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a minimum
width of 30 pixels use new Dimension(30, -1). To set off
filtering by minimum size use null.max - the maximum object size. The dimension may contain zero or
negative width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a maximum
width of 100 pixels use new Dimension(100, -1). To set off
filtering by maximum size use null.stepName - step name (optional). When provided the method will
create a step of the specified name and add it to the report. The step
will be "pass" if the component is found and clicked successfully or
"fail" otherwise.move - relative coordinates allowing to apply the click to a
custom location (optional). Use this option to implement actions such as
"click XXX pixels to the right from the component". The coordinates are
calculated against the component center. The distance parameter overrides
the click point specified in the component image properties. To bypass
the click point and click the image center use the point of [0, 0].continueScript - the value of true will make the method
not to terminate the script when the component is not found.wait - the time to wait after the object is found and clicked. 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).number
parameter is higher than the number of objects found).IOException - when the underlying desktop connection throws an I/O
error.public int clickObject(int button,
int modifiers,
int count,
int number,
Rectangle cmpArea,
String timeout,
Color color,
Integer rgbTolerance,
Dimension min,
Dimension max,
String wait)
throws IOException
Look for an object/component on the screen by the specified color and click it. It provides access to functionality of the Click object scripting language command. The method combines functionality of the Waitfor match, Mouse click and Exit commands to perform the following sequence of tasks:
number parameter can be used to specify which instance
to click.number parameter the method calls the Exit
command to terminate the script.
As the method is a synthetic one it naturally supports parameters of the
two participating commands of (Waitfor match,
Mouse click) and the
object algorithm. For simplicity some of the advanced and rarely used
object parameters are omitted, such as the rotations
, bridgecolors, overlapmode,
clear and draw ones. Should you need to apply
these parameters use the Component Capture to apply a sequence of WaitFor
and Mouse commands.
button - the mouse button to click. Supported values are
MouseEvent.BUTTON1 (left button, 1), MouseEvent.BUTTON2
(middle button, 2) and MouseEvent.BUTTON3, 3 (right button). If
any other value is used the argument defaults to the left button.modifiers - modifier mask as specified in the
InputEvent. For example, to specify Ctrl+Alt use
InputEvent.CTRL_MASK | InputEvent.ALT_MASKcount - how many times to click. The default value is 1 (one click).
Delays among multiple clicks are defined by a value in the Mouse command
user preferences.number - number of the object to apply the click to in the reading
order (from the top to the bottom, from the left to the right). The
default value is 1 (click the first object). The value of 0 (zero) will
click the last object. Negative values will click objects in the reversed
order. For example, the value of -1 will click onto the second last
object, the value of -2 onto the third last one etc.cmpArea - the screen rectangle to limit the search to. To search the
whole screen set it to null.timeout - the maximum time to wait for the object to. 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 the method applies
the default Click command timeout of 30 seconds.color - the object color.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_object documentation for details.
min - the minimum object size. The dimension may contain zero or
negative width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a minimum
width of 30 pixels use new Dimension(30, -1). To set off
filtering by minimum size use null.max - the maximum object size. The dimension may contain zero or
negative width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a maximum
width of 100 pixels use new Dimension(100, -1). To set off
filtering by maximum size use null.wait - the time to wait after the object is found and clicked. 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).number
parameter is higher than the number of objects found).IOException - when the underlying desktop connection throws an I/O
error.public int clickObject(int number,
Color color,
Integer rgbTolerance,
Dimension min,
Dimension max,
String wait)
throws IOException
Look for an object/component on the screen by the specified color and click it. It provides access to functionality of the Click object scripting language command.
This is a convenience method which calls the clickObject(int, int, int, int, java.awt.Rectangle, java.lang.String, java.awt.Color, java.lang.Integer, java.awt.Dimension, java.awt.Dimension, java.lang.String)
one to perform a single left mouse button click onto the target
object.
number - number of the object to apply the click to in the reading
order (from the top to the bottom, from the left to the right). The
default value is 1 (click the first object). The value of 0 (zero) will
click the last object. Negative values will click objects in the reversed
order. For example, the value of -1 will click onto the second last
object, the value of -2 onto the third last one etc.color - the object color.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_object documentation for details.
min - the minimum object size. The dimension may contain zero or
negative width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a minimum
width of 30 pixels use new Dimension(30, -1). To set off
filtering by minimum size use null.max - the maximum object size. The dimension may contain zero or
negative width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a maximum
width of 100 pixels use new Dimension(100, -1). To set off
filtering by maximum size use null.wait - the time to wait after the object is found and clicked. 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).number
parameter is higher than the number of objects found).IOException - when the underlying desktop connection throws an I/O
error.public int rightClickObject(int number,
Point move,
Color color,
Integer rgbTolerance,
Dimension min,
Dimension max,
String stepName,
boolean continueScript,
String wait)
throws IOException
Look for an object/component on the screen by the specified color and right click it. It provides access to functionality of the Click object scripting language command.
This is a convenience method which calls the clickObject(int, int, int, int, java.awt.Rectangle, java.lang.String, java.awt.Color, java.lang.Integer, java.awt.Dimension, java.awt.Dimension, java.lang.String)
one to perform a single right mouse button click onto the target
object.
number - number of the object to apply the click to in the reading
order (from the top to the bottom, from the left to the right). The
default value is 1 (click the first object). The value of 0 (zero) will
click the last object. Negative values will click objects in the reversed
order. For example, the value of -1 will click onto the second last
object, the value of -2 onto the third last one etc.color - the object color.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_object documentation for details.
min - the minimum object size. The dimension may contain zero or
negative width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a minimum
width of 30 pixels use new Dimension(30, -1). To set off
filtering by minimum size use null.max - the maximum object size. The dimension may contain zero or
negative width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a maximum
width of 100 pixels use new Dimension(100, -1). To set off
filtering by maximum size use null.stepName - step name (optional). When provided the method will
create a step of the specified name and add it to the report. The step
will be "pass" if the component is found and clicked successfully or
"fail" otherwise.move - relative coordinates allowing to apply the click to a
custom location (optional). Use this option to implement actions such as
"click XXX pixels to the right from the component". The coordinates are
calculated against the component center. The distance parameter overrides
the click point specified in the component image properties. To bypass
the click point and click the image center use the point of [0, 0].continueScript - the value of true will make the method
not to terminate the script when the component is not found.wait - the time to wait after the object is found and clicked. 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).number
parameter is higher than the number of objects found).IOException - when the underlying desktop connection throws an I/O
error.public int rightClickObject(int number,
Color color,
Integer rgbTolerance,
Dimension min,
Dimension max,
String wait)
throws IOException
Look for an object/component on the screen by the specified color and right click it. It provides access to functionality of the Click object scripting language command.
This is a convenience method which calls the clickObject(int, int, int, int, java.awt.Rectangle, java.lang.String, java.awt.Color, java.lang.Integer, java.awt.Dimension, java.awt.Dimension, java.lang.String)
one to perform a single right mouse button click onto the target
object.
number - number of the object to apply the click to in the reading
order (from the top to the bottom, from the left to the right). The
default value is 1 (click the first object). The value of 0 (zero) will
click the last object. Negative values will click objects in the reversed
order. For example, the value of -1 will click onto the second last
object, the value of -2 onto the third last one etc.color - the object color.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_object documentation for details.
min - the minimum object size. The dimension may contain zero or
negative width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a minimum
width of 30 pixels use new Dimension(30, -1). To set off
filtering by minimum size use null.max - the maximum object size. The dimension may contain zero or
negative width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a maximum
width of 100 pixels use new Dimension(100, -1). To set off
filtering by maximum size use null.wait - the time to wait after the object is found and clicked. 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).number
parameter is higher than the number of objects found).IOException - when the underlying desktop connection throws an I/O
error.public int doubleClickObject(int number,
Point move,
Color color,
Integer rgbTolerance,
Dimension min,
Dimension max,
String stepName,
boolean continueScript,
String wait)
throws IOException
Look for an object/component on the screen by the specified color and double click it. It provides access to functionality of the Click object scripting language command.
This is a convenience method which calls the clickObject(int, int, int, int, java.awt.Rectangle, java.lang.String, java.awt.Color, java.lang.Integer, java.awt.Dimension, java.awt.Dimension, java.lang.String)
one to perform a double left mouse button click onto the target
object.
number - number of the object to apply the click to in the reading
order (from the top to the bottom, from the left to the right). The
default value is 1 (click the first object). The value of 0 (zero) will
click the last object. Negative values will click objects in the reversed
order. For example, the value of -1 will click onto the second last
object, the value of -2 onto the third last one etc.color - the object color.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_object documentation for details.
min - the minimum object size. The dimension may contain zero or
negative width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a minimum
width of 30 pixels use new Dimension(30, -1). To set off
filtering by minimum size use null.max - the maximum object size. The dimension may contain zero or
negative width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a maximum
width of 100 pixels use new Dimension(100, -1). To set off
filtering by maximum size use null.stepName - step name (optional). When provided the method will
create a step of the specified name and add it to the report. The step
will be "pass" if the component is found and clicked successfully or
"fail" otherwise.move - relative coordinates allowing to apply the click to a
custom location (optional). Use this option to implement actions such as
"click XXX pixels to the right from the component". The coordinates are
calculated against the component center. The distance parameter overrides
the click point specified in the component image properties. To bypass
the click point and click the image center use the point of [0, 0].continueScript - the value of true will make the method
not to terminate the script when the component is not found.wait - the time to wait after the object is found and clicked. 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).number
parameter is higher than the number of objects found).IOException - when the underlying desktop connection throws an I/O
error.public int doubleClickObject(int number,
Color color,
Integer rgbTolerance,
Dimension min,
Dimension max,
String wait)
throws IOException
Look for an object/component on the screen by the specified color and double click it. It provides access to functionality of the Click object scripting language command.
This is a convenience method which calls the clickObject(int, int, int, int, java.awt.Rectangle, java.lang.String, java.awt.Color, java.lang.Integer, java.awt.Dimension, java.awt.Dimension, java.lang.String)
one to perform a double left mouse button click onto the target
object.
number - number of the object to apply the click to in the reading
order (from the top to the bottom, from the left to the right). The
default value is 1 (click the first object). The value of 0 (zero) will
click the last object. Negative values will click objects in the reversed
order. For example, the value of -1 will click onto the second last
object, the value of -2 onto the third last one etc.color - the object color.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_object documentation for details.
min - the minimum object size. The dimension may contain zero or
negative width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a minimum
width of 30 pixels use new Dimension(30, -1). To set off
filtering by minimum size use null.max - the maximum object size. The dimension may contain zero or
negative width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a maximum
width of 100 pixels use new Dimension(100, -1). To set off
filtering by maximum size use null.wait - the time to wait after the object is found and clicked. 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).number
parameter is higher than the number of objects found).IOException - when the underlying desktop connection throws an I/O
error.public int clickObject(int number,
Color color,
Integer rgbTolerance,
String wait)
throws IOException
Look for an object/component on the screen by the specified color and click it. It provides access to functionality of the Click object scripting language command.
This is a convenience method which calls the clickObject(int, int, int, int, java.awt.Rectangle, java.lang.String, java.awt.Color, java.lang.Integer, java.awt.Dimension, java.awt.Dimension, java.lang.String)
one to perform a single left mouse button click onto the target
object.
number - number of the object to apply the click to in the reading
order (from the top to the bottom, from the left to the right). The
default value is 1 (click the first object). The value of 0 (zero) will
click the last object. Negative values will click objects in the reversed
order. For example, the value of -1 will click onto the second last
object, the value of -2 onto the third last one etc.color - the object color.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_object documentation for details.
wait - the time to wait after the object is found and clicked. 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).number
parameter is higher than the number of objects found).IOException - when the underlying desktop connection throws an I/O
error.public int rightClickObject(int number,
Color color,
Integer rgbTolerance,
String wait)
throws IOException
Look for an object/component on the screen by the specified color and right click it. It provides access to functionality of the Click object scripting language command.
This is a convenience method which calls the clickObject(int, int, int, int, java.awt.Rectangle, java.lang.String, java.awt.Color, java.lang.Integer, java.awt.Dimension, java.awt.Dimension, java.lang.String)
one to perform a single right mouse button click onto the target
object.
number - number of the object to apply the click to in the reading
order (from the top to the bottom, from the left to the right). The
default value is 1 (click the first object). The value of 0 (zero) will
click the last object. Negative values will click objects in the reversed
order. For example, the value of -1 will click onto the second last
object, the value of -2 onto the third last one etc.color - the object color.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_object documentation for details.
wait - the time to wait after the object is found and clicked. 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).number
parameter is higher than the number of objects found).IOException - when the underlying desktop connection throws an I/O
error.public int doubleClickObject(int number,
Color color,
Integer rgbTolerance,
String wait)
throws IOException
Look for an object/component on the screen by the specified color and double click it. It provides access to functionality of the Click object scripting language command.
This is a convenience method which calls the clickObject(int, int, int, int, java.awt.Rectangle, java.lang.String, java.awt.Color, java.lang.Integer, java.awt.Dimension, java.awt.Dimension, java.lang.String)
one to perform a double left mouse button click onto the target
object.
number - number of the object to apply the click to in the reading
order (from the top to the bottom, from the left to the right). The
default value is 1 (click the first object). The value of 0 (zero) will
click the last object. Negative values will click objects in the reversed
order. For example, the value of -1 will click onto the second last
object, the value of -2 onto the third last one etc.color - the object color.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_object documentation for details.
wait - the time to wait after the object is found and clicked. 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).number
parameter is higher than the number of objects found).IOException - when the underlying desktop connection throws an I/O
error.public int clickObject(int number,
Color color,
Dimension min,
Dimension max)
throws IOException
Look for an object/component on the screen by the specified color and click it. It provides access to functionality of the Click object scripting language command.
This is a convenience method which calls the clickObject(int, int, int, int, java.awt.Rectangle, java.lang.String, java.awt.Color, java.lang.Integer, java.awt.Dimension, java.awt.Dimension, java.lang.String)
one to perform a solid color (intolerant) object search followed
by a single left mouse button click to the resulting location.
number - number of the object to apply the click to in the reading
order (from the top to the bottom, from the left to the right). The
default value is 1 (click the first object). The value of 0 (zero) will
click the last object. Negative values will click objects in the reversed
order. For example, the value of -1 will click onto the second last
object, the value of -2 onto the third last one etc.color - the object color.min - the minimum object size. The dimension may contain zero or
negative width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a minimum
width of 30 pixels use new Dimension(30, -1). To set off
filtering by minimum size use null.max - the maximum object size. The dimension may contain zero or
negative width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a maximum
width of 100 pixels use new Dimension(100, -1). To set off
filtering by maximum size use null.number
parameter is higher than the number of objects found).IOException - when the underlying desktop connection throws an I/O
error.public int rightClickObject(int number,
Color color,
Dimension min,
Dimension max)
throws IOException
Look for an object/component on the screen by the specified color and right click it. It provides access to functionality of the Click object scripting language command.
This is a convenience method which calls the clickObject(int, int, int, int, java.awt.Rectangle, java.lang.String, java.awt.Color, java.lang.Integer, java.awt.Dimension, java.awt.Dimension, java.lang.String)
one to perform a solid color (intolerant) object search followed
by a single right mouse button click to the resulting location.
number - number of the object to apply the click to in the reading
order (from the top to the bottom, from the left to the right). The
default value is 1 (click the first object). The value of 0 (zero) will
click the last object. Negative values will click objects in the reversed
order. For example, the value of -1 will click onto the second last
object, the value of -2 onto the third last one etc.color - the object color.min - the minimum object size. The dimension may contain zero or
negative width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a minimum
width of 30 pixels use new Dimension(30, -1). To set off
filtering by minimum size use null.max - the maximum object size. The dimension may contain zero or
negative width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a maximum
width of 100 pixels use new Dimension(100, -1). To set off
filtering by maximum size use null.number
parameter is higher than the number of objects found).IOException - when the underlying desktop connection throws an I/O
error.public int doubleClickObject(int number,
Color color,
Dimension min,
Dimension max)
throws IOException
Look for an object/component on the screen by the specified color and double click it. It provides access to functionality of the Click object scripting language command.
This is a convenience method which calls the clickObject(int, int, int, int, java.awt.Rectangle, java.lang.String, java.awt.Color, java.lang.Integer, java.awt.Dimension, java.awt.Dimension, java.lang.String)
one to perform a solid color (intolerant) object search followed
by a double left mouse button click to the resulting location.
number - number of the object to apply the click to in the reading
order (from the top to the bottom, from the left to the right). The
default value is 1 (click the first object). The value of 0 (zero) will
click the last object. Negative values will click objects in the reversed
order. For example, the value of -1 will click onto the second last
object, the value of -2 onto the third last one etc.color - the object color.min - the minimum object size. The dimension may contain zero or
negative width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a minimum
width of 30 pixels use new Dimension(30, -1). To set off
filtering by minimum size use null.max - the maximum object size. The dimension may contain zero or
negative width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a maximum
width of 100 pixels use new Dimension(100, -1). To set off
filtering by maximum size use null.number
parameter is higher than the number of objects found).IOException - when the underlying desktop connection throws an I/O
error.public int clickObject(Color color, Integer rgbTolerance, String wait) throws IOException
Look for an object/component on the screen by the specified color and click it. It provides access to functionality of the Click object scripting language command.
This is a convenience method which calls the clickObject(int, int, int, int, java.awt.Rectangle, java.lang.String, java.awt.Color, java.lang.Integer, java.awt.Dimension, java.awt.Dimension, java.lang.String)
one to perform a single left mouse button click onto the target
object.
color - the object color.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_object documentation for details.
wait - the time to wait after the object is found and clicked. 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).number
parameter is higher than the number of objects found).IOException - when the underlying desktop connection throws an I/O
error.public int rightClickObject(Color color, Integer rgbTolerance, String wait) throws IOException
Look for an object/component on the screen by the specified color and right click it. It provides access to functionality of the Click object scripting language command.
This is a convenience method which calls the clickObject(int, int, int, int, java.awt.Rectangle, java.lang.String, java.awt.Color, java.lang.Integer, java.awt.Dimension, java.awt.Dimension, java.lang.String)
one to perform a single right mouse button click onto the target
object.
color - the object color.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_object documentation for details.
wait - the time to wait after the object is found and clicked. 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).number
parameter is higher than the number of objects found).IOException - when the underlying desktop connection throws an I/O
error.public int doubleClickObject(Color color, Integer rgbTolerance, String wait) throws IOException
Look for an object/component on the screen by the specified color and double click it. It provides access to functionality of the Click object scripting language command.
This is a convenience method which calls the clickObject(int, int, int, int, java.awt.Rectangle, java.lang.String, java.awt.Color, java.lang.Integer, java.awt.Dimension, java.awt.Dimension, java.lang.String)
one to perform a double left mouse button click onto the target
object.
color - the object color.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_object documentation for details.
wait - the time to wait after the object is found and clicked. 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).number
parameter is higher than the number of objects found).IOException - when the underlying desktop connection throws an I/O
error.public int clickObject(int number,
Color color)
throws IOException
Look for an object/component on the screen by the specified color and click it. It provides access to functionality of the Click object scripting language command.
This is a convenience method which calls the clickObject(int, int, int, int, java.awt.Rectangle, java.lang.String, java.awt.Color, java.lang.Integer, java.awt.Dimension, java.awt.Dimension, java.lang.String)
one to perform a solid color (intolerant) object search followed
by a single left mouse button click to the resulting location.
number - number of the object to apply the click to in the reading
order (from the top to the bottom, from the left to the right). The
default value is 1 (click the first object). The value of 0 (zero) will
click the last object. Negative values will click objects in the reversed
order. For example, the value of -1 will click onto the second last
object, the value of -2 onto the third last one etc.color - the object color.number
parameter is higher than the number of objects found).IOException - when the underlying desktop connection throws an I/O
error.public int rightClickObject(int number,
Color color)
throws IOException
Look for an object/component on the screen by the specified color and right click it. It provides access to functionality of the Click object scripting language command.
This is a convenience method which calls the clickObject(int, int, int, int, java.awt.Rectangle, java.lang.String, java.awt.Color, java.lang.Integer, java.awt.Dimension, java.awt.Dimension, java.lang.String)
one to perform a solid color (intolerant) object search followed
by a single right mouse button click to the resulting location.
number - number of the object to apply the click to in the reading
order (from the top to the bottom, from the left to the right). The
default value is 1 (click the first object). The value of 0 (zero) will
click the last object. Negative values will click objects in the reversed
order. For example, the value of -1 will click onto the second last
object, the value of -2 onto the third last one etc.color - the object color.number
parameter is higher than the number of objects found).IOException - when the underlying desktop connection throws an I/O
error.public int doubleClickObject(int number,
Color color)
throws IOException
Look for an object/component on the screen by the specified color and double click it. It provides access to functionality of the Click object scripting language command.
This is a convenience method which calls the clickObject(int, int, int, int, java.awt.Rectangle, java.lang.String, java.awt.Color, java.lang.Integer, java.awt.Dimension, java.awt.Dimension, java.lang.String)
one to perform a solid color (intolerant) object search followed
by a double left mouse button click to the resulting location.
number - number of the object to apply the click to in the reading
order (from the top to the bottom, from the left to the right). The
default value is 1 (click the first object). The value of 0 (zero) will
click the last object. Negative values will click objects in the reversed
order. For example, the value of -1 will click onto the second last
object, the value of -2 onto the third last one etc.color - the object color.number
parameter is higher than the number of objects found).IOException - when the underlying desktop connection throws an I/O
error.public int clickObject(Color color) throws IOException
Look for an object/component on the screen by the specified color and click it. It provides access to functionality of the Click object scripting language command.
This is a convenience method which calls the clickObject(int, int, int, int, java.awt.Rectangle, java.lang.String, java.awt.Color, java.lang.Integer, java.awt.Dimension, java.awt.Dimension, java.lang.String)
one to perform a solid color (intolerant) object search followed
by a single left mouse button click to the resulting location.
color - the object color.number
parameter is higher than the number of objects found).IOException - when the underlying desktop connection throws an I/O
error.public int rightClickObject(Color color) throws IOException
Look for an object/component on the screen by the specified color and right click it. It provides access to functionality of the Click object scripting language command.
This is a convenience method which calls the clickObject(int, int, int, int, java.awt.Rectangle, java.lang.String, java.awt.Color, java.lang.Integer, java.awt.Dimension, java.awt.Dimension, java.lang.String)
one to perform a solid color (intolerant) object search followed
by a single right mouse button click to the resulting location.
color - the object color.number
parameter is higher than the number of objects found).IOException - when the underlying desktop connection throws an I/O
error.public int doubleClickObject(Color color) throws IOException
Look for an object/component on the screen by the specified color and double click it. It provides access to functionality of the Click object scripting language command.
This is a convenience method which calls the clickObject(int, int, int, int, java.awt.Rectangle, java.lang.String, java.awt.Color, java.lang.Integer, java.awt.Dimension, java.awt.Dimension, java.lang.String)
one to perform a solid color (intolerant) object search followed
by a double left mouse button click to the resulting location.
color - the object color.number
parameter is higher than the number of objects found).IOException - when the underlying desktop connection throws an I/O
error.public int clickTextPattern(int button,
int modifiers,
int count,
int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
int mode,
String pattern,
String wait)
throws IOException
IOExceptionpublic int clickTextPattern(int button,
int modifiers,
int count,
int number,
Point move,
Rectangle cmpArea,
String timeout,
String language,
float scale,
int mode,
String pattern,
String stepName,
boolean continueScript,
String wait)
throws IOException
IOExceptionpublic int clickTextPattern(int button,
int modifiers,
int count,
int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
String pattern,
String wait)
throws IOException
IOExceptionpublic int clickText(int button,
int modifiers,
int count,
int number,
Point move,
Rectangle cmpArea,
String timeout,
String language,
float scale,
int mode,
String text,
int textDistance,
String stepName,
boolean continueScript,
String wait)
throws IOException
IOExceptionpublic int clickText(int button,
int modifiers,
int count,
int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
int mode,
String text,
int distance,
String wait)
throws IOException
IOExceptionpublic int clickText(int button,
int modifiers,
int count,
int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
String text,
int distance,
String wait)
throws IOException
IOExceptionpublic int clickTextPattern(int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
String pattern,
String wait)
throws IOException
IOExceptionpublic int rightClickTextPattern(int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
int mode,
String pattern,
String wait)
throws IOException
IOExceptionpublic int rightClickTextPattern(int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
String pattern,
String wait)
throws IOException
IOExceptionpublic int doubleClickTextPattern(int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
int mode,
String pattern,
String wait)
throws IOException
IOExceptionpublic int doubleClickTextPattern(int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
String pattern,
String wait)
throws IOException
IOExceptionpublic int clickText(int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
String text,
int distance,
String wait)
throws IOException
IOExceptionpublic int rightClickText(int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
String text,
int distance,
String wait)
throws IOException
IOExceptionpublic int doubleClickText(int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
String text,
int distance,
String wait)
throws IOException
IOExceptionpublic int clickTextPattern(int number,
String pattern,
String wait)
throws IOException
IOExceptionpublic int rightClickTextPattern(int number,
String pattern,
String wait)
throws IOException
IOExceptionpublic int doubleClickTextPattern(int number,
String pattern,
String wait)
throws IOException
IOExceptionpublic int clickText(int number,
String text,
int distance,
String wait)
throws IOException
IOExceptionpublic int rightClickText(int number,
String text,
int distance,
String wait)
throws IOException
IOExceptionpublic int doubleClickText(int number,
String text,
int distance,
String wait)
throws IOException
IOExceptionpublic int clickTextPattern(String pattern) throws IOException
IOExceptionpublic int rightClickTextPattern(String pattern) throws IOException
IOExceptionpublic int doubleClickTextPattern(String pattern) throws IOException
IOExceptionpublic int clickText(String text, int distance) throws IOException
IOExceptionpublic int rightClickText(String text, int distance) throws IOException
IOExceptionpublic int doubleClickText(String text, int distance) throws IOException
IOExceptionpublic int clickText(int number,
String text)
throws IOException
IOExceptionpublic int rightClickText(int number,
String text)
throws IOException
IOExceptionpublic int doubleClickText(int number,
String text)
throws IOException
IOExceptionpublic int clickText(String text) throws IOException
IOExceptionpublic int rightClickText(String text) throws IOException
IOExceptionpublic int doubleClickText(String text) throws IOException
IOExceptionpublic int dragImage(File[] templates, int button, int modifiers, float passRate, int number, File[] targetTemplates, int targetNumber, Rectangle cmpArea, String timeout, String sort, float[] scale, boolean continueScript, String step, String wait) throws IOException
Look for a component (a button, field, ...) on the screen by the specified image(s) and drag it. It provides access to functionality of the Drag image scripting language command. The method combines functionality of the Waitfor match, Mouse drag and Exit commands to perform the following sequence of tasks:
number parameter can be used to specify which instance to
click.number parameter the method calls the Exit
command to terminate the script.As the method is a synthetic one it naturally supports parameters of the two participating commands (Waitfor match, Mouse drag) and the search2 algorithm.
templates - the list of template images and/or
image collections. This parameter is mandatory.button - the mouse button to click. Supported values are
MouseEvent.BUTTON1 (left button, 1), MouseEvent.BUTTON2
(middle button, 2) and MouseEvent.BUTTON3, 3 (right button). If
any other value is used the argument defaults to the left button.modifiers - modifier mask as specified in the
InputEvent. For example, to specify Ctrl+Alt use
InputEvent.CTRL_MASK | InputEvent.ALT_MASKpassRate - the "search2" pass rate as a percentage between 0 and
100. The value of 100 indicates that exact match is required (100%
matching). To use the default pass rate of 50% set the parameter to a
value equal to or lower than zero.number - number of the component to apply the click to. The default
value is 1 (click the first component). The value of 0 (zero) will click
the last component. Negative values will click components in the reversed
order. For example, the value of -1 will click onto the second last
component, the value of -2 onto the third last component etc.
The order of located components is subject to the selected sort mode.
See the sort parameter for details. The default best
mode will put the best matching components to the top of the
list. If there are matches with the same match ratio they are sorted in
the reading order (from the top to the bottom, from the left to the
right). With this sort mode the number of 1 will click the
best matching location on the screen while the value of 0 will click the
worst matching one. This mechanism allows to deal with false matches
caused by the tolerant search for the pass rate lower than 100%.
targetTemplates - allows to specify the drop point by template
image(s). The method will search for them using the "search2" method
first. Another alternative is to specify the drop point through the
relativeTargetCoords parameter.targetNumber - number of the drop component to drag to. It is used
together with targetTemplates in case that there are
multiple drop components displayed on the screen and we wish to drag to
the one of particular number. See the number parameter for
info about the value range.cmpArea - the screen rectangle to limit the search to. To search the
whole screen set it to null.timeout - the maximum time to wait for the component to. 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 the method applies
the default Click command timeout of 30 seconds.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)."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:
step - optional step name. If provided the method will record a test
step to the report with the pass/fail result according to the actual
outcome.continueScript - the value of true will make the method
not to terminate the script when the component is not found.wait - the time to wait after the object is found and clicked. 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).number
parameter is higher than the number of components found).IOException - when one of the argument images doesn't exist or
cannot be read or when the underlying desktop connection throws an I/O
error.public int dragImage(File[] templates, int button, int modifiers, float passRate, int number, File[] targetTemplates, int targetNumber, Rectangle cmpArea, String timeout, String sort, float[] scale, String wait) throws IOException
IOExceptionpublic int dragImage(File[] templates, int button, int modifiers, float passRate, int number, Point relativeTargetCoords, Rectangle cmpArea, String timeout, String sort, float[] scale, boolean continueScript, String step, String wait) throws IOException
IOExceptionpublic int dragImage(File[] templates, int button, int modifiers, float passRate, int number, Point relativeTargetCoords, Rectangle cmpArea, String timeout, String sort, float[] scale, String wait) throws IOException
IOExceptionpublic int dragImage(File[] templates, int button, int modifiers, float passRate, int number, Point relativeTargetCoords) throws IOException
IOExceptionpublic int dragImage(File[] templates, int button, Point relativeTargetCoords) throws IOException
IOExceptionpublic int dragImage(File[] templates, Point relativeTargetCoords) throws IOException
IOExceptionpublic int dragObject(int button,
int modifiers,
int number,
Rectangle cmpArea,
String timeout,
Color color,
Integer rgbTolerance,
Dimension min,
Dimension max,
File[] targetTemplates,
int targetNumber,
boolean continueScript,
String step,
String wait)
throws IOException
Look for a component (a button, field, ...) on the screen by the specified color and drag it. It provides access to functionality of the Drag object scripting language command. The method combines functionality of the Waitfor match, Mouse drag and Exit commands to perform the following sequence of tasks:
number parameter can be used to specify which instance to
click.number parameter the method calls the Exit
command to terminate the script.As the method is a synthetic one it naturally supports parameters of the two participating commands (Waitfor match, Mouse drag) and the object algorithm.
button - the mouse button to click. Supported values are
MouseEvent.BUTTON1 (left button, 1), MouseEvent.BUTTON2
(middle button, 2) and MouseEvent.BUTTON3, 3 (right button). If
any other value is used the argument defaults to the left button.modifiers - modifier mask as specified in the
InputEvent. For example, to specify Ctrl+Alt use
InputEvent.CTRL_MASK | InputEvent.ALT_MASKnumber - number of the component to apply the click to. The default
value is 1 (click the first component). The value of 0 (zero) will click
the last component. Negative values will click components in the reversed
order. For example, the value of -1 will click onto the second last
component, the value of -2 onto the third last component etc.
The order of located components is subject to the selected sort mode.
See the sort parameter for details. The default best
mode will put the best matching components to the top of the
list. If there are matches with the same match ratio they are sorted in
the reading order (from the top to the bottom, from the left to the
right). With this sort mode the number of 1 will click the
best matching location on the screen while the value of 0 will click the
worst matching one. This mechanism allows to deal with false matches
caused by the tolerant search for the pass rate lower than 100%.
color - the object color.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_object documentation for details.
min - the minimum object size. The dimension may contain zero or
negative width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a minimum
width of 30 pixels use new Dimension(30, -1). To set off
filtering by minimum size use null.max - the maximum object size. The dimension may contain zero or
negative width or height to indicate that it should not be applied.
For example, to make the method search just for objects with a maximum
width of 100 pixels use new Dimension(100, -1). To set off
filtering by maximum size use null.targetTemplates - allows to specify the drop point by template
image(s). The method will search for them using the "search2" method
first. Another alternative is to specify the drop point through the
relativeTargetCoords parameter.targetNumber - number of the drop component to drag to. It is used
together with targetTemplates in case that there are
multiple drop components displayed on the screen and we wish to drag to
the one of particular number. See the number parameter for
info about the value range.cmpArea - the screen rectangle to limit the search to. To search the
whole screen set it to null.timeout - the maximum time to wait for the component to. 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 the method applies
the default Click command timeout of 30 seconds.continueScript - the value of true will make the method
not to terminate the script when the component is not found.step - optional step name. If provided the method will record a test
step to the report with the pass/fail result according to the actual
outcome.wait - the time to wait after the object is found and clicked. 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).number
parameter is higher than the number of components found).IOException - when one of the argument images doesn't exist or
cannot be read or when the underlying desktop connection throws an I/O
error.public int dragObject(int button,
int modifiers,
int number,
Rectangle cmpArea,
String timeout,
Color color,
Integer rgbTolerance,
Dimension min,
Dimension max,
File[] targetTemplates,
int targetNumber,
String wait)
throws IOException
IOExceptionpublic int dragObject(int button,
int modifiers,
Rectangle cmpArea,
String timeout,
Color color,
Integer rgbTolerance,
Dimension min,
Dimension max,
int number,
Point relativeTargetCoords,
String wait)
throws IOException
IOExceptionpublic int dragObject(int button,
int modifiers,
Rectangle cmpArea,
String timeout,
Color color,
Integer rgbTolerance,
Dimension min,
Dimension max,
int number,
Point relativeTargetCoords,
boolean continueScript,
String step,
String wait)
throws IOException
IOExceptionpublic int dragObject(int button,
Color color,
Integer rgbTolerance,
Dimension min,
Dimension max,
int number,
Point relativeTargetCoords,
String wait)
throws IOException
IOExceptionpublic int dragObject(Color color, Integer rgbTolerance, Dimension min, Dimension max, Point relativeTargetCoords) throws IOException
IOExceptionpublic int dragObject(Color color, Point relativeTargetCoords) throws IOException
IOExceptionpublic int dragTextPattern(int button,
int modifiers,
int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
int mode,
String pattern,
Point relativeTargetCoords,
String wait)
throws IOException
IOExceptionpublic int dragTextPattern(int button,
int modifiers,
int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
int mode,
String pattern,
Point relativeTargetCoords,
boolean continueScript,
String step,
String wait)
throws IOException
IOExceptionpublic int dragTextPattern(int button,
int modifiers,
int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
String pattern,
Point relativeTargetCoords,
String wait)
throws IOException
IOExceptionpublic int dragTextPattern(int button,
int number,
String language,
float scale,
String pattern,
Point relativeTargetCoords)
throws IOException
IOExceptionpublic int dragTextPattern(String pattern, Point relativeTargetCoords) throws IOException
IOExceptionpublic int dragTextPattern(int button,
int modifiers,
int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
int mode,
String pattern,
File[] targetTemplates,
int targetNumber,
boolean continueScript,
String step,
String wait)
throws IOException
IOExceptionpublic int dragTextPattern(int button,
int modifiers,
int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
int mode,
String pattern,
File[] targetTemplates,
int targetNumber,
String wait)
throws IOException
IOExceptionpublic int dragTextPattern(int button,
int modifiers,
int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
String pattern,
File[] targetTemplates,
int targetNumber,
String wait)
throws IOException
IOExceptionpublic int dragText(int button,
int modifiers,
int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
int mode,
String text,
int distance,
Point relativeTargetCoords,
boolean continueScript,
String step,
String wait)
throws IOException
IOExceptionpublic int dragText(int button,
int modifiers,
int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
int mode,
String text,
int distance,
Point relativeTargetCoords,
String wait)
throws IOException
IOExceptionpublic int dragText(int button,
int modifiers,
int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
String text,
int distance,
Point relativeTargetCoords,
String wait)
throws IOException
IOExceptionpublic int dragText(int button,
int number,
String language,
float scale,
String text,
int distance,
Point relativeTargetCoords)
throws IOException
IOExceptionpublic int dragText(String text, int distance, Point relativeTargetCoords) throws IOException
IOExceptionpublic int dragText(String text, Point relativeTargetCoords) throws IOException
IOExceptionpublic int dragText(int button,
int modifiers,
int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
int mode,
String text,
int distance,
File[] targetTemplates,
int targetNumber,
boolean continueScript,
String step,
String wait)
throws IOException
IOExceptionpublic int dragText(int button,
int modifiers,
int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
int mode,
String text,
int distance,
File[] targetTemplates,
int targetNumber,
String wait)
throws IOException
IOExceptionpublic int dragText(int button,
int modifiers,
int number,
Rectangle cmpArea,
String timeout,
String language,
float scale,
String text,
int distance,
File[] targetTemplates,
int targetNumber,
String wait)
throws IOException
IOExceptionpublic int browserOpen(String browser, String url) throws IOException
browser - the browser code such as "firefox", "ie", "edge" or
"chrome".url - the web page to load.IOException - on an I/O error.public int browserOpenRemote(String hub, String url, String... capabilities) throws IOException
hub - the hub address, for example http://myhub:4443url - the web page to load.capabilities - an even array of [capability, value] Selenium
capabilities as declared in the
CapabilityType class.IOException - on an I/O error.public int browserClose()
throws IOException
IOException - on an I/O error.public int browserFind(String timeout, String... attributes) throws IOException
timeout - the maximum time to wait for the element(s) for. If omitted
(null) the command will default to 30 seconds.attributes - the tag attributes in form of "param", "value" pairs.
For example to search for an element of the "myclass" class use the pair
of "class", "myclass".IOException - on an I/O error.public int browserFindAndClick(int elementNumber,
String timeout,
boolean continueScript,
String... attributes)
throws IOException
elementNumber - the element number to apply the action to. This
presumes that the search returns more than one element.timeout - the maximum time to wait for the element(s) for. If omitted
(null) the command will default to 30 seconds.continueScript - the value of true will make the method
not to terminate the script when the element is not found. The default
value is true (terminate script).attributes - the tag attributes in form of "param", "value" pairs.
For example to search for an element of the "myclass" class use the pair
of "class", "myclass".IOException - on an I/O error.public int browserFindAndClick(int elementNumber,
String timeout,
String... attributes)
throws IOException
elementNumber - the element number to apply the action to. This
presumes that the search returns more than one element.timeout - the maximum time to wait for the element(s) for. If omitted
(null) the command will default to 30 seconds.attributes - the tag attributes in form of "param", "value" pairs.
For example to search for an element of the "myclass" class use the pair
of "class", "myclass".IOException - on an I/O error.public int browserFindAndClick(String... attributes) throws IOException
attributes - the tag attributes in form of "param", "value" pairs.
For example to search for an element of the "myclass" class use the pair
of "class", "myclass".IOException - on an I/O error.public int browserFindAndClear(int elementNumber,
String timeout,
boolean continueScript,
String... attributes)
throws IOException
elementNumber - the element number to apply the action to. This
presumes that the search returns more than one element.timeout - the maximum time to wait for the element(s) for. If omitted
(null) the command will default to 30 seconds.continueScript - the value of true will make the method
not to terminate the script when the element is not found. The default
value is true (terminate script).attributes - the tag attributes in form of "param", "value" pairs.
For example to search for an element of the "myclass" class use the pair
of "class", "myclass".IOException - on an I/O error.public int browserFindAndClear(int elementNumber,
String timeout,
String... attributes)
throws IOException
elementNumber - the element number to apply the action to. This
presumes that the search returns more than one element.timeout - the maximum time to wait for the element(s) for. If omitted
(null) the command will default to 30 seconds.attributes - the tag attributes in form of "param", "value" pairs.
For example to search for an element of the "myclass" class use the pair
of "class", "myclass".IOException - on an I/O error.public int browserFindAndClear(String... attributes) throws IOException
attributes - the tag attributes in form of "param", "value" pairs.
For example to search for an element of the "myclass" class use the pair
of "class", "myclass".IOException - on an I/O error.public int browserFindAndSubmit(int elementNumber,
String timeout,
boolean continueScript,
String... attributes)
throws IOException
elementNumber - the element number to apply the action to. This
presumes that the search returns more than one element.timeout - the maximum time to wait for the element(s) for. If omitted
(null) the command will default to 30 seconds.continueScript - the value of true will make the method
not to terminate the script when the element is not found. The default
value is true (terminate script).attributes - the tag attributes in form of "param", "value" pairs.
For example to search for an element of the "myclass" class use the pair
of "class", "myclass".IOException - on an I/O error.public int browserFindAndSubmit(int elementNumber,
String timeout,
String... attributes)
throws IOException
elementNumber - the element number to apply the action to. This
presumes that the search returns more than one element.timeout - the maximum time to wait for the element(s) for. If omitted
(null) the command will default to 30 seconds.attributes - the tag attributes in form of "param", "value" pairs.
For example to search for an element of the "myclass" class use the pair
of "class", "myclass".IOException - on an I/O error.public int browserFindAndSubmit(String... attributes) throws IOException
attributes - the tag attributes in form of "param", "value" pairs.
For example to search for an element of the "myclass" class use the pair
of "class", "myclass".IOException - on an I/O error.public int browserFindAndType(String textToType, int elementNumber, String timeout, boolean continueScript, String... attributes) throws IOException
textToType - the text to type.elementNumber - the element number to apply the action to. This
presumes that the search returns more than one element.timeout - the maximum time to wait for the element(s) for. If omitted
(null) the command will default to 30 seconds.continueScript - the value of true will make the method
not to terminate the script when the element is not found. The default
value is true (terminate script).attributes - the tag attributes in form of "param", "value" pairs.
For example to search for an element of the "myclass" class use the pair
of "class", "myclass".IOException - on an I/O error.public int browserFindAndType(String textToType, int elementNumber, String timeout, String... attributes) throws IOException
textToType - the text to type.elementNumber - the element number to apply the action to. This
presumes that the search returns more than one element.timeout - the maximum time to wait for the element(s) for. If omitted
(null) the command will default to 30 seconds.attributes - the tag attributes in form of "param", "value" pairs.
For example to search for an element of the "myclass" class use the pair
of "class", "myclass".IOException - on an I/O error.public int browserFindAndType(String textToType, String... attributes) throws IOException
textToType - the text to type.attributes - the tag attributes in form of "param", "value" pairs.
For example to search for an element of the "myclass" class use the pair
of "class", "myclass".IOException - on an I/O error.public int browserFindAndSelectByText(String optionText, int elementNumber, String timeout, boolean continueScript, String... attributes) throws IOException
optionText - the complete drop down item text to look for.elementNumber - the element number to apply the action to. This
presumes that the search returns more than one element.timeout - the maximum time to wait for the element(s) for. If omitted
(null) the command will default to 30 seconds.continueScript - the value of true will make the method
not to terminate the script when the element is not found. The default
value is true (terminate script).attributes - the tag attributes in form of "param", "value" pairs.
For example to search for an element of the "myclass" class use the pair
of "class", "myclass".IOException - on an I/O error.public int browserFindAndSelectByText(String optionText, int elementNumber, String timeout, String... attributes) throws IOException
optionText - the complete drop down item text to look for.elementNumber - the element number to apply the action to. This
presumes that the search returns more than one element.timeout - the maximum time to wait for the element(s) for. If omitted
(null) the command will default to 30 seconds.attributes - the tag attributes in form of "param", "value" pairs.
For example to search for an element of the "myclass" class use the pair
of "class", "myclass".IOException - on an I/O error.public int browserFindAndSelectByText(String optionText, String... attributes) throws IOException
optionText - the complete drop down item text to look for.attributes - the tag attributes in form of "param", "value" pairs.
For example to search for an element of the "myclass" class use the pair
of "class", "myclass".IOException - on an I/O error.public int browserFindAndSelectByValue(String optionValue, int elementNumber, String timeout, boolean continueScript, String... attributes) throws IOException
optionValue - the drop down item value, i.e. the value specified
by the 'value' attribute of the 'option' HTML tag.elementNumber - the element number to apply the action to. This
presumes that the search returns more than one element.timeout - the maximum time to wait for the element(s) for. If omitted
(null) the command will default to 30 seconds.continueScript - the value of true will make the method
not to terminate the script when the element is not found. The default
value is true (terminate script).attributes - the tag attributes in form of "param", "value" pairs.
For example to search for an element of the "myclass" class use the pair
of "class", "myclass".IOException - on an I/O error.public int browserFindAndSelectByValue(String optionValue, int elementNumber, String timeout, String... attributes) throws IOException
optionValue - the drop down item value, i.e. the value specified
by the 'value' attribute of the 'option' HTML tag.elementNumber - the element number to apply the action to. This
presumes that the search returns more than one element.timeout - the maximum time to wait for the element(s) for. If omitted
(null) the command will default to 30 seconds.attributes - the tag attributes in form of "param", "value" pairs.
For example to search for an element of the "myclass" class use the pair
of "class", "myclass".IOException - on an I/O error.public int browserFindAndSelectByValue(String optionValue, String... attributes) throws IOException
optionValue - the drop down item value, i.e. the value specified
by the 'value' attribute of the 'option' HTML tag.attributes - the tag attributes in form of "param", "value" pairs.
For example to search for an element of the "myclass" class use the pair
of "class", "myclass".IOException - on an I/O error.public int browserFindAndSelectByIndex(int optionIndex,
int elementNumber,
String timeout,
boolean continueScript,
String... attributes)
throws IOException
optionIndex - the test to type. It applies only to text fields where
the "elementAction" parameter is set to "type".elementNumber - the element number to apply the action to. This
presumes that the search returns more than one element.timeout - the maximum time to wait for the element(s) for. If omitted
(null) the command will default to 30 seconds.continueScript - the value of true will make the method
not to terminate the script when the element is not found. The default
value is true (terminate script).attributes - the tag attributes in form of "param", "value" pairs.
For example to search for an element of the "myclass" class use the pair
of "class", "myclass".IOException - on an I/O error.public int browserFindAndSelectByIndex(int optionIndex,
int elementNumber,
String timeout,
String... attributes)
throws IOException
optionIndex - the test to type. It applies only to text fields where
the "elementAction" parameter is set to "type".elementNumber - the element number to apply the action to. This
presumes that the search returns more than one element.timeout - the maximum time to wait for the element(s) for. If omitted
(null) the command will default to 30 seconds.attributes - the tag attributes in form of "param", "value" pairs.
For example to search for an element of the "myclass" class use the pair
of "class", "myclass".IOException - on an I/O error.public int browserFindAndSelectByIndex(int optionIndex,
String... attributes)
throws IOException
optionIndex - the test to type. It applies only to text fields where
the "elementAction" parameter is set to "type".attributes - the tag attributes in form of "param", "value" pairs.
For example to search for an element of the "myclass" class use the pair
of "class", "myclass".IOException - on an I/O error.public int alert(String text, String title, String fields, String values, String buttons, String timeout, Point location, Dimension size) throws IOException
text - the alert message text (mandatory).title - the message window title (optional).fields - an optional list of semicolon separated editable field
names.values - an optional list of semicolon separated values to populate
the fields with.buttons - an optional list of semicolon separated buttons or null to
fall back to the default "OK" button.timeout - the window time out or null to make it show until the user
clicks one of its buttons.location - custom location of the top left window corner. When the
argument is null the window is displayed in the screen center.size - custom window size. When the argument is null the window
packs to the default size.IOException - on an I/O error.public int alert(String text, String title, String fields, String values, String buttons, String timeout) throws IOException
text - the alert message text (mandatory).title - the message window title (optional).fields - an optional list of semicolon separated editable field
names.values - an optional list of semicolon separated values to populate
the fields with.buttons - an optional list of semicolon separated buttons or null to
fall back to the default "OK" button.timeout - the window time out or null to make it show until the user
clicks one of its buttons.IOException - on an I/O error.public int alert(String text, String title, String buttons, String timeout) throws IOException
text - the alert message text (mandatory).title - the message window title (optional).buttons - an optional list of semicolon separated buttons or null to
fall back to the default "OK" button.timeout - the window time out or null to make it show until the user
clicks one of its buttons.IOException - on an I/O error.public int date(String date, String inFormat, String add, String outFormat, String var) throws IOException
date - a date to be parsed and processed. If the argument is null
the current date will be used.inFormat - the input date format. It makes sense only if the
date parameter is specified. The format must follow the
java.text.SimpleDateFormat specification. If the argument is null the
_DATE variable format is used. It defaults to "yyyyMMdd" and
it may be customized in the Language screen of the user
preferences.add - optional time interval to be added or subtracted from the
input date. It must be in the
TPR Time Values format. For example, the value of "-30d" will
subtract 30 days from the date.outFormat - the output date format to be used to store the formatted
date to the _DATE variable or one specified by the
var argument. The format must follow the
java.text.SimpleDateFormat specification. If the argument is null the
_DATE variable format is used. It defaults to "yyyyMMdd" and
it may be customized in the Language screen of the user
preferences.var - name of the variable to store the date to. It defaults to
_DATE.IOException - on an I/O error.public int date(String date, String inFormat, String outFormat) throws IOException
_DATE variable.
The method provides access to the Date functionality.date - a date to be parsed and processed. If the argument is null
the current date will be used.inFormat - the input date format. It makes sense only if the
date parameter is specified. The format must follow the
java.text.SimpleDateFormat specification. If the argument is null the
_DATE variable format is used. It defaults to "yyyyMMdd" and
it may be customized in the Language screen of the user
preferences.outFormat - the output date format to be used to store the formatted
date to the _DATE variable or one specified by the
var argument. The format must follow the
java.text.SimpleDateFormat specification. If the argument is null the
_DATE variable format is used. It defaults to "yyyyMMdd" and
it may be customized in the Language screen of the user
preferences.IOException - on an I/O error.public int date(String outFormat) throws IOException
_DATE
variable. The method provides access to the Date
functionality.outFormat - the output date format to be used to store the formatted
date to the _DATE variable or one specified by the
var argument. The format must follow the
java.text.SimpleDateFormat specification. If the argument is null the
_DATE variable format is used. It defaults to "yyyyMMdd" and
it may be customized in the Language screen of the user
preferences.IOException - on an I/O error.public int mailGet(String protocol, String server, String user, String password, String folder, String uid, int max, String from, String subject, String body, String attachment, Boolean read) throws IOException
protocol - the mail protocol, one of "POP3", "POP3S" (SSL secured
POP3), "IMAP" or "IMAPS" (SSL secured IMAP). When null the protocol
defaults to IMAPS.server - the server address (name or IP) and port, for example
"my.mail.com" or "my.mail.com:993".user - the user name.password - the password.folder - the folder name. Leave the value on null to use the default
"Inbox" folder. This parameter is ignored for POP3 which supports a
single folder only.uid - the message UID (Unique Identifier). It allows to get a
single message. The UID is available through
getVariable("_EMAIL_UID_[n]"
after a call of
mailGet(java.lang.String, int, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.Boolean).max - maximum number of most recent messages to be retrieved. The
default value is 100.from - filter the messages by a string contained in the "to"
address.subject - filter the messages by a string contained in the message
subject.body - filter the messages by a string contained in the message
body.attachment - filter the messages by a string contained in an email
attachment. For example, to retrieve only messages containing a MS Excel
file in the attachment use ".xls".read - retrieve only read (true) or unread (false) messages. To get
all messages use null.IOException - in case of an I/O error.public int mailGet(String protocol, String security, String server, String user, String password, String folder, String uid, int max, String from, String subject, String body, String attachment, Boolean read) throws IOException
protocol - the mail protocol, one of "POP3", "POP3S" (SSL secured
POP3), "IMAP" or "IMAPS" (SSL secured IMAP). When null the protocol
defaults to IMAPS.security - the security type. Use null or
EmailConstants.SECURITY_PASSWORD for plain password authentication
or one of EmailConstants.SECURITY_GOOGLE or
EmailConstants.SECURITY_MICROSOFT for OAuth2 authentication to GMail
or Outlook mail.server - the server address (name or IP) and port, for example
"my.mail.com" or "my.mail.com:993".user - the user name.password - the password if the security is null or
EmailConstants.SECURITY_PASSWORD. Other security types rely on
stored OAuth2 tokens and the password argument is ignored.folder - the folder name. Leave the value on null to use the default
"Inbox" folder. This parameter is ignored for POP3 which supports a
single folder only.uid - the message UID (Unique Identifier). It allows to get a single
message. The UID is available through
getVariable("_EMAIL_UID_[n]"
after a call of
mailGet(java.lang.String, int, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.Boolean).max - maximum number of most recent messages to be retrieved. The
default value is 100.from - filter the messages by a string contained in the "to"
address.subject - filter the messages by a string contained in the message
subject.body - filter the messages by a string contained in the message
body.attachment - filter the messages by a string contained in an email
attachment. For example, to retrieve only messages containing a MS Excel
file in the attachment use ".xls".read - retrieve only read (true) or unread (false) messages. To get
all messages use null.IOException - in case of an I/O error.public int mailGet(String folder, int max, String from, String subject, String body, String attachment, Boolean read) throws IOException
Get mail from a POP3 or IMAP server and filter it by the specified parameters. The method provides access to the Mail functionality.
This method omits the connection parameters such as the protocol,
server, user name and password. It presumes that they have been
previously used by another "Mail get" command or they were specified
through the variables of "_EMAIL_SERVER", "_EMAIL_PROTOCOL",
"_EMAIL_USER", "_EMAIL_PASSWORD" and "_EMAIL_SECURITY. To set the
variables use the AbstractJavaTestScript.setVariable(java.lang.String, java.lang.Object)
method.
folder - the folder name. Leave the value on null to use the default
"Inbox" folder. This parameter is ignored for POP3 which supports a
single folder only.max - maximum number of most recent messages to be retrieved. The
default value is 100.from - filter the messages by a string contained in the "to"
address.subject - filter the messages by a string contained in the message
subject.body - filter the messages by a string contained in the message
body.attachment - filter the messages by a string contained in an email
attachment. For example, to retrieve only messages containing a MS Excel
file in the attachment use ".xls".read - retrieve only read (true) or unread (false) messages. To get
all messages use null.IOException - in case of an I/O error.public int mailGet(String uid) throws IOException
Get a single mail specified by the UID from a POP3 or IMAP server. The method provides access to the Mail functionality.
This method omits the connection parameters such as the protocol,
server, user name and password. It presumes that they have been
previously used by another "Mail get" command or they were specified
through the variables of "_EMAIL_SERVER", "_EMAIL_PROTOCOL",
"_EMAIL_USER" and "_EMAIL_PASSWORD". To set the variables use the
AbstractJavaTestScript.setVariable(java.lang.String, java.lang.Object) method.
uid - the message UID (Unique Identifier). The UID is available
through
getVariable("_EMAIL_UID_[n]"
after a successful call of any mailGet() method.IOException - in case of an I/O error.public int mailSet(String protocol, String security, String server, String user, String password, String uid, Boolean read) throws IOException
protocol - the mail protocol, one of "POP3", "POP3S" (SSL secured
POP3), "IMAP" or "IMAPS" (SSL secured IMAP). When null the protocol
defaults to IMAPS.security - the security type. Use null or
EmailConstants.SECURITY_PASSWORD for plain password authentication
or one of EmailConstants.SECURITY_GOOGLE or
EmailConstants.SECURITY_MICROSOFT for OAuth2 authentication to GMail
or Outlook mail.server - the server address (name or IP) and port, for example
"my.mail.com" or "my.mail.com:993".user - the user name.password - the password if the security is null or
EmailConstants.SECURITY_PASSWORD. Other security types rely on
stored OAuth2 tokens and the password argument is ignored.uid - the message UID (Unique Identifier). It allows to get a
single message. The UID is available through
getVariable("_EMAIL_UID_[n]"
after a call of
mailGet(java.lang.String, int, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.Boolean).
If the argument is null it will default to all messages retrieved
previously by any mailGet() method call.read - set the SEEN flag of the message(s) to read (true) or unread
(false). The default value is true (read).IOException - in case of an I/O error.public int mailSet(String protocol, String server, String user, String password, String uid, Boolean read) throws IOException
protocol - the mail protocol, one of "POP3", "POP3S" (SSL secured
POP3), "IMAP" or "IMAPS" (SSL secured IMAP). When null the protocol
defaults to IMAPS.server - the server address (name or IP) and port, for example
"my.mail.com" or "my.mail.com:993".user - the user name.password - the password.uid - the message UID (Unique Identifier). It allows to get a
single message. The UID is available through
getVariable("_EMAIL_UID_[n]"
after a call of
mailGet(java.lang.String, int, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.Boolean).
If the argument is null it will default to all messages retrieved
previously by any mailGet() method call.read - set the SEEN flag of the message(s) to read (true) or unread
(false). The default value is true (read).IOException - in case of an I/O error.public int mailSet(String uid, Boolean read) throws IOException
Set the "Seen" ("Read") flag of one or more emails. The method provides access to the Mail functionality.
This method omits the connection parameters such as the protocol,
server, user name and password. It presumes that they have been
previously used by another "Mail get" command or they were specified
through the variables of "_EMAIL_SERVER", "_EMAIL_PROTOCOL",
"_EMAIL_USER", "_EMAIL_PASSWORD" and "_EMAIL_SECURITY". To set the
variables use the AbstractJavaTestScript.setVariable(java.lang.String, java.lang.Object)
method.
uid - the message UID (Unique Identifier). It allows to process a
single message. The UID is available through
getVariable("_EMAIL_UID_[n]"
after a call of
mailGet(java.lang.String, int, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.Boolean).
If the argument is null it will default to all messages retrieved
previously by any mailGet() method call.read - set the SEEN flag of the message(s) to read (true) or unread
(false). The default value is true (read).IOException - in case of an I/O error.public int mailSet(Boolean read) throws IOException
Set the "Seen" ("Read") flag of all messages retrieved through the previous call of any of the mailGet() method. The method provides access to the Mail functionality.
This method omits the connection parameters such as the protocol,
server, user name and password. It presumes that they have been
previously used by another "Mail get" command or they were specified
through the variables of "_EMAIL_SERVER", "_EMAIL_PROTOCOL",
"_EMAIL_USER", "_EMAIL_PASSWORD" and "_EMAIL_SECURITY". To set the
variables use the AbstractJavaTestScript.setVariable(java.lang.String, java.lang.Object)
method.
read - set the SEEN flag of the message(s) to read (true) or unread
(false). The default value is true (read).IOException - in case of an I/O error.public int mailDelete(String protocol, String security, String server, String user, String password, String uid) throws IOException
protocol - the mail protocol, one of "POP3", "POP3S" (SSL secured
POP3), "IMAP" or "IMAPS" (SSL secured IMAP). When null the protocol
defaults to IMAPS.server - the server address (name or IP) and port, for example
"my.mail.com" or "my.mail.com:993".security - the security type. Use null or
EmailConstants.SECURITY_PASSWORD for plain password authentication
or one of EmailConstants.SECURITY_GOOGLE or
EmailConstants.SECURITY_MICROSOFT for OAuth2 authentication to GMail
or Outlook mail.user - the user name.password - the password if the security is null or
EmailConstants.SECURITY_PASSWORD. Other security types rely on
stored OAuth2 tokens and the password argument is ignored.uid - the message UID (Unique Identifier). It allows to delete a
single message. The UID is available through
getVariable("_EMAIL_UID_[n]"
after a call of
mailGet(java.lang.String, int, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.Boolean).
If the argument is null it will default to all messages retrieved
previously by any mailGet() method call.IOException - in case of an I/O error.public int mailDelete(String protocol, String server, String user, String password, String uid) throws IOException
protocol - the mail protocol, one of "POP3", "POP3S" (SSL secured
POP3), "IMAP" or "IMAPS" (SSL secured IMAP). When null the protocol
defaults to IMAPS.server - the server address (name or IP) and port, for example
"my.mail.com" or "my.mail.com:993".user - the user name.password - the password if the security is null or
EmailConstants.SECURITY_PASSWORD. Other security types rely on
stored OAuth2 tokens and the password argument is ignored.uid - the message UID (Unique Identifier). It allows to delete a
single message. The UID is available through
getVariable("_EMAIL_UID_[n]"
after a call of
mailGet(java.lang.String, int, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.Boolean).
If the argument is null it will default to all messages retrieved
previously by any mailGet() method call.IOException - in case of an I/O error.public int mailDelete(String uid) throws IOException
Delete one or more emails. The method provides access to the Mail functionality.
This method omits the connection parameters such as the protocol,
server, user name and password. It presumes that they have been
previously used by another "Mail get" command or they were specified
through the variables of "_EMAIL_SERVER", "_EMAIL_PROTOCOL",
"_EMAIL_USER", "_EMAIL_PASSWORD" and "_EMAIL_SECURITY". To set the
variables use the AbstractJavaTestScript.setVariable(java.lang.String, java.lang.Object)
method.
uid - the message UID (Unique Identifier). It allows to delete a
single message. The UID is available through
getVariable("_EMAIL_UID_[n]"
after a call of
mailGet(java.lang.String, int, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.Boolean).
If the argument is null it will default to all messages retrieved
previously by any mailGet() method call.IOException - in case of an I/O error.public int mailDelete()
throws IOException
Delete all messages retrieved through the previous call of any of the mailGet() methods. The method provides access to the Mail functionality.
This method omits the connection parameters such as the protocol,
server, user name and password. It presumes that they have been
previously used by another "Mail get" command or they were specified
through the variables of "_EMAIL_SERVER", "_EMAIL_PROTOCOL",
"_EMAIL_USER", "_EMAIL_PASSWORD" and "_EMAIL_SECURITY". To set the
variables use the AbstractJavaTestScript.setVariable(java.lang.String, java.lang.Object)
method.
IOException - in case of an I/O error.public int gesturePress(int finger,
Point to)
throws IOException
finger - the finger ID. It is a number starting from zero. The
maximum number of fingers is subject to the device and connection but
it's seldom less than 5.to - the press location.IOException - on an I/O error.public int gestureMove(int finger,
Point to)
throws IOException
finger - the finger ID. It is a number starting from zero. The
maximum number of fingers is subject to the device and connection but
it's seldom less than 5.to - the location to move the finger to.IOException - on an I/O error.public int gestureRelease(int finger)
throws IOException
finger - the finger ID. It is a number starting from zero. The
maximum number of fingers is subject to the device and connection but
it's seldom less than 5.IOException - on an I/O error.public int gestureSave(String name, Boolean clear) throws IOException
name - the gesture name. Names are case sensitive. If you use an
already existing name it will overwrite the previous gesture.clear - true to clear the gesture buffer and make it ready for
design of a new gesture. This operation does not affect saved gestures.
The default value is true (clear the buffer).IOException - on an I/O error.public int gestureExecute(String name, Point start, String duration, Boolean clear, int count, String wait) throws IOException
name - name of the previously saved gesture. If the name
is omitted the method will execute whatever has been recorded to the
gesture buffer.start - the point to move the gesture to (optional). Each gesture
has a start point which is the press location of the finger with the
lowest ID (typically finger #0). This parameter allows to start the
gesture from a new location. If the gesture fails to fit the screen the
method will trim it by the screen bounds which may lead to unexpected
results.duration - the gesture duration. 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). The default
value is 500 milliseconds.clear - true to clear the gesture buffer after execution. This
operation does not affect saved gestures. The default value is
true (clear the buffer).count - how many times to perform the gesture. The default value is
1 (execute once).wait - the time to wait after the gesture gets performed. 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).IOException - on an I/O error.public int gestureExecute(String name, Point start, String duration) throws IOException
name - name of the previously saved gesture. If the name
is omitted the method will execute whatever has been recorded to the
gesture buffer.start - the point to move the gesture to (optional). Each gesture
has a start point which is the press location of the finger with the
lowest ID (typically finger #0). This parameter allows to start the
gesture from a new location. If the gesture fails to fit the screen the
method will trim it by the screen bounds which may lead to unexpected
results.duration - the gesture duration. 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). The default
value is 500 milliseconds.IOException - on an I/O error.public int gestureExecute(String name) throws IOException
name - name of the previously saved gesture. If the name
is omitted the method will execute whatever has been recorded to the
gesture buffer.IOException - on an I/O error.public int gestureExecute(Point start, String duration) throws IOException
start - the point to move the gesture to (optional). Each gesture
has a start point which is the press location of the finger with the
lowest ID (typically finger #0). This parameter allows to start the
gesture from a new location. If the gesture fails to fit the screen the
method will trim it by the screen bounds which may lead to unexpected
results.duration - the gesture duration. 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). The default
value is 500 milliseconds.IOException - on an I/O error.public int gestureExecute()
throws IOException
IOException - on an I/O error.public int gestureClear()
throws IOException
IOException - on an I/O error.public int vargSet(String name, String value, String scope) throws IOException
name - variable name.value - variable value.scope - variable scope, one of "local", "script" or "session".IOException - on an I/O error.public int vargDelete(String name, String scope) throws IOException
name - variable name.scope - variable scope, one of "local", "script" or "session".IOException - on an I/O error.public int vargDelete(String name) throws IOException
name - variable name.IOException - on an I/O error.public boolean isPass()
IllegalStateException.public int getExitCode()
getContext().getExitCode());.
If there's no context (for example when the script was instantiated but not executed yet)
the method throws an IllegalStateException.public UserConfiguration getUserConfiguration()
Convenience method for quick access to the user configuration. The
method delivers the shared user configuration instance returned by
UserConfiguration.getInstance(). As it is a shared singleton, any
parameter change affects all scripts and objects in the whole JVM. The
method must be called after the ApplicationSupport class is
instantiated because it is initialized in there.
User configuration is a map of [parameter,value] pairs of configurable
parameters. The loading mechanism has several layers. In the first
step the class loads default values from the DefaultConfiguration.properties
and EntConfiguration.properties files bundled inside the application
JAR file robot.jar. If the external user configuration file
[user_home]/tplanrobot.cfg exists, it is loaded in the next step and
it overwrites the default values. The third layer is represented by so called
override table (UserConfiguration.setOverrideTable(java.util.Map) which
has the highest priority and allows temporary non-destructive override of
any configuration value. This table is primarily populated from the -o/--option
CLI switches but it can be used programmatically as well.
Changes to the user configuration are not saved to file by default.
If the script runs in the CLI mode, the changes are never saved unless it
calls the UserConfiguration.saveConfiguration() method. When the
script runs in the GUI mode, the main window will save the configuration
when it exits normally (except when it crashes or gets killed through the OS means).
If you want to apply just temporary changes and avoid saving them permanently,
use the override table instead.
Test scripts and third party Java programs are free to change the configuration to change behavior of Robot's functionality dynamically. Parameter names and expected values can be either retrieved in a very raw form from the abovementioned property files or in a more comfortable way through the "Show preference details tool tip" feature of the Robot's Preferences window. Favorite tasks include for example setting of the start and finish time outs to zero:
getConfiguration().setInteger("scripting.delayBeforeAutomaticExecutionSeconds", 0);
getConfiguration().setInteger("scripting.delayAfterAutomaticExecutionSeconds", 0);
The same example taking advantage of the override table:
Map table = getConfiguration().getOverrideTable();
if (table == null) {
table = new Hashtable();
getConfiguration().setOverrideTable(table);
}
table.put("scripting.delayBeforeAutomaticExecutionSeconds", "0");
table.put("scripting.delayAfterAutomaticExecutionSeconds", "0");
public void setTemplateDir(String dir)
ScriptingContext.setTemplateDir(java.io.File)
method of the associated script context.setTemplateDir in class AbstractJavaTestScriptdir - a directory.public void setOutputDir(String dir)
ScriptingContext.setOutputDir(java.io.File)
method of the associated script context.setOutputDir in class AbstractJavaTestScriptdir - a directory.