AddField (Screen function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (reads better this way)
 
(12 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{Template:Screen:AddField subtitle}}
{{Template:Screen:AddField subtitle}}
The <var>AddField</var> callable function adds a field (an instance of a <var>[[ScreenField_class|ScreenField]]</var> object) to the screen represented by the method object (an instance of a <var>[[Screen_class|Screen]]</var> object).
The <var>AddField</var> [[Notation conventions for methods#Callable functions|callable]] function adds a field (an instance of a <var>[[ScreenField_class|ScreenField]]</var> object) to the screen represented by the method object (an instance of a <var>[[Screen_class|Screen]]</var> object).


A <var>ScreenField</var> can only be defined within the limits of the current screen. The number of rows and columns in the current screen is determined by <var>Screen</var> class methods (<var>[[Rows_(Screen_function)|Rows]]</var> and <var>[[Columns_(Screen_function)|Columns]]</var> properties).  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 <var>ScreenField</var> can only be defined within the limits of the current screen. The number of rows and columns in the current screen is determined by <var>Screen</var> class methods (<var>[[Rows_(Screen_function)|Rows]]</var> and <var>[[Columns_(Screen_function)|Columns]]</var> properties).  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.
Line 6: Line 6:
==Syntax==
==Syntax==
{{Template:Screen:AddField syntax}}
{{Template:Screen:AddField syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%field</th>
 
<tr><th>%sfield</th>
<td>A declared <var>ScreenField</var> object that is set to a new <var>ScreenField</var> object reference. </td></tr>
<td>A declared <var>ScreenField</var> object that is set to a new <var>ScreenField</var> object reference. </td></tr>
<tr><th>screen</th>
<tr><th>screen</th>
<td>A reference to an instance of a <var>Screen</var> object. </td></tr>
<td>A reference to an instance of a <var>Screen</var> object. </td></tr>


<tr><th>Row</th>
<tr><th><var>Row</var></th>
<td><var class="term">Row</var> is an optional, but <var>[[Methods#Named parameters|Name-Required]]</var>, 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 <var>Rows</var> method. Any row number in the screen may be used for a field.  No rows are reserved by <var class="product">[[Janus SOAP|"Janus Soap"]]</var>.  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 <var class="term">Row</var> default value is 1 or the value specified or implied by the previous <var>AddField</var> call.</td></tr>
<td><var>Row</var> is an optional, but [[Notation conventions for methods#Named parameters|name required]], <var class="term">number</var> 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 <var>Rows</var> method.
<p>
Any row number in the screen may be used for a field.  No rows are reserved by <var class="product">[[:Category:SOUL|SOUL]]</var>.  A field may occupy more than one row.</p>
<p>
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.</p>
<p>
The <var>Row</var> default value is 1 or the value specified or implied by the previous <var>AddField</var> call.</p></td></tr>


<tr><th>Column</th>
<tr><th><var>Column</var></th>
<td><var class="term">Column</var> is an optional, but <var>Name-Required</var>, 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 <var>Columns</var> method. The default <var class="term">Column</var> value is one greater than the ending column number of the preceding field, or it is 1 if no previous fields.</td></tr>
<td><var>Column</var> is an optional, name required, <var class="term">number</var> 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.
<p>
The first column in a screen is column 1; the last column can be determined with the <var>Columns</var> method.</p>
<p>
The default <var>Column</var> value is one greater than the ending column number of the preceding field, or it is 1 if no previous fields.</p></td></tr>


<tr><th>Width</th>
<tr><th><var>Width</var></th>
<td><var class="term">Width</var> is an optional, but <var>Name-Required</var>, 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 <code>1</code>, and the maximum width is <code>255</code>. If no width is specified, the width of the field is determined by the length of the string specified in the method's <var class="term">Value</var> parameter.  If neither a <var class="term">Width</var> nor a <var class="term">Value</var> parameter is specified, the request is cancelled.  If both <var class="term">Width</var> and <var class="term">Value</var> parameters are specified, the <var class="term">Width</var> parameter is used to set the field width, and the <var class="term">Value</var> is silently padded or truncated accordingly. The <var>[[Width_(ScreenField_property)|Width]]</var> property lets you reset the width.</td></tr>
<td><var>Width</var> is an optional, name required, <var class="term">number</var> 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 <code>1</code>, and the maximum width is <code>255</code>.
<p>
If no width is specified, the width of the field is determined by the length of the string specified in the method's <var>Value</var> parameter.  If neither a <var>Width</var> nor a <var>Value</var> parameter is specified, the request is cancelled.  If both <var>Width</var> and <var>Value</var> parameters are specified, the <var>Width</var> parameter is used to set the field width, and the <var>Value</var> is silently padded or truncated accordingly.</p></td></tr>


<tr><th>Color</th>
<tr><th><var>Color</var></th>
<td><var class="term">Color</var> is an optional, but <var>Name-Required</var>, <var>Fieldcolor</var> enumeration value. Valid values (case unimportant) are <code>turquoise</code>, <code>green</code>, <code>blue</code>, <code>red</code>, <code>white</code>, <code>yellow</code>, and <code>pink</code>. The default is <code>blue</code>.   This parameter explicitly sets the color for a screen field. The <var>[[Color_(ScreenField_property)|Color]]</var> method lets you reset it. You can use the <var class="term">[[ProtectedColor_(Screen_property)|ProtectedColor]]</var> and <var class="term">[[UnprotectedColor_(Screen_property)|UnprotectedColor]]</var> methods to set defaults for a screen's protected and unprotected fields, respectively. </td></tr>
<td><var>Color</var> is an optional, name required, <var>[[Color_(ScreenField_property)#FieldColor_enumeration|Fieldcolor]]</var> enumeration value. Valid values (case unimportant) are <code>turquoise</code>, <code>green</code>, <code>blue</code>, <code>red</code>, <code>white</code>, <code>yellow</code>, and <code>pink</code>. The default is <code>blue</code>.
<p>
This parameter explicitly sets the color for a screen field. The <var>[[Color_(ScreenField_property)|Color]]</var> method lets you reset it.</p>
<p>
You can use the <var>[[ProtectedColor_(Screen_property)|ProtectedColor]]</var> and <var>[[UnprotectedColor_(Screen_property)|UnprotectedColor]]</var> methods to set defaults for a screen's protected and unprotected fields, respectively.</p></td></tr>


<tr><th>Protected</th>
<tr><th><var>Protected</var></th>
<td><var class="term">Protected</var> is an optional, but <var>Name-Required</var>, <var>[[Boolean_enumeration|Boolean enumeration]]</var> value.  If <code>True</code>, the field will be protected against modification by the user when the screen is displayed.  If <code>False</code>, the screen field will be an input field. New fields are protected by default. The value of this attribute can be reset using the <var>[[Protected_(ScreenField_property)|Protected]]</var> method. </td></tr>
<td><var>Protected</var> is an optional, name required, [[Boolean_enumeration]] value.  If <code>True</code>, the field will be protected against modification by the user when the screen is displayed.  If <code>False</code>, the screen field will be an input field.
<p>
New fields are protected by default.</p>
<p>
The value of this attribute can be reset using the <var>[[Protected_(ScreenField_property)|Protected]]</var> method.</p></td></tr>


<tr><th>Highlight</th>
<tr><th><var>Highlight</var></th>
<td><var class="term">Highlight</var> is an optional, but <var>Name-Required</var>, <var>Highlight</var> enumeration value.  Valid values (case unimportant) are: <code>Underline</code>, <code>Reverse</code>, <code>Blink</code>, or <code>None</code>. A <var>ScreenField</var> may have only one <var>Highlight</var> attribute.  The <var>[[Highlight_(ScreenField_property)|Highlight]]</var> property lets you reset it. The default is <code>None</code>.</td></tr>
<td><var>Highlight</var> is an optional, name required, [[Highlight_enumeration]] value.  Valid values (case unimportant) are: <code>Underline</code>, <code>Reverse</code>, <code>Blink</code>, or <code>None</code>.
<p>
A <var>ScreenField</var> may have only one <var>Highlight</var> attribute.  The <var>[[Highlight_(ScreenField_property)|Highlight]]</var> property lets you reset it. The default is <code>None</code>.</p></td></tr>


<tr><th>Numeric</th>
<tr><th><var>Numeric</var></th>
<td><var class="term">Numeric</var> is an optional, but <var>Name-Required</var>, <var>Boolean enumeration</var> value.  If <code>True</code>, and the field is not protected, only numeric values may be entered in the field; numeric values must be composed of the characters <code>0</code> through <code>9</code>, plus (<code>+</code>), minus (<code>-</code>), and period (<code>.</code>). If <code>False</code> (the default), field input is not restricted to numeric data.  The <var>[[Numeric_(ScreenField_property)|Numeric]]</var> property lets you reset the value. Regardless of the value of the <var>Numeric</var> attribute, the programmer can assign any type of value to the field.  Enforcement of the <var>Numeric</var> 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><var>Numeric</var> is an optional, name required, <var>Boolean</var> enumeration value.  If <code>True</code>, and the field is not protected, only numeric values may be entered in the field; numeric values must be composed of the characters <code>0</code> through <code>9</code>, plus (<code>+</code>), minus (<code>-</code>), and period (<code>.</code>).<p>If <code>False</code> (the default), field input is not restricted to numeric data.  The <var>[[Numeric_(ScreenField_property)|Numeric]]</var> property lets you reset the value.</p>
<p>
Regardless of the value of the <var>Numeric</var> attribute, the programmer can assign any type of value to the field.  Enforcement of the <var>Numeric</var> attribute takes place only when a user enters data in the field.</p>
<p>
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.</p></td></tr>


<tr><th>Modified</th>
<tr><th><var>Modified</var></th>
<td><var class="term">Modified</var> is an optional, but <var>Name-Required</var>, <var>Boolean enumeration</var> value that indicates whether a <var>ScreenField</var> value has been modified by the user.  <code>True</code> indicates the <var>ScreenField</var> has been modified by the user.  The default, <code>False</code>, indicates the <var>ScreenField</var> has not been modified. Regardless of the initial setting of this argument, the value of the <var>Modified</var> property for a field is always set by the <var>[[Read_(Screen_function)|Read]]</var> method.</td></tr>
<td><var>Modified</var> is an optional, name required, <var>Boolean</var> enumeration value that indicates whether a <var>ScreenField</var> value has been modified by the user.  <code>True</code> indicates the <var>ScreenField</var> has been modified by the user.  The default, <code>False</code>, indicates the <var>ScreenField</var> has not been modified.<p>Regardless of the initial setting of this argument, the value of the <var>Modified</var> property for a field is always set by the <var>[[Read_(Screen_function)|Read]]</var> method.</p></td></tr>


<tr><th>Invisible</th>
<tr><th><var>Invisible</var></th>
<td><var class="term">Invisible</var> is an optional, but <var>Name-Required</var>, <var>Boolean enumeration</var> value.  If <code>True</code>, any data in the field will not displayed on the terminal.  If <code>False</code> (the default), the screen field data is displayed on the terminal. The <var>[[Invisible_(ScreenField_property)|Invisible]]</var> 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><var>Invisible</var> is an optional, name required, <var>Boolean</var> enumeration value.  If <code>True</code>, any data in the field will not displayed on the terminal.  If <code>False</code> (the default), the screen field data is displayed on the terminal.<p>The <var>[[Invisible_(ScreenField_property)|Invisible]]</var> 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.</p></td></tr>


<tr><th><var>AutoSkip</var></th>
<tr><th><var>AutoSkip</var></th>
<td></td></tr>
<td><var>AutoSkip</var> is an optional, name required, <var>Boolean</var> enumeration value that indicates whether the cursor should automatically skip to the next input field when a character is entered in the last position of the current <var>ScreenField</var>.  <code>True</code> indicates the cursor will <var>AutoSkip</var>. This is the default. <code>False</code> indicates the cursor will not <var>AutoSkip</var>.</td></tr>


<tr><th>Itemid</th>
<tr><th><var>Itemid</var></th>
<td><var class="term">Itemid</var> is an optional, but <var>Name-Required</var>, numeric value that allows the <var>[[CursorItemId_(Screen_function)|CursorItemID]]</var> method to identify the screenfield that contains the cursor after a screen read. The default <var class="term">Itemid</var> number is <code>0</code>. The item ID should be a unique value for each screenfield, but this is not enforced by the <var>AddField</var> method.  You can reset the item ID using the <var>[[Itemid_(ScreenField_property)|ItemID</var> method. Item IDs are most useful when using <var>[[Arraylist_class|arraylists]]</var> of <var>ScreenFields</var>, which is commonly done for scrolling applications.</td></tr>
<td><var>Itemid</var> is an optional, name required, <var class="term">number</var> that allows the <var>[[CursorItemId_(Screen_function)|CursorItemID]]</var> method to identify the screenfield that contains the cursor after a screen read.
<p>
The default <var>Itemid</var> number is <code>0</code>. The item ID should be a unique value for each screenfield, but this is not enforced by the <var>AddField</var> method.  You can reset the item ID using the <var>[[Itemid_(ScreenField_property)|ItemID]]</var> method.</p><p>Item IDs are most useful when using an <var>[[Arraylist_class|Arraylist]]</var> of <var>ScreenFields</var>, which is commonly done for scrolling applications.</p></td></tr>


<tr><th>Value</th>
<tr><th><var>Value</var></th>
<td><var class="term">Value</var> is an optional, but <var>Name-Required</var>, string value that contains the screen data to be displayed.  The <var class="term">Value</var> parameter is simply a convenient way to set display data when the screenfield is instantiated. The <var>[[Value_(ScreenField_property)|Value]]</var> method performs the same work, but can also get user-entered data for a screenField. </td></tr>
<td><var>Value</var> is an optional, name required, <var class="term">string</var> that contains the screen data to be displayed.  The <var>Value</var> parameter is simply a convenient way to set display data when the screenfield is instantiated.<p>
The <var>[[Value_(ScreenField_property)|Value]]</var> method performs the same work, but can also get user-entered data for a screenField.</p></td></tr>


<tr><th><var>Strip</var></th>
<td><var>Strip</var> is an optional, name required, [[Boolean enumeration]] that lets you suppress the removal of leading and trailing blanks from input fields. <var>Strip</var> is available as of version 7.5 of Model&nbsp;204.</td></tr>
</table>
</table>


==Usage notes==
==Usage notes==
<ul>
<ul>
<li>Each of the screenfield attributes specified by the <var>AddField</var> optional parameters can be updated by their like-named <var>ScreenField</var> [[List of ScreenField methods|methods]]. The "modified" and "value" attributes are also set by a user screen-interaction.
<li>Each of the screen field attributes specified by the <var>AddField</var> optional parameters corresponds to a like-named <var>[[List of ScreenField methods|ScreenField]]</var> property.
<li>Some of those <var>ScreenField</var> properties, such as <var>[[Row (ScreenField property)|Row]]</var>, may not be modified, but others, such as <var>[[Invisible (ScreenField property)|Invisible]]</var>, may be modified.
<li>The values of the <var>[[Modified (ScreenField property)|Modified]]</var> and <var>[[Value (ScreenField property)|Value]]</var> properties are also set by a user screen-interaction.
</ul>
</ul>
==Examples==
For an example using the <var>AddField</var> method, see [[Screen object sample code|"Screen object sample code"]].


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

Latest revision as of 21:37, 24 July 2014

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

The AddField 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 and Columns properties). 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.
Row Row is an optional, but name required, number 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.

Any row number in the screen may be used for a field. No rows are reserved by SOUL. 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.

Column Column is an optional, name required, number 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.

The default Column value is one greater than the ending column number of the preceding field, or it is 1 if no previous fields.

Width Width is an optional, name required, number 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.

Color Color is an optional, name required, 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 lets you reset it.

You can use the ProtectedColor and UnprotectedColor methods to set defaults for a screen's protected and unprotected fields, respectively.

Protected Protected is an optional, name required, 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.

Highlight Highlight is an optional, name required, Highlight_enumeration value. Valid values (case unimportant) are: Underline, Reverse, Blink, or None.

A ScreenField may have only one Highlight attribute. The Highlight property lets you reset it. The default is None.

Numeric Numeric is an optional, name required, 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 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.

Modified Modified is an optional, name required, 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.

Invisible Invisible is an optional, name required, 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.

AutoSkip AutoSkip is an optional, name required, Boolean enumeration value that indicates whether the cursor should automatically skip to the next input field when a character is entered in the last position of the current ScreenField. True indicates the cursor will AutoSkip. This is the default. False indicates the cursor will not AutoSkip.
Itemid Itemid is an optional, name required, number that allows the CursorItemID method to identify the screenfield that contains the cursor after a screen read.

The default Itemid 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 item ID using the ItemID method.

Item IDs are most useful when using an Arraylist of ScreenFields, which is commonly done for scrolling applications.

Value Value is an optional, name required, 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 method performs the same work, but can also get user-entered data for a screenField.

Strip Strip is an optional, name required, Boolean enumeration that lets you suppress the removal of leading and trailing blanks from input fields. Strip is available as of version 7.5 of Model 204.

Usage notes

  • Each of the screen field attributes specified by the AddField optional parameters corresponds to a like-named ScreenField property.
  • Some of those ScreenField properties, such as Row, may not be modified, but others, such as Invisible, may be modified.
  • The values of the Modified and Value properties are also set by a user screen-interaction.

Examples

For an example using the AddField method, see "Screen object sample code".

See also