com.mercury.ftjadin.custom
Class MicAPI

java.lang.Object
  extended bycom.mercury.ftjadin.custom.MicAPI

public class MicAPI
extends java.lang.Object

The MicAPI class provides an API that makes it possible to record and execute functions in your application that are not related to the user interface.


Field Summary
static int BAD_STRING
          The string cannot be interpreted as integer.
static int DIEZ_NUM
          The string is in the format #n, for example: "#2".
static int DIGIT_NUM
          The string is in the format n, for example: "2".
 
Constructor Summary
MicAPI()
           
 
Method Summary
static voidactivateWindow(int hwnd)
          Invokes a native method to activate the window.
static java.lang.StringadjustString(java.lang.String str)
          Modifies the string value so that it can be used as a string constant in double quotes in a UFT GUI test.
static voiddispatchEvent(java.awt.AWTEvent evt)
          Deprecated. Relevant for AWT-only. Included in the API for backward compatibility.
static voiddispatchEvent(java.lang.Object comp, java.lang.Object evt)
          Dispatches the specified event.
static voidenableRecord(java.lang.Object obj)
          Enables recording on the specified object.
static java.lang.ObjectfindTarget(java.lang.Object container, int x, int y)
          Finds the component inside a container that covers the point specified by the x and y arguments.
static java.lang.ObjectgetParentWindow(java.lang.Object widget)
          Finds the topmost window that contains the specified control.
static voidinvokeAndWaitInEDT(java.lang.Object comp, java.lang.Runnable run, long timeout)
          Invokes the runnable code in the main GUI thread -- the event dispatching thread (EDT).
static voidinvokeLaterInEDT(java.lang.Object comp, java.lang.Runnable run)
          Invokes the runnable code in the main GUI thread -- the event dispatching thread (EDT).
static booleanisDebug(java.lang.String section)
          Checks whether the specified section is in configured for debug mode.
static voidlogLine(java.lang.String line)
          Writes the text to the log as a separate line.
static voidlogLine(java.lang.String section, java.lang.String line)
          Writes the text to the log as a separate line only if the section is configured to debug.
static voidlogStackTrace(java.lang.String section, java.lang.Throwable throwable)
          Prints a Throwable exception's stack trace to the log only if the section is configured to debug.
static voidlogStackTrace(java.lang.Throwable throwable)
          Prints a Throwable exception's stack trace to the log.
static voidmouseClick(java.lang.Object comp, int x, int y)
          Performs a single left-button mouse click.
static voidmouseClick(java.lang.Object comp, int x, int y, int mdf)
          Performs a single mouse click using the specified button.
static voidmouseClick(java.lang.Object comp, int x, int y, int button, int mdf, int clicks)
          Performs the specified number of mouse clicks using the specified button.
static voidmouseDrag(java.lang.Object comp, int from_x, int from_y, int to_x, int to_y, int mdf)
          Performs a mouse drag between two points on the object using the specified button.
static voidpostEvent(java.awt.AWTEvent evt)
          Deprecated. Relevant for AWT-only. Included in the API for backward compatibility.
static voidpostEvent(java.lang.Object comp, java.lang.Object evt)
          Posts the specified event into the EventQueue.
static voidrecord(java.lang.Object obj, java.lang.String str)
          Records a user operation on the specified object.
static voidrecord(java.lang.Object obj, java.lang.String str, int time)
          Records a user operation on the specified object after the specified delay.
static voidrecord(java.lang.Object obj, java.lang.String str, java.lang.String[] params)
          Records a user operation with parameters on the specified object.
static voidrecord(java.lang.Object obj, java.lang.String str, java.lang.String[] params, int time)
          Records a user operation with parameters on the specified object after the specified delay.
static voidregisterWrapperInspector(java.lang.Class objClz, WrapperInspector inspector)
          Registers a new WrapperInspector object for objects of the specified Class.
static intstring2int(java.lang.String str)
          Converts a string to an integer.
static intstring2int(java.lang.String str, int mode)
          Converts a string of a specified format to an integer.
static voidtypeText(java.awt.Component comp, java.lang.String text)
          Enters text into a component, generating the events mode configured by the variable of the tested application.
static voidtypeText(java.awt.Component comp, java.lang.String text, java.lang.String event_mode)
          Enters text into a component.
static voidtypeText(java.lang.Object comp, java.lang.String text)
          Enters text into a component, generating the events mode configured by the variable of the tested application.
static voidtypeText(java.lang.Object comp, java.lang.String text, java.lang.String event_mode)
          Enters text into a component.
static booleanwaitForSynchronization(java.lang.Object comp, long timeout)
          Waits for object event handling to finish.
 

 

Field Detail

DIGIT_NUM

public static final int DIGIT_NUM
The string is in the format n, for example: "2".

See Also:
Constant Field Values

DIEZ_NUM

public static final int DIEZ_NUM
The string is in the format #n, for example: "#2".

See Also:
Constant Field Values

BAD_STRING

public static final int BAD_STRING
The string cannot be interpreted as integer.

See Also:
Constant Field Values
Constructor Detail

MicAPI

public MicAPI()
Method Detail

adjustString

public static java.lang.String adjustString(java.lang.String str)
Modifies the string value so that it can be used as a string constant in double quotes in a UFT GUI test. For example, it escapes special characters, replacing '\' with '\\', '"' with '\"', and so on. It is recommended to run this method on any string sent to UFT unless the string is definitely known to be valid. Example: MicAPI.record(list, "list_select_item(\"%m\", \"" + MicAPI.adjustString(item) + "\")";

Parameters:
str - The input string.
Returns:
The valid constant string.

postEvent

public static void postEvent(java.awt.AWTEvent evt)
Deprecated. Relevant for AWT-only. Included in the API for backward compatibility.

Posts the specified event into the EventQueue.

Parameters:
evt - The event to post.

postEvent

public static void postEvent(java.lang.Object comp,
 java.lang.Object evt)
Posts the specified event into the EventQueue.

Parameters:
evt - The event to post.

dispatchEvent

public static void dispatchEvent(java.awt.AWTEvent evt)
Deprecated. Relevant for AWT-only. Included in the API for backward compatibility.

Dispatches the specified event. The function returns after the event has been processed by the application.

Parameters:
evt - The event to dispatch.

dispatchEvent

public static void dispatchEvent(java.lang.Object comp,
 java.lang.Object evt)
Dispatches the specified event. The function returns after the event has been processed by the application.

Parameters:
comp - The component whose event handler code will be evoked.
evt - The event to dispatch.

invokeLaterInEDT

public static void invokeLaterInEDT(java.lang.Object comp,
 java.lang.Runnable run)
Invokes the runnable code in the main GUI thread -- the event dispatching thread (EDT).

Parameters:
comp - The component whose event handler code will be evoked.
run - The code to execute.

invokeAndWaitInEDT

public static void invokeAndWaitInEDT(java.lang.Object comp,
 java.lang.Runnable run,
 long timeout)
Invokes the runnable code in the main GUI thread -- the event dispatching thread (EDT). Returns after the code finishes.

Parameters:
comp - The component whose event handler code will be evoked.
run - The code to execute.
timeout - The maximum time to wait for completion. Set to -1 to use the default - 20 seconds.

waitForSynchronization

public static boolean waitForSynchronization(java.lang.Object comp,
 long timeout)
Waits for object event handling to finish. For example: checks if the event handler finished processing previous events, checks if event queue is empty, waits for modal dialog to finish, and so forth.

Parameters:
comp - The component whose event handler code will be evoked.
timeout - The maximum time to wait for object synchronization. Set to -1 to use default.
Returns:
True if synchronization completed within timeout. False if event timed out.

typeText

public static void typeText(java.lang.Object comp,
 java.lang.String text,
 java.lang.String event_mode)
Enters text into a component. typeText generates key events depending on the event mode and inserts them into the event queue.

Parameters:
comp - The component into which to enter text.
text - The text to be typed.
event_mode - A string with one or more of the characters "P", "T", "R". "P" indicates to generate KeyPressed events. "T" indicates KeyTyped events. "R" indicates KeyReleased events.

typeText

public static void typeText(java.awt.Component comp,
 java.lang.String text,
 java.lang.String event_mode)
Enters text into a component. typeText generates key events depending on the event mode and inserts them into the event queue.

Parameters:
comp - The component into which to enter text.
text - The text to be typed.
event_mode - A string with one or more of the characters "P", "T", "R". "P" indicates to generate KeyPressed events. "T" indicates KeyTyped events. "R" indicates KeyReleased events.

typeText

public static void typeText(java.awt.Component comp,
 java.lang.String text)
Enters text into a component, generating the events mode configured by the variable of the tested application. By default, it is "PTR". This is the combination required for AWT key typing.

Parameters:
comp - The component into which to enter text.
text - The text to be typed.

typeText

public static void typeText(java.lang.Object comp,
 java.lang.String text)
Enters text into a component, generating the events mode configured by the variable of the tested application. By default, it is "PTR". This is the combination required for AWT key typing.

Parameters:
comp - The component into which to enter text.
text - The text to be typed.

mouseClick

public static void mouseClick(java.lang.Object comp,
 int x,
 int y)
Performs a single left-button mouse click. mouseClick puts the appropriate mouse events into the event queue, but does not dispatch the events.
The coordinates are relative to the component object.

Parameters:
comp - The component to click on.
x - The x-coordinate of the click.
y - The y-coordinate of the click.

mouseClick

public static void mouseClick(java.lang.Object comp,
 int x,
 int y,
 int mdf)
Performs a single mouse click using the specified button. mouseClick puts the appropriate mouse events into the event queue, but does not dispatch the events.
The coordinates are relative to the component object.

Parameters:
comp - The component to click on.
x - The x-coordinate of the click.
y - The y-coordinate of the click.
mdf - The mouse button to click: ObjectCS.LEFT, ObjectCS.RIGHT, or ObjectCS.MIDDLE.

mouseClick

public static void mouseClick(java.lang.Object comp,
 int x,
 int y,
 int button,
 int mdf,
 int clicks)
Performs the specified number of mouse clicks using the specified button. mouseClick puts the appropriate mouse events into the event queue, but does not dispatch the events.
The coordinates are relative to the component object.

Parameters:
comp - The component to click on.
x - The x-coordinate of the click.
y - The y-coordinate of the click.
mdf - Keys pressed while clicking. The options can be ORed to indicate multiple keys.
The options are: ObjectCS.SHIFT, ObjectCS.CONTROL, ObjectCS.CONTROL_SHIFT, and ObjectCS.ALT.
clicks - The number of clicks.

mouseDrag

public static void mouseDrag(java.lang.Object comp,
 int from_x,
 int from_y,
 int to_x,
 int to_y,
 int mdf)
Performs a mouse drag between two points on the object using the specified button. mouseDrag dispatches all generated events except for the last MouseReleased event, which is inserted into the event queue.
The coordinates are relative to the component object.

Parameters:
comp - The component on which to drag the mouse.
from_x - The start x-coordinate.
from_y - The start y-coordinate.
to_x - The end x-coordinate.
to_x - The end y-coordinate.
mdf - The mouse button to click: ObjectCS.LEFT, ObjectCS.RIGHT, or ObjectCS.MIDDLE.

getParentWindow

public static java.lang.Object getParentWindow(java.lang.Object widget)
Finds the topmost window that contains the specified control.

Parameters:
widget - The control for which to find the containing window.
Returns:
A toolkit-specific window object containing the specified control.

findTarget

public static java.lang.Object findTarget(java.lang.Object container,
 int x,
 int y)
Finds the component inside a container that covers the point specified by the x and y arguments. That is, the point is inside the component.

Parameters:
container - The object in which to perform the search.
x - The x-coordinate relative to container.
y - The y-coordinate relative to container.

activateWindow

public static void activateWindow(int hwnd)
Invokes a native method to activate the window. hwnd must represent a top-level window object.

Parameters:
hwnd - The handle of the window to activate.

enableRecord

public static void enableRecord(java.lang.Object obj)
Enables recording on the specified object. The recording engine filters out unwanted recording, generally of activity initiated by callbacks triggered by the application itself, rather than by the user. To filter this activity, the engine stores an object "touched" by the user (either by mouse or by keyboard) and allows recording only for this object. Use enableRecord to force recording on an "untouched" object. Example: MicAPI.enableRecord(target); MicAPI.record(target, record_string);

Parameters:
obj - The object on which to enable recording.

registerWrapperInspector

public static void registerWrapperInspector(java.lang.Class objClz,
                                            WrapperInspector inspector)
Registers a new WrapperInspector object for objects of the specified Class.
This method should be called from the registerWrapperInspetor() method of the support class for a compound object, which, in turn, is called by the constructor of CustomClassSupport.

Parameters:
objClz - The name of a class whose objects are capable of being wrapped by a WrapperInspector.
inspector - The WrapperInspector to register.

record

public static void record(java.lang.Object obj,
 java.lang.String str,
 int time)
Records a user operation on the specified object after the specified delay. The operation will be recorded after the time specified has elapsed. If during this time, there is an additional call to a record method, this delayed recording is silently ignored.
For example, use this method to delay recording a click event to ensure that the click was not actually the first click of a double-click. If there is no call to a record method during the delay period, the click is recorded. Otherwise, the click is ignored and the subsequent call - the double-click - is recorded instead. When record is called, a step is added to the UFT GUI test.

Parameters:
obj - The object on which the operation was performed.
str - The name of the test object method. For example, Click or Select.
time - The time in milliseconds to wait before recording.

record

public static void record(java.lang.Object obj,
 java.lang.String str)
Records a user operation on the specified object. The operation should contain a single "%m" tag to be substituted by a test object name or a "%w" tag for a window.

Parameters:
obj - The object on which the operation was performed.
str - The name of the test object method. For example, Click or Select.

record

public static void record(java.lang.Object obj,
 java.lang.String str,
 java.lang.String[] params)
Records a user operation with parameters on the specified object.

Parameters:
obj - The object on which the operation was performed.
str - The name of the test object method. For example, Click or Select.
params - The parameters for the test object method. For example, x and y for Click.

record

public static void record(java.lang.Object obj,
 java.lang.String str,
 java.lang.String[] params,
 int time)
Records a user operation with parameters on the specified object after the specified delay. The operation will be recorded after the time specified has elapsed. If during this time, there is an additional call to a record method, this delayed recording is silently ignored.
For example, use this method to delay recording a click event to ensure that the click was not actually the first click of a double-click. If there is no call to a record method during the delay period, the click is recorded. Otherwise, the click is ignored and the subsequent call - the double-click - is recorded instead. When record is called, a step is added to the UFT GUI test.

Parameters:
obj - The object on which the operation was performed.
str - The name of the test object method. For example, Click or Select.
params - The parameters for the test object method.
time - The time in milliseconds to wait before recording.

logLine

public static void logLine(java.lang.String line)
Writes the text to the log as a separate line. A newline character is added automatically to the line.

Parameters:
line - The text to write to the log.

logLine

public static void logLine(java.lang.String section,
 java.lang.String line)
Writes the text to the log as a separate line only if the section is configured to debug. A newline character is added automatically to the line.

Parameters:
section - The debug section to which this log belongs.
line - The text to write to the log.
See Also:
isDebug(String)

logStackTrace

public static void logStackTrace(java.lang.Throwable throwable)
Prints a Throwable exception's stack trace to the log. Use for debugging.

Parameters:
throwable - The exception to throw.

logStackTrace

public static void logStackTrace(java.lang.String section,
 java.lang.Throwable throwable)
Prints a Throwable exception's stack trace to the log only if the section is configured to debug.

Parameters:
section - The debug section in which this exception is thrown.
throwable - The exception to throw.
See Also:
isDebug(String)

string2int

public static int string2int(java.lang.String str)
Converts a string to an integer. The string can be simple, like "2", or preceded by a # sign, like "#2".

Parameters:
str - A string that can be interpreted as an integer.
Returns:
The integer representing the string's value.

string2int

public static int string2int(java.lang.String str,
 int mode)
Converts a string of a specified format to an integer. For simple strings, like "2", specify the format by passing mode DIGIT_NUM. For strings of format "#2", specify the format with mode DIEZ_NUM. If either is possible, OR the modes together.

Parameters:
str - A string that can be interpreted as an integer.
mode - Either DIGIT_NUM, DIEZ_NUM or (DIEZ_NUM | DIGIT_NUM).
Returns:
An integer.

isDebug

public static boolean isDebug(java.lang.String section)
Checks whether the specified section is in configured for debug mode.

Parameters:
section - The section label, such as Record, Replay, and so on.