putStringEx Method

Copies a string of text to the specified position in the presentation space and returns the number of characters written.

Syntax

C#
Visual Basic
C++/CLI

'Declaration
 
Public Function putStringEx( _ 
   ByVal inText As String, _ 
   ByVal inStartRow As Integer, _ 
   ByVal inStartColumn As Integer, _ 
   ByVal inEndRow As Integer, _ 
   ByVal inEndColumn As Integer, _ 
   ByVal inArea As Integer, _ 
   ByVal inWrap As Integer, _ 
   ByVal inModes As Integer, _ 
   ByVal inFill As Boolean _ 
) As Integer

'Usage
 
Dim instance As ScreenUPG 
Dim inText As String 
Dim inStartRow As Integer 
Dim inStartColumn As Integer 
Dim inEndRow As Integer 
Dim inEndColumn As Integer 
Dim inArea As Integer 
Dim inWrap As Integer 
Dim inModes As Integer 
Dim inFill As Boolean 
Dim value As Integer 
  
value = instance.putStringEx(inText, inStartRow, inStartColumn, inEndRow, inEndColumn, inArea, inWrap, inModes, inFill)

public int putStringEx( 
   string inText,
   int inStartRow,
   int inStartColumn,
   int inEndRow,
   int inEndColumn,
   int inArea,
   int inWrap,
   int inModes,
   bool inFill 
)

public: 
int putStringEx( 
   String^ inText,
   int inStartRow,
   int inStartColumn,
   int inEndRow,
   int inEndColumn,
   int inArea,
   int inWrap,
   int inModes,
   bool inFill 
)

Parameters

inText: The text to copy to the presentation space.
inStartRow: The row in which to begin writing.
inStartColumn: The column in which to begin writing.
inEndRow: The row at which to stop writing.
inEndColumn: The column at which to stop writing.
inArea: Reserved. Set to 0.
inWrap: Whether or not to wrap to the top after reaching the end of the presentation space. Possible values include: WRAP_ON and WRAP_OFF
inModes: Action to perform when a protected field is encountered while writing the string to the presentation space. Possible values include: PUTSTRING_SKIP, PUTSTRING_SPAN and PUTSTRING_STOP.
inFill: When true, the area specified is filled with the string specified by inText.

Return Value

The number of characters written.

Exceptions

Exception	Description
InputInhibitedException	Thrown if putStringEx was not able to complete successfully because a field with the input inhibited attribute was encountered.
ProtectedFieldException	Thrown if putStringEx was not able to complete successfully because a protected field was encountered.
TruncatedException	Thrown if there is not enough room in the presentation space to write all of the data specified by putString.

Remarks

Note: putStringEx only copies text (not keystrokes) to the presentation space and will overwrite any existing text. It is not affected by enabling Insert mode. To send keystrokes (such as Transmit or Tab) or to insert characters use sendKeys.

Example

C#
Visual Basic

try
{
	string inText = "a text string";
	int inStartRow = 1;
	int inStartColumn = 1;
	int inEndRow = 24;
	int inEndColumng = 80;
	int inArea = 0;
	int inWrap = ScreenUPG.ScreenUPG.WRAP_ON;
	int inMode = ScreenUPG.ScreenUPG.PUTSTRING_STOP;
	bool inFill = true;
            
	// Fill the presentation space, starting at the home position with the text
	int charsWritten = screen.putStringEx(inText, inStartRow, inStartColumn, inEndRow, inEndColumn, inArea, inWrap, inMode, inFill);
}
catch(ProtectedFieldException e)
{
	Console.Write("ProtectedFieldException\n");
}
catch(InputInhibitedException e)
{
	Console.Write("InputInhibitedException\n");
}
catch(TruncatedException e)
{
	Console.Write("TruncatedException\n");
}

Dim inText As String
Dim inStartRow As Integer
Dim inStartColumn As Integer
Dim inEndRow As Integer
Dim inEndColumn As Integer
Dim inArea As Integer
Dim inWrap As Integer
Dim inMode As Integer
Dim inFill As Boolean
Dim charsWritten As Integer
            
'Text to send at home position
inText = "a text string"
inStartRow = 1
inStartColumn = 1
inEndRow = 24
inEndColumn = 80
inArea = 0
inWrap = 1
inMode = 0
inFill = True
            
'Fill the presentation space, starting at the home position with the text
charsWritten = screen.putStringEx(inText, inStartRow, inStartColumn, inEndRow, inEndColumn, inArea, inWrap, inMode, inFill)

Requirements

Target Platforms: Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

Reference

ScreenUPG Class
ScreenUPG Members
putString Method
sendKeys Method
PUTSTRING_SKIP Property
PUTSTRING_SPAN Property
PUTSTRING_STOP Property
WRAP_OFF Property
WRAP_ON Property