Services Builder for Screens

com.attachmate.sc.ssa
Interface IQAScreen

All Superinterfaces:
IQAScreenConstants

public interface IQAScreen
extends IQAScreenConstants

IQAScreen describes the Attachmate Quick Application for Java interface. It uses the same method names as QACOM but in a Java friendly form. Rather than returning status codes, the methods will throw NavExceptions. Output parameters have been replaced with returning objects.

Since the navigation maps do not support indexed screens, you may only use the screen name to access a recorded screen.

See Also:
IField, IScreenDataConstants

Field Summary
 
Fields inherited from interface com.attachmate.sc.ssa.IQAScreenConstants
ATTR_BLINK, ATTR_CHAR_SET_APL, ATTR_COLUMN_SEPARATOR, ATTR_DEFAULT, ATTR_HIGH_INTENSITY, ATTR_LEFT_LINE, ATTR_OVERLINE, ATTR_REVERSE, ATTR_RIGHT_LINE, ATTR_STRIKETHROUGH, ATTR_UNDERLINE, ATTR_VISIBLE, COLOR_BG_BLACK, COLOR_BG_BLUE, COLOR_BG_DEFAULT, COLOR_BG_DK_BLUE, COLOR_BG_DK_GREEN, COLOR_BG_DK_MAGENTA, COLOR_BG_DK_RED, COLOR_BG_DK_TURQUOISE, COLOR_BG_DK_YELLOW, COLOR_BG_GRAY, COLOR_BG_GREEN, COLOR_BG_LT_GRAY, COLOR_BG_MAGENTA, COLOR_BG_MASK, COLOR_BG_RED, COLOR_BG_TURQUOISE, COLOR_BG_WHITE, COLOR_BG_YELLOW, COLOR_FG_BLACK, COLOR_FG_BLUE, COLOR_FG_DEFAULT, COLOR_FG_DK_BLUE, COLOR_FG_DK_GREEN, COLOR_FG_DK_MAGENTA, COLOR_FG_DK_RED, COLOR_FG_DK_TURQUOISE, COLOR_FG_DK_YELLOW, COLOR_FG_GRAY, COLOR_FG_GREEN, COLOR_FG_LT_GRAY, COLOR_FG_MAGENTA, COLOR_FG_MASK, COLOR_FG_RED, COLOR_FG_TURQUOISE, COLOR_FG_WHITE, COLOR_FG_YELLOW, FIELD_ALPHA_ONLY, FIELD_ALPHA_SHIFT, FIELD_ATTRIB_SPACE, FIELD_ATTRIBUTE, FIELD_AUTO_ENTER, FIELD_CHECK_MOD_10, FIELD_CHECK_MOD_11, FIELD_DIGITS, FIELD_EXIT_REQ, FIELD_LIGHT_PEN, FIELD_MAGNETIC_STRIP, FIELD_MANDATORY_ENTRY, FIELD_MANDATORY_FILL, FIELD_MARK_DUP, FIELD_MODE_BLOCK, FIELD_MODE_PROTECTED, FIELD_MODIFIED, FIELD_NUMERIC_ONLY, FIELD_NUMERIC_SHIFT, FIELD_RA_BLANKFILL, FIELD_RA_ZEROFILL, FIELD_RIGHT_JUSTIFIED, FIELD_SIGNED_NUMERIC, FIELD_TRIGGER, FIELD_TYPE_MESSAGE, FIELD_TYPE_TABLE, FIELD_TYPE_USER, FIELD_UPPERCASE, TS_BACKWARDS, TS_FIELD_ONLY, TS_IGNORE_CASE, TS_NORMAL, TS_WRAP
 
Method Summary
 Point findString(java.lang.String string, int startRow, int startCol, int flag)
          Returns the location of the given text on the current screen.
 IFieldData[] getAllFieldInformation()
          Gets an array of field data for all the fields on the current screen.
 long[] getAttributes(int row, int col, int length)
          Gets the attributes at the specified row, column and length.
 IController getController()
          Gets the current IController that SendKeys is using.
 java.lang.String getCurrentScreenName()
          Gets the name of the current host screen from the pre-recorded navigation map.
 Point getCursorPosition()
          Gets the cursor position on the current host screen.
 IFieldData getField(int fieldIndex)
          Gets the field data for the specified field.
 IFieldData getField(java.lang.String fieldName)
          Gets the field data for the specified field.
 int getFieldCount()
          Gets the number of fields for the current host screen.
 int getFieldIndexFromName(java.lang.String screenName, java.lang.String fieldName)
          Gets the field index based on its name on the given screen.
 java.lang.String getFieldNameFromIndex(java.lang.String screenName, int fieldIndex)
          Gets the field name based on its index on the given screen.
 Dimension getScreenSize()
          Gets the size of the screen.
 long getSettleTime()
          Gets the time to wait for the screen to settle.
 java.lang.String getString(int row, int col, int length)
          Gets any text at the specified row, column and length.
 long getTimeOut()
          Gets the time that the host waits from an action used in SendKeys.
 Point getWaitForCursor()
          Gets a Point that contains the location of the cursor trigger.
 int putString(java.lang.String text, int row, int col)
          Writes the text to the current host screen at the specified row and column.
 void sendKeys(java.lang.String keys)
          Sends keystrokes to the host at the current cursor position.
 void setController(IController controller)
          Sets the IController object used in SendKeys.
 void setCursorPosition(int row, int col)
          Sets the cursor position on the current host screen
 void setFieldValue(int fieldIndex, java.lang.String value)
          Sets the value of a specified unprotected field.
 void setFieldValue(java.lang.String fieldName, java.lang.String value)
          Sets the value of a specified unprotected field.
 void setSettleTime(long milliseconds)
          Sets the time to wait for the screen to settle.
 void setTimeOut(long milliseconds)
          Sets the time that the host waits from a action used to SendKeys.
 void setWaitForCursor(int row, int column)
          Sets a cursor trigger for ending a read.
 

Method Detail

findString

public Point findString(java.lang.String string,
                        int startRow,
                        int startCol,
                        int flag)
Returns the location of the given text on the current screen. This method attempts to locate a given string on the host screen, beginning at a specified now and column position. If the text is not found, the coordinates return will be (0,0).

Parameters:
string - the string to search for on the given screen.
startRow - the row position at which to start the search. This value must be greater than zero.
startCol - the column position at which to start the search. This value must be greater than zero.
flag - set with flags TS_WRAP, TS_BACKWARDS, TS_FIELD_ONLY and TS_IGNORE_CASE set.
Returns:
a Point containing the row and column position of where the the string was found. If the string was not found, they are set to zero.

getAllFieldInformation

public IFieldData[] getAllFieldInformation()
Gets an array of field data for all the fields on the current screen. This method will return an array of IField objects that hold everything from the field coordinates, field attributes and text. Use the built-in array method length to get the field count.

Returns:
An array of IField objects.
See Also:
IField

getCursorPosition

public Point getCursorPosition()
Gets the cursor position on the current host screen.

Returns:
a Point containing the current row and column of the cursor.

getFieldCount

public int getFieldCount()
Gets the number of fields for the current host screen.

Returns:
the number of fields.

getField

public IFieldData getField(int fieldIndex)
Gets the field data for the specified field.

Parameters:
fieldIndex - the field for which to get the data. The index is zero based.
Returns:
an IField object containing all the data for the specified field or null if no such field exists.
See Also:
IField

getField

public IFieldData getField(java.lang.String fieldName)
Gets the field data for the specified field.

Parameters:
fieldName - the name of the field for which to get the data.
Returns:
an IField object containing all the data for the specified field or null if no such field exists.
See Also:
IField

getCurrentScreenName

public java.lang.String getCurrentScreenName()
Gets the name of the current host screen from the pre-recorded navigation map. The current screen definition is compared against screen in the map. This will return the name of the first matched screen.

Returns:
the name of the screen. null if the a match could not be found.

getFieldNameFromIndex

public java.lang.String getFieldNameFromIndex(java.lang.String screenName,
                                              int fieldIndex)
Gets the field name based on its index on the given screen. The current host screen needs to have been recorded to have this method succeed. The index numbers start at zero and end one less than the field count. The index may change if another recording file is set.

Parameters:
screenName - the name of the screen that contains the requested field. Use null to search the current screen.
fieldIndex -
Returns:
the name of the field

getFieldIndexFromName

public int getFieldIndexFromName(java.lang.String screenName,
                                 java.lang.String fieldName)
Gets the field index based on its name on the given screen. The current host screen needs to have been recorded to have this method succeed. The name needs to be non-null. If the name cannot be found on the specified map, -1 will be returned.

Parameters:
screenName - the name of the screen that contains the requested field. Use null to search the current screen.
fieldName - a string containing the field identifier convert.
Returns:
the index of the field that matches the name, else -1.

getScreenSize

public Dimension getScreenSize()
Gets the size of the screen. Tbe height of the returned Dimension object is the number of rows, the width the number of columns.

Returns:
a Dimension object containing the maximum number of rows and columns for the current screen.

getAttributes

public long[] getAttributes(int row,
                            int col,
                            int length)
Gets the attributes at the specified row, column and length. If the length parameter is zero, the text from the specified row and column to the end of the screen is returned. The row and column parameters must always be greater than zero.

Parameters:
row - the row position on the host screen at which to begin retrieving attributes.
col - the column position on the host screen at which to begin retrieving attributes.
length - the number of attributes to retrieve. If this value is zero, the attributes are retrieved up to the end of the screen.
Returns:
the attributes that have been retrieved.

getString

public java.lang.String getString(int row,
                                  int col,
                                  int length)
Gets any text at the specified row, column and length. If the length parameter is zero, the text from the specified row and column to the end of the screen is returned. The row and column parameters must always be greater than zero.

This method returns the correct value that is contained in non-display fields. Be sure to check the field attribute prior to displaying text retrieved with this method.

Parameters:
row - the row position on the host screen at which to begin retrieving text.
col - the column position on the host screen at which to begin retrieving text.
length - the length of the text string to retrieve. If this value is zero, the text is retrieved up to the end of the screen.
Returns:
the text that has been retrieved.

putString

public int putString(java.lang.String text,
                     int row,
                     int col)
              throws com.attachmate.nav.engine.NavException
Writes the text to the current host screen at the specified row and column.

NOTE: If this method is called to put text on an unformatted screen then you must follow this call by a call to the setCursorPosition method in order to place the cursor at the end of the text just written. This is necessary for the text to be correctly sent to the host on an unformatted screen.

Parameters:
text - the text to write to the screen
row - the row position on the screen at which to begin writting the text string.
col - the column position on the screen at which to begin writting the text string.
Returns:
the number of characters actually written to the screen.
Throws:
com.attachmate.nav.engine.NavException
ProtectedFieldException

sendKeys

public void sendKeys(java.lang.String keys)
              throws com.attachmate.nav.engine.NavException,
                     java.io.IOException
Sends keystrokes to the host at the current cursor position. You can send terminal-specific keys using HLLAPI mnemonics. Uses the default settle time on the execution of commands to the host.

Parameters:
keys - text and HLLAPI mnemonics to send to the screen
Throws:
com.attachmate.nav.engine.NavException
java.io.IOException

setCursorPosition

public void setCursorPosition(int row,
                              int col)
Sets the cursor position on the current host screen

Parameters:
row - the cursor row position. The row is 1 based.
col - the cursor column position. The column is 1 based.

setFieldValue

public void setFieldValue(int fieldIndex,
                          java.lang.String value)
                   throws com.attachmate.nav.engine.NavException
Sets the value of a specified unprotected field.

Parameters:
fieldIndex - the field for which a value is to be set. The index is zero based.
value - the value to set for the specified field.
Throws:
com.attachmate.nav.engine.NavException

setFieldValue

public void setFieldValue(java.lang.String fieldName,
                          java.lang.String value)
                   throws com.attachmate.nav.engine.NavException
Sets the value of a specified unprotected field. The current host screen needs to have been recorded to have this method succeed. The field name is matched up to the recorded screen to find the field index.

Parameters:
fieldName - the name of the field to set.
value - the value for the specified field.
Throws:
com.attachmate.nav.engine.NavException

setTimeOut

public void setTimeOut(long milliseconds)
Sets the time that the host waits from a action used to SendKeys. The default is 20,000 milliseconds.

Parameters:
milliseconds - the number of milliseconds to wait before timing out. A value of zero indicates no (infinite) timeout.

getTimeOut

public long getTimeOut()
Gets the time that the host waits from an action used in SendKeys.

This is an extension to the QACOM

Returns:
the number of milliseconds to wait before timing out. Use a value of zero for no (infinite) timeout.

setSettleTime

public void setSettleTime(long milliseconds)
Sets the time to wait for the screen to settle. If the host read returns with data before the settle time, another read is performed. This will continue until the read times out by the time specified. The default timeout is 1500 milliseconds.

Parameters:
milliseconds - the number of milliseconds to use for the settle time.

getSettleTime

public long getSettleTime()
Gets the time to wait for the screen to settle. If the host read returns with data before the settle time, another read is performed. This will continue until the read times out by the time specified. The default timeout is 1500 milliseconds.

This is an extension to the QACOM

Returns:
the number of milliseconds to use for the settle time.

setWaitForCursor

public void setWaitForCursor(int row,
                             int column)
Sets a cursor trigger for ending a read. When a read is returned, the cursor will be examined and if it is at the supplied coordinates, the settled read will exit. If the row or column is set to zero, then the trigger isn't used. Timeout and settle time are still used to terminate the settled read.

This is an extension to the QACOM

Parameters:
row - the row to use for the cursor trigger
column - the column to use for the cursor trigger

getWaitForCursor

public Point getWaitForCursor()
Gets a Point that contains the location of the cursor trigger. When a read returns, the cursor is examined and if it matches the supplied coordinates, the settled read will exit. If the row or column is set to zero, then the trigger isn't used. Timeout and settle time are still used to terminate the settled read.

This is an extension to the QACOM

Returns:
a Point containing the trigger coordinates

getController

public IController getController()
Gets the current IController that SendKeys is using.

This is an extension to the QACOM.

Returns:
returns the current controller object

setController

public void setController(IController controller)
Sets the IController object used in SendKeys.

This is an extension to the QACOM

Parameters:
controller - an IController based object

Services Builder for Screens