com.microfocus.zfe.haapi.ps

Interface PresentationSpace

public interface PresentationSpace

Contains information about a host screen and methods to interact with a host screen. A host screen is represented as a collection of DataCell instances, one for each location on the host screen. 3270 and 5250 host types are also represented as a collection of Field instances. The first position in a presentation space is represented by row1 and column 1.

See Also:

DataCell, Field

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	PresentationSpace.SearchDirection Used for search related methods.

Method Summary

Modifier and Type	Method and Description
void	addPresentationSpaceListener(PresentationSpaceListener listener, PresentationSpaceEvent.Origin... origin) Registers a listener to receive presentation space events from this PresentationSpace instance.
Position	getCursorPosition() Returns a Position instance representing the current cursor position.
List<DataCell>	getDataCells() Returns a list of DataCell instances representing each position of the presentation space with the first member of the list being the first position on the host screen and the last member being the last position.
List<DataCell>	getDataCells(Position start, int length) Returns a list of DataCell instances where the first member of the list will be for the position specified by the start parameter.
FieldList	getFields() Returns a list of the fields in the presentation space.
Dimension	getSize() Returns the size of the screen as a Dimension object.
String	getText(Position start, int length) Returns a string representing a linear area of the presentation space.
boolean	isCursorVisible() Tests if the cursor is currently visible in the presentation space.
boolean	removePresentationSpaceListener(PresentationSpaceListener listener) Unregisters a listener that no longer wishes to receive presentation space events from this PresentationSpace instance.
void	sendKeys(String s) Transmits a string and/or terminal keys to the host at the current cursor position in the presentation space.
void	setCursorPosition(Position location) Moves the host cursor to the specified row and column position.

Method Detail

addPresentationSpaceListener

void addPresentationSpaceListener(PresentationSpaceListener listener,
                                  PresentationSpaceEvent.Origin... origin)

Registers a listener to receive presentation space events from this PresentationSpace instance. If the listener was previously registered for a different event origin and the new registration differs, the registration origin is changed; the new registration does not add to the existing registration. Note: In VT, HP, and T27 emulations, all presentation space updates occur as the result of text echoing from the host, and one cannot distinguish between host events and user events. For these emulations, registration is made for PresentationSpaceListener.Origin.ALL, regardless of the origin you specify. In addition, PresentationSpace events sent to registered listeners in VT, HP, and T27 emulations will always be PresentationSpaceEvent.Origin.HOST and PresentationSpaceEvent.Origin.USER regardless of what is specified for the event origin.

Parameters:

listener - the object that wishes to receive events.

origin - optional filter for events the listener wishes to receive. Defaults to PresentationSpaceEvent.Origin.HOST and PresentationSpaceEvent.Origin.USER if no origin is specified.

See Also:

PresentationSpaceEvent.Origin

removePresentationSpaceListener

boolean removePresentationSpaceListener(PresentationSpaceListener listener)

Unregisters a listener that no longer wishes to receive presentation space events from this PresentationSpace instance.

Parameters:

listener - the PresentationSpaceListener instance to be removed

Returns:

true if the listener instance was found to be removed, false otherwise

getFields

FieldList getFields()

Returns a list of the fields in the presentation space. This doesn't return any fields from the back buffer. If the host type does not support fields or the current screen is unformatted then the return will always be an empty list.

Returns:

a list of host defined fields in the presentation space.

See Also:

FieldList

getDataCells

List<DataCell> getDataCells()
                     throws PresentationSpaceException

Returns a list of DataCell instances representing each position of the presentation space with the first member of the list being the first position on the host screen and the last member being the last position.

Returns:

a list of DataCell instances which may be empty if the session is not connected

Throws:

PresentationSpaceException - if an error occurs

getDataCells

List<DataCell> getDataCells(Position start,
                            int length)
                     throws PresentationSpaceException

Returns a list of DataCell instances where the first member of the list will be for the position specified by the start parameter. The maximum number of DataCell instances in the list is specified by the length parameter. If the length argument results in going beyond the last position of the presentation space then the returned list will only contain DataCell instances up to the last position on the presentation space.

Parameters:

start - the first position on the host screen in which to retrieve DataCell instances for

length - the maximum number of DataCell instances to be retrieved

Returns:

a list of DataCell instances which may be empty if the session is not connected

Throws:

InvalidPositionException - if the start parameter in not part of the presentation space

PresentationSpaceException - if an error occurs

getText

String getText(Position start,
               int length)
        throws PresentationSpaceException

Returns a string representing a linear area of the presentation space. No new line characters will be inserted if row boundaries are encountered.

Parameters:

start - the start position in which to retrieve text for

length - the maximum number of characters to return. If the length parameter would cause the last position of the presentation space to be exceeded then only those characters up to the last position will be returned.

Returns:

a string representing a linear area of the presentation space which may be empty if the session is not connected

Throws:

InvalidPositionException - if the start parameter in not part of the presentation space

PresentationSpaceException - if an error occurs.

getSize

Dimension getSize()

Returns the size of the screen as a Dimension object. The screen size is 0,0 if the session is not connected

Returns:

a Dimension instance with the number of rows and columns

getCursorPosition

Position getCursorPosition()

Returns a Position instance representing the current cursor position. Position instance with a negative number for row or column represent a cursor located in the back buffer. An unconnected session will have a cursor position of 0,0.

Returns:

a Position instance representing the current cursor location.

setCursorPosition

void setCursorPosition(Position location)
                throws PresentationSpaceException

Moves the host cursor to the specified row and column position. For some emulations (notably VT), the host may constrain the movements of the cursor.

Parameters:

location - a Position instance representing where the cursor should be moved to.

Throws:

InvalidPositionException - if the location parameter is out of range for the presentation space.

PresentationSpaceException - if an error occurs.

isCursorVisible

boolean isCursorVisible()

Tests if the cursor is currently visible in the presentation space. A cursor is always considered not visible if the session is not connected.

Returns:

true if the cursor is visible; false if the cursor is not visible.

sendKeys

void sendKeys(String s)
       throws PresentationSpaceException

Transmits a string and/or terminal keys to the host at the current cursor position in the presentation space. If the cursor is not in the desired position then setCursorPosition can be called first. The string can be simply text to transmit, or it can consist of text plus key mnemonics. Key mnemonics are specific to each type of emulation, and are identified by square brackets around the keyname. For example, the mnemonic for the Enter key is "[enter]" (case sensitive). The text string can contain any number of strings and key mnemonics, so a string like "myname[tab]mypass[enter]" can be used to transmit a user ID, tab to the next field, transmit a password, then transmit the Enter key. To transmit a left or right square bracket, double the brackets: "[[" or "]]". When specifying key mnemonics, it's recommended that you use the KeyMnemonics enumeration instead of hard-coding the mnemonic strings. Use caution when using this form of SendKeys with VT and HP emulations. This method transmits the string to the desired location by first setting the cursor position, transmitting the string, then resetting the cursor position to the original position. In VT emulation, the host may constrain the cursor position, and the string may not be transmitted to the location you expect. Further, with both VT and HP emulations, because the cursor position is reset immediately after the string is transmitted, the data returned from the host may appear at the original cursor position, not at the position you specify in this method. If the data does not appear at the desired location, use the setCursorPos() method to set the cursor position yourself, then use sendKeys() that does not require a position.

Parameters:

s - the string of text and key mnemonics to transmit.

Throws:

PresentationSpaceException - if an error occurs in parsing or transmitting the string