---

com.mercury.ftjadin.custom
Class MicAPI

java.lang.Object
  com.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 void	activateWindow(int hwnd)           Invokes a native method to activate the window.
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.
static void	dispatchEvent(java.awt.AWTEvent evt)           Deprecated. Relevant for AWT-only. Included in the API for backward compatibility.
static void	dispatchEvent(java.lang.Object comp, java.lang.Object evt)           Dispatches the specified event.
static void	enableRecord(java.lang.Object obj)           Enables recording on the specified object.
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.
static java.lang.Object	getParentWindow(java.lang.Object widget)           Finds the topmost window that contains the specified control.
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).
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).
static boolean	isDebug(java.lang.String section)           Checks whether the specified section is in configured for debug mode.
static void	logLine(java.lang.String line)           Writes the text to the log as a separate line.
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.
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.
static void	logStackTrace(java.lang.Throwable throwable)           Prints a Throwable exception's stack trace to the log.
static void	mouseClick(java.lang.Object comp, int x, int y)           Performs a single left-button mouse click.
static void	mouseClick(java.lang.Object comp, int x, int y, int mdf)           Performs a single mouse click using the specified button.
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.
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.
static void	postEvent(java.awt.AWTEvent evt)           Deprecated. Relevant for AWT-only. Included in the API for backward compatibility.
static void	postEvent(java.lang.Object comp, java.lang.Object evt)           Posts the specified event into the EventQueue.
static void	record(java.lang.Object obj, java.lang.String str)           Records a user operation on the specified object.
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.
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.
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.
static void	registerWrapperInspector(java.lang.Class objClz, WrapperInspector inspector)           Registers a new WrapperInspector object for objects of the specified Class.
static int	string2int(java.lang.String str)           Converts a string to an integer.
static int	string2int(java.lang.String str, int mode)           Converts a string of a specified format to an integer.
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.
static void	typeText(java.awt.Component comp, java.lang.String text, java.lang.String event_mode)           Enters text into a component.
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.
static void	typeText(java.lang.Object comp, java.lang.String text, java.lang.String event_mode)           Enters text into a component.
static boolean	waitForSynchronization(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 '\\' or '"' with '\"'. 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 to evoke.

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 to evoke.

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 to evoke.

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, or waits for modal dialog to finish.

Parameters:

comp - The component whose event handler code to evoke.

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 is 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 is 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 or Replay.

---