AddField (Screen function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
mNo edit summary
Line 3: Line 3:
This callable function adds a field (an instance of a ScreenField object) to the screen represented by the method object (an instance of a Screen object).
This callable function adds a field (an instance of a ScreenField object) to the screen represented by the method object (an instance of a Screen object).


A ScreenField can only be defined within the limits of the current screen. The number of rows and columns in the current screen is determined by Screen class methods (“Rows property” and “Columns property”, below). An attempt to define a field outside these boundaries results in request cancellation. If any part of a new screen field would overlap an existing field, the request is cancelled.
A ScreenField can only be defined within the limits of the current screen. The number of rows and columns in the current screen is determined by Screen class methods (“Rows property” and “Columns property”, below). An attempt to define a field outside these boundaries results in request cancellation. If any part of a new screen field would overlap an existing field, the request is cancelled.
==Syntax==
==Syntax==
{{Template:Screen:AddField syntax}}
{{Template:Screen:AddField syntax}}
Line 12: Line 12:
<tr><th>%screen</th>
<tr><th>%screen</th>
<td>A reference to an instance of a Screen object. </td></tr>
<td>A reference to an instance of a Screen object. </td></tr>
<tr><th>Color= fieldcolor</th>
<tr><th><var>Color= fieldcolor</var></th>
<td>The optional Color argument (name required) is a Fieldcolor enumeration value. Valid values (case unimportant) are turquoise, green, blue, red, white, yellow, and pink. The default is blue.
<td>The optional Color argument (name required) is a Fieldcolor enumeration value. Valid values (case unimportant) are turquoise, green, blue, red, white, yellow, and pink. The default is blue.
  This parameter explicitly sets the color for a screen field. The Color method (&amp;amp;#x201C;Color property&amp;amp;#x201D;, below) lets you reset it. You can use the ProtectedColor (&amp;amp;#x201C;ProtectedColor property&amp;amp;#x201D;) and UnprotectedColor (&amp;amp;#x201C;UnprotectedColor property&amp;amp;#x201D;) methods to set defaults for a screen's protected and unprotected fields, respectively. </td></tr>
  This parameter explicitly sets the color for a screen field. The Color method (&amp;amp;amp;#x201C;Color property&amp;amp;amp;#x201D;, below) lets you reset it. You can use the ProtectedColor (&amp;amp;amp;#x201C;ProtectedColor property&amp;amp;amp;#x201D;) and UnprotectedColor (&amp;amp;amp;#x201C;UnprotectedColor property&amp;amp;amp;#x201D;) methods to set defaults for a screen's protected and unprotected fields, respectively. </td></tr>
<tr><th>Column= num</th>
<tr><th><var>Column= num</var></th>
<td>The optional Column argument (name required) is a numeric value indicating the first column position in the field. This first column, in any field, is reserved for an attribute byte and cannot contain displayable data (it appears on a screen as a blank). The field's value (display data) begins by default in the column immediately following the reserved column. The first column in a screen is column 1; the last column can be determined with the Columns method (&amp;amp;#x201C;Columns property&amp;amp;#x201D;, below). The default Column value is one greater than the ending column number of the preceding field, or it is 1.
<td>The optional Column argument (name required) is a numeric value indicating the first column position in the field. This first column, in any field, is reserved for an attribute byte and cannot contain displayable data (it appears on a screen as a blank). The field's value (display data) begins by default in the column immediately following the reserved column. The first column in a screen is column 1; the last column can be determined with the Columns method (&amp;amp;amp;#x201C;Columns property&amp;amp;amp;#x201D;, below). The default Column value is one greater than the ending column number of the preceding field, or it is 1.
  </td></tr>
  </td></tr>
<tr><th>Highlight= highlight</th>
<tr><th><var>Highlight= highlight</var></th>
<td>The optional Highlight argument (name required) is a Highlight enumeration value. Valid values (case unimportant) are: Underline, Reverse, Blink, or None. A ScreenField may have only one Highlight attribute. The Highlight property (&amp;amp;#x201C;Highlight&amp;amp;#x201D; on page 909) lets you reset it. The default is None. </td></tr>
<td>The optional Highlight argument (name required) is a Highlight enumeration value. Valid values (case unimportant) are: Underline, Reverse, Blink, or None. A ScreenField may have only one Highlight attribute. The Highlight property (&amp;amp;amp;#x201C;Highlight&amp;amp;amp;#x201D; on page 909) lets you reset it. The default is None. </td></tr>
<tr><th>Invisible= bool</th>
<tr><th><var>Invisible= bool</var></th>
<td>The optional Invisible argument (name required) is a Boolean enumeration value: if True, any data in the field will not displayed on the terminal. If False (the default), the screen field data is displayed on the terminal. The Invisible property lets you reset the value. The invisible attribute can be applied to protected or nonprotected fields. It is typically used to hide password prompts or other private data, but it does not encrypt or suppress transmission of data over the network. It is intended to minimize theft of private data at terminals situated in non-private areas. </td></tr>
<td>The optional Invisible argument (name required) is a Boolean enumeration value: if True, any data in the field will not displayed on the terminal. If False (the default), the screen field data is displayed on the terminal. The Invisible property lets you reset the value. The invisible attribute can be applied to protected or nonprotected fields. It is typically used to hide password prompts or other private data, but it does not encrypt or suppress transmission of data over the network. It is intended to minimize theft of private data at terminals situated in non-private areas. </td></tr>
<tr><th>Itemid= num</th>
<tr><th><var>Itemid= num</var></th>
<td>The optional Itemid argument (name required) is a numeric value assigned to the the screenfield that allows the CursorItemID method to identify the screenfield that contains the cursor after a screen read. The default ID number is 0. The item ID should be a unique value for each screenfield, but this is not enforced by the AddField method. You can reset the ID using the ScreenField ItemID method (&amp;amp;#x201C;Itemid property&amp;amp;#x201D;, below). ItemIDs are most useful when using arraylists of ScreenFields. This is commonly done for scrolling applications. </td></tr>
<td>The optional Itemid argument (name required) is a numeric value assigned to the the screenfield that allows the CursorItemID method to identify the screenfield that contains the cursor after a screen read. The default ID number is 0. The item ID should be a unique value for each screenfield, but this is not enforced by the AddField method. You can reset the ID using the ScreenField ItemID method (&amp;amp;amp;#x201C;Itemid property&amp;amp;amp;#x201D;, below). ItemIDs are most useful when using arraylists of ScreenFields. This is commonly done for scrolling applications. </td></tr>
<tr><th>Modified= bool</th>
<tr><th><var>Modified= bool</var></th>
<td>The optional Modified argument (name required) is a Boolean enumeration value that indicates whether a ScreenField value has been modified by the user: True indicates the ScreenField has been modified by the user. The default, False, indicates the ScreenField has not been modified. Regardless of the initial setting of this argument, the value of the Modified property for a field is always set by the Read method. </td></tr>
<td>The optional Modified argument (name required) is a Boolean enumeration value that indicates whether a ScreenField value has been modified by the user: True indicates the ScreenField has been modified by the user. The default, False, indicates the ScreenField has not been modified. Regardless of the initial setting of this argument, the value of the Modified property for a field is always set by the Read method. </td></tr>
<tr><th>Numeric= bool</th>
<tr><th><var>Numeric= bool</var></th>
<td>The optional Numeric argument (name required) is a Boolean enumeration value: if True, and the field is not protected, only numeric values may be entered in the field. Numeric values must be composed of the characters 0 through 9, plus (+), minus (-), and period (.). If False (the default), field input is not restricted to numeric data. The Numeric property (&amp;amp;#x201C;Numeric&amp;amp;#x201D;, below) lets you reset the value. Regardless of the value of the Numeric attribute, the programmer can assign any type of value to the field. Enforcement of the Numeric attribute takes place only when a user enters data in the field. Some terminal emulators do not enforce numeric field restrictions, so the programmer should be aware that the value of a numeric field must still be checked for validity.
<td>The optional Numeric argument (name required) is a Boolean enumeration value: if True, and the field is not protected, only numeric values may be entered in the field. Numeric values must be composed of the characters 0 through 9, plus (+), minus (-), and period (.). If False (the default), field input is not restricted to numeric data. The Numeric property (&amp;amp;amp;#x201C;Numeric&amp;amp;amp;#x201D;, below) lets you reset the value. Regardless of the value of the Numeric attribute, the programmer can assign any type of value to the field. Enforcement of the Numeric attribute takes place only when a user enters data in the field. Some terminal emulators do not enforce numeric field restrictions, so the programmer should be aware that the value of a numeric field must still be checked for validity.
  </td></tr>
  </td></tr>
<tr><th>Protected= bool</th>
<tr><th><var>Protected= bool</var></th>
<td>The optional Protected argument (name required) is a Boolean enumeration value: if True, the field will be protected against modification by the user when the screen is displayed. If False, the screen field will be an input field. New fields are protected by default. The value of this attribute can be reset using the Protected method (&amp;amp;#x201C;Protected property&amp;amp;#x201D;, below). </td></tr>
<td>The optional Protected argument (name required) is a Boolean enumeration value: if True, the field will be protected against modification by the user when the screen is displayed. If False, the screen field will be an input field. New fields are protected by default. The value of this attribute can be reset using the Protected method (&amp;amp;amp;#x201C;Protected property&amp;amp;amp;#x201D;, below). </td></tr>
<tr><th>Row= num</th>
<tr><th><var>Row= num</var></th>
<td>The optional Row argument (name required) is a numeric value indicating the starting row number for the field. The first row in a screen is row 1, and the last can be determined with the Rows method (&amp;amp;#x201C;Rows property&amp;amp;#x201D;, below).  Any row number in the screen may be used for a field. No rows are reserved by Janus SOAP. A field may occupy more than one row. The first position in any field is reserved for an attribute byte, which cannot contain displayable data and appears on a screen as a blank. A field's display data begins by default in the column immediately following the reserved byte. The Row default value is 1 or the value specified or implied by the previous AddField call.
<td>The optional Row argument (name required) is a numeric value indicating the starting row number for the field. The first row in a screen is row 1, and the last can be determined with the Rows method (&amp;amp;amp;#x201C;Rows property&amp;amp;amp;#x201D;, below).  Any row number in the screen may be used for a field. No rows are reserved by Janus SOAP. A field may occupy more than one row. The first position in any field is reserved for an attribute byte, which cannot contain displayable data and appears on a screen as a blank. A field's display data begins by default in the column immediately following the reserved byte. The Row default value is 1 or the value specified or implied by the previous AddField call.
  </td></tr>
  </td></tr>
<tr><th>Value= string</th>
<tr><th><var>Value= string</var></th>
<td>The optional Value argument (name required) is a string that contains the screen data to be displayed. The Value parameter is simply a convenient way to set display data when the screenfield is instantiated.
<td>The optional Value argument (name required) is a string that contains the screen data to be displayed. The Value parameter is simply a convenient way to set display data when the screenfield is instantiated.
The [[Value_(ScreenField_property)|Screenfield class Value method]] performs the same work, but can also get user-entered data for a screenField. For more information on setting and getting screenField values, see &amp;amp;#x201C;Value property&amp;amp;#x201D;.
The [[Value_(ScreenField_property)|Screenfield class Value method]] performs the same work, but can also get user-entered data for a screenField. For more information on setting and getting screenField values, see &amp;amp;amp;#x201C;Value property&amp;amp;amp;#x201D;.
  </td></tr>
  </td></tr>
<tr><th>Width=width</th>
<tr><th><var>Width=width</var></th>
<td>The optional Width argument (name required) is a numeric value indicating the length of the screen field, excluding the attribute byte. The first position in any field is occupied by an attribute byte, which cannot contain user data. The minimum width for a field is 1, and the maximum width is 255. If no width is specified, the width of the field is determined by the length of the string specified in the method's Value parameter. If neither a Width nor a Value parameter is specified, the request is cancelled. If both Width and Value parameters are specified, the Width parameter is used to set the field width, and the Value is silently padded or truncated accordingly.
<td>The optional Width argument (name required) is a numeric value indicating the length of the screen field, excluding the attribute byte. The first position in any field is occupied by an attribute byte, which cannot contain user data. The minimum width for a field is 1, and the maximum width is 255. If no width is specified, the width of the field is determined by the length of the string specified in the method's Value parameter. If neither a Width nor a Value parameter is specified, the request is cancelled. If both Width and Value parameters are specified, the Width parameter is used to set the field width, and the Value is silently padded or truncated accordingly.
  The Width property lets you reset the width.</td></tr>
  The Width property lets you reset the width.</td></tr>
Line 45: Line 45:
==Usage notes==
==Usage notes==


Each of the screenfield attributes specified by the AddField optional parameters can be updated by their like-named <var>ScreenField</var> [[List of ScreenField methods|methods]]. The &#x201C;modified&#x201D; and &#x201C;value&#x201D; attributes are also set by a user screen-interaction.
Each of the screenfield attributes specified by the AddField optional parameters can be updated by their like-named <var>ScreenField</var> [[List of ScreenField methods|methods]]. The &amp;#x201C;modified&amp;#x201D; and &amp;#x201C;value&amp;#x201D; attributes are also set by a user screen-interaction.


==See also==
==See also==
{{Template:Screen:AddField footer}}
{{Template:Screen:AddField footer}}

Revision as of 01:04, 13 April 2011

Add a field to an instance of a screen object (Screen class)


This callable function adds a field (an instance of a ScreenField object) to the screen represented by the method object (an instance of a Screen object).

A ScreenField can only be defined within the limits of the current screen. The number of rows and columns in the current screen is determined by Screen class methods (&amp;amp;#x201C;Rows property&amp;amp;#x201D; and &amp;amp;#x201C;Columns property&amp;amp;#x201D;, below). An attempt to define a field outside these boundaries results in request cancellation. If any part of a new screen field would overlap an existing field, the request is cancelled.

Syntax

[%sfield =] screen:AddField[( [Row= number], [Column= number], - [Width= number], [Color= fieldColor], - [Protected= boolean], [Highlight= highlight], - [Numeric= boolean], [Modified= boolean], - [Invisible= boolean], [Autoskip= boolean], - [Itemid= number], [Strip= boolean], - [Value= string])]

Syntax terms

%sfield A declared ScreenField object that is set to a new ScreenField object reference.
%screen A reference to an instance of a Screen object.
Color= fieldcolor The optional Color argument (name required) is a Fieldcolor enumeration value. Valid values (case unimportant) are turquoise, green, blue, red, white, yellow, and pink. The default is blue. This parameter explicitly sets the color for a screen field. The Color method (&amp;amp;#x201C;Color property&amp;amp;#x201D;, below) lets you reset it. You can use the ProtectedColor (&amp;amp;#x201C;ProtectedColor property&amp;amp;#x201D;) and UnprotectedColor (&amp;amp;#x201C;UnprotectedColor property&amp;amp;#x201D;) methods to set defaults for a screen's protected and unprotected fields, respectively.
Column= num The optional Column argument (name required) is a numeric value indicating the first column position in the field. This first column, in any field, is reserved for an attribute byte and cannot contain displayable data (it appears on a screen as a blank). The field's value (display data) begins by default in the column immediately following the reserved column. The first column in a screen is column 1; the last column can be determined with the Columns method (&amp;amp;#x201C;Columns property&amp;amp;#x201D;, below). The default Column value is one greater than the ending column number of the preceding field, or it is 1.
Highlight= highlight The optional Highlight argument (name required) is a Highlight enumeration value. Valid values (case unimportant) are: Underline, Reverse, Blink, or None. A ScreenField may have only one Highlight attribute. The Highlight property (&amp;amp;#x201C;Highlight&amp;amp;#x201D; on page 909) lets you reset it. The default is None.
Invisible= bool The optional Invisible argument (name required) is a Boolean enumeration value: if True, any data in the field will not displayed on the terminal. If False (the default), the screen field data is displayed on the terminal. The Invisible property lets you reset the value. The invisible attribute can be applied to protected or nonprotected fields. It is typically used to hide password prompts or other private data, but it does not encrypt or suppress transmission of data over the network. It is intended to minimize theft of private data at terminals situated in non-private areas.
Itemid= num The optional Itemid argument (name required) is a numeric value assigned to the the screenfield that allows the CursorItemID method to identify the screenfield that contains the cursor after a screen read. The default ID number is 0. The item ID should be a unique value for each screenfield, but this is not enforced by the AddField method. You can reset the ID using the ScreenField ItemID method (&amp;amp;#x201C;Itemid property&amp;amp;#x201D;, below). ItemIDs are most useful when using arraylists of ScreenFields. This is commonly done for scrolling applications.
Modified= bool The optional Modified argument (name required) is a Boolean enumeration value that indicates whether a ScreenField value has been modified by the user: True indicates the ScreenField has been modified by the user. The default, False, indicates the ScreenField has not been modified. Regardless of the initial setting of this argument, the value of the Modified property for a field is always set by the Read method.
Numeric= bool The optional Numeric argument (name required) is a Boolean enumeration value: if True, and the field is not protected, only numeric values may be entered in the field. Numeric values must be composed of the characters 0 through 9, plus (+), minus (-), and period (.). If False (the default), field input is not restricted to numeric data. The Numeric property (&amp;amp;#x201C;Numeric&amp;amp;#x201D;, below) lets you reset the value. Regardless of the value of the Numeric attribute, the programmer can assign any type of value to the field. Enforcement of the Numeric attribute takes place only when a user enters data in the field. Some terminal emulators do not enforce numeric field restrictions, so the programmer should be aware that the value of a numeric field must still be checked for validity.
Protected= bool The optional Protected argument (name required) is a Boolean enumeration value: if True, the field will be protected against modification by the user when the screen is displayed. If False, the screen field will be an input field. New fields are protected by default. The value of this attribute can be reset using the Protected method (&amp;amp;#x201C;Protected property&amp;amp;#x201D;, below).
Row= num The optional Row argument (name required) is a numeric value indicating the starting row number for the field. The first row in a screen is row 1, and the last can be determined with the Rows method (&amp;amp;#x201C;Rows property&amp;amp;#x201D;, below). Any row number in the screen may be used for a field. No rows are reserved by Janus SOAP. A field may occupy more than one row. The first position in any field is reserved for an attribute byte, which cannot contain displayable data and appears on a screen as a blank. A field's display data begins by default in the column immediately following the reserved byte. The Row default value is 1 or the value specified or implied by the previous AddField call.
Value= string The optional Value argument (name required) is a string that contains the screen data to be displayed. The Value parameter is simply a convenient way to set display data when the screenfield is instantiated.

The Screenfield class Value method performs the same work, but can also get user-entered data for a screenField. For more information on setting and getting screenField values, see &amp;amp;#x201C;Value property&amp;amp;#x201D;.

Width=width The optional Width argument (name required) is a numeric value indicating the length of the screen field, excluding the attribute byte. The first position in any field is occupied by an attribute byte, which cannot contain user data. The minimum width for a field is 1, and the maximum width is 255. If no width is specified, the width of the field is determined by the length of the string specified in the method's Value parameter. If neither a Width nor a Value parameter is specified, the request is cancelled. If both Width and Value parameters are specified, the Width parameter is used to set the field width, and the Value is silently padded or truncated accordingly. The Width property lets you reset the width.

Usage notes

Each of the screenfield attributes specified by the AddField optional parameters can be updated by their like-named ScreenField methods. The &#x201C;modified&#x201D; and &#x201C;value&#x201D; attributes are also set by a user screen-interaction.

See also