com.tplan.robot.scripting.commands

Interface EditorFriendlyCommandHandler

All Known Implementing Classes:

AbstractCombinedCommand

public interface EditorFriendlyCommandHandler

Interface for a command handler (or a Java test script method call) able to cooperate with the script editor and/or to edit its parameters through a GUI editor.

The methods defined in this interface allow the implementing command to create a command editor through one of the three hierarchical mechanisms:

• Commands using a custom dialog may declare this capability through the hasCustomPropertyDialog(java.util.LinkedHashMap, com.tplan.robot.scripting.interpret.TestScriptInterpret, int, javax.swing.Action[]) method. Examples of such commands are CompareTo, Waitfor and Screenshot.
• Commands which wish to rely on the Preferences framework but need to tweak it with custom behavior may build their custom preference panel (see PreferencePanel) and declare it through the hasCustomParameterComponent(java.util.LinkedHashMap, com.tplan.robot.scripting.interpret.TestScriptInterpret, com.tplan.robot.gui.preferences.PreferencePanel[]) method.
• The simplest way of building of a command editor is to declare the command parameters through the getVisualParameters(java.util.LinkedHashMap, com.tplan.robot.scripting.interpret.TestScriptInterpret) method and let the Preferences framework manage the GUI.

Any command implementing this interface:

• It will appear in the Command Wizard which gets activated through Ctrl+Enter in the script editor. This allows to create new commands and Java method calls.
• When Ctrl+Enter is pressed while the caret is on an existing command or a Java method call, the command editor gets displayed for that element.
• Right click onto an existing command or Java method call displays the context menu where the topmost menu item opens the command editor.

Since:

3.0

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

Field Summary

Fields

Modifier and Type	Field and Description
static int	CATEGORY_ADMIN Command category - administrative and execution control commands.
static int	CATEGORY_DESKTOP Command category - desktop commands (mouse and keyboard).
static int	CATEGORY_IMAGE_OPS Command category - image operations (component search, image analysis, OCR, ...).
static int	CATEGORY_IO Command category - data input/output.
static int	CATEGORY_REPORTING Command category - reporting commands.
static int	CATEGORY_UNKNOWN Command category - unknown/unsorted.

Method Summary

Modifier and Type	Method and Description
void	checkVisualParameters(Map<String,CharSequence> parameters, TestScriptInterpret interpret) Check (compile) the map of parameters retrieved through the command editor window before they are used to build and/or update the command or Java method call.
int	getCategory(StringBuilder customCategoryDescription) Get the category the command falls to.
String	getShortDescription(Map<String,String> parameters, TestScriptInterpret interpret) Get short description (up to 50 chars) of what the command does.
List<Preference>	getVisualParameters(LinkedHashMap<String,Object> parameters, TestScriptInterpret interpret) Get the list of visual parameters for construction of a dynamic command editor window.
boolean	hasCustomParameterComponent(LinkedHashMap<String,Object> parameters, TestScriptInterpret interpret, com.tplan.robot.gui.preferences.PreferencePanel[] panel) Specify whether the command provides a custom preference panel.
boolean	hasCustomPropertyDialog(LinkedHashMap<String,Object> parameters, TestScriptInterpret interpret, int offset, Action[] action) Specify whether the command provides a custom editor.
boolean	hasFixedArgument(List<String> arguments) Defines whether the command uses a fixed argument (one-of-a-list).

Field Detail

CATEGORY_UNKNOWN

static final int CATEGORY_UNKNOWN

Command category - unknown/unsorted.

See Also:

Constant Field Values

CATEGORY_DESKTOP

static final int CATEGORY_DESKTOP

Command category - desktop commands (mouse and keyboard).

See Also:

Constant Field Values

CATEGORY_ADMIN

static final int CATEGORY_ADMIN

Command category - administrative and execution control commands.

See Also:

Constant Field Values

CATEGORY_REPORTING

static final int CATEGORY_REPORTING

Command category - reporting commands.

See Also:

Constant Field Values

CATEGORY_IMAGE_OPS

static final int CATEGORY_IMAGE_OPS

Command category - image operations (component search, image analysis, OCR, ...).

See Also:

Constant Field Values

CATEGORY_IO

static final int CATEGORY_IO

Command category - data input/output.

See Also:

Constant Field Values

Method Detail

getVisualParameters

List<Preference> getVisualParameters(LinkedHashMap<String,Object> parameters,
                                     TestScriptInterpret interpret)

Get the list of visual parameters for construction of a dynamic command editor window.

This method will be called only after the hasCustomPropertyDialog(java.util.LinkedHashMap, com.tplan.robot.scripting.interpret.TestScriptInterpret, int, javax.swing.Action[]) and hasCustomParameterComponent(java.util.LinkedHashMap, com.tplan.robot.scripting.interpret.TestScriptInterpret, com.tplan.robot.gui.preferences.PreferencePanel[]) methods return false.

Parameters:

parameters - input parameters parsed from the already existing command or preselected through the Command Wizard menu.

interpret - test script interpret owning the edited script.

Returns:

list of visual parameters. If the list is null and the command does not provide a custom component through the hasCustomPropertyDialog(java.util.LinkedHashMap, com.tplan.robot.scripting.interpret.TestScriptInterpret, int, javax.swing.Action[]) and hasCustomParameterComponent(java.util.LinkedHashMap, com.tplan.robot.scripting.interpret.TestScriptInterpret, com.tplan.robot.gui.preferences.PreferencePanel[]) methods, it will be considered as not editable through the GUI.

checkVisualParameters

void checkVisualParameters(Map<String,CharSequence> parameters,
                           TestScriptInterpret interpret)
                    throws IllegalArgumentException

Check (compile) the map of parameters retrieved through the command editor window before they are used to build and/or update the command or Java method call. This method may be also used to remove or filter the parameters. This is especially useful if the command editor uses auxiliary settings which are not recognized by the command or method at runtime.

If the command handler extends the AbstractCommandHandler class, it may take advantage of the AbstractCommandHandler.compileParameters(java.util.Map, com.tplan.robot.scripting.interpret.TestScriptInterpret) method which converts a copy of the input map to the legacy parameter format and passes it to the CommandHandler.validate(java.util.List, java.util.Map, java.util.Map, com.tplan.robot.scripting.ScriptingContext) method to verify whether the parameters are recognized and their values are acceptable. This allows to avoid duplication of parameter parsing and compilation code.

Parameters:

parameters - map of parameters and their values. All values are in the format recognized by token parser (TokenParserImpl.getParser()) which may be used to convert them to native Java objects such as Number, Point, Rectangle etc.

interpret - test script interpret owning the edited script.

Throws:

IllegalArgumentException - when one or more parameters is not recognized or its value is invalid. The exception should contain a descriptive message because it will be displayed by the GUI.

hasFixedArgument

boolean hasFixedArgument(List<String> arguments)

Defines whether the command uses a fixed argument (one-of-a-list). Examples of such commands are Mouse with the arguments of "click", "press" etc. or WaitFor ("match", "mismatch",...). If the command does use a fixed argument it is supposed to return true and populate the argument list with the argument values (if the list is not null).

Parameters:

arguments - optional output list for the argument values.

Returns:

true if the command uses fixed argument values, false if not.

hasCustomParameterComponent

boolean hasCustomParameterComponent(LinkedHashMap<String,Object> parameters,
                                    TestScriptInterpret interpret,
                                    com.tplan.robot.gui.preferences.PreferencePanel[] panel)

Specify whether the command provides a custom preference panel. If it does it is expected to return true and populate the first field of the panel array with an instance of the panel.

Parameters:

parameters - map of parameters and their values. All values are in the format recognized by token parser (TokenParserImpl.getParser()) which may be used to convert them to native Java objects such as Number, Point, Rectangle etc.

interpret - test script interpret owning the edited script.

panel - output array of length=1 which should be populated inside the method with the custom panel instance if the method returns true.

Returns:

true if the command creates its own custom preference panel or false otherwise.

hasCustomPropertyDialog

boolean hasCustomPropertyDialog(LinkedHashMap<String,Object> parameters,
                                TestScriptInterpret interpret,
                                int offset,
                                Action[] action)

Specify whether the command provides a custom editor. If it does it is expected to return true and populate the first field of the action array with an instance of an Action which opens up the dialog.

Even though the method is implemented to return false, it may be also used to preprocess parameters parsed from an existing command call before they reach the command editor window. The method may for example change the parameters or their values in the input map. As the argument map the real one rather than a copy, any data change will hold in there and it will be reflected in the GUI.

Parameters:

parameters - map of parameters and their values. All values are in the format recognized by token parser (TokenParserImpl.getParser()) which may be used to convert them to native Java objects such as Number, Point, Rectangle etc.

interpret - test script interpret owning the edited script.

offset - position in the edited script.

action - output array of length=1 which should be populated inside the method with an Action instance if the method returns true.

Returns:

true if the command creates its own dialog or false otherwise.

getCategory

int getCategory(StringBuilder customCategoryDescription)

Get the category the command falls to. The method may return one of the predefined CATEGORY_XXX constants defined by this class. Commands which do not fall into any specified category may return CATEGORY_UNKNOWN or a code outside of the recognized constants and pass the desired category name through the argument string builder instance.

Parameters:

customCategoryDescription - string buffer for category name. It is only used if the returned value is other than the standard ones.

Returns:

category code.

getShortDescription

String getShortDescription(Map<String,String> parameters,
                           TestScriptInterpret interpret)

Get short description (up to 50 chars) of what the command does. This will be used for the list (menu) of available actions in the GUI.

Parameters:

parameters - map of parameters and their values. All values are in the format recognized by token parser (TokenParserImpl.getParser()) which may be used to convert them to native Java objects such as Number, Point, Rectangle etc.

interpret - test script interpret owning the edited script.

Returns:

short command description.