Entry fields do not use titles.
Entry fields take a numeric or alphanumeric value.
Conversion between the alphanumeric and numeric forms occurs automatically if you specify a numeric value. This allows you to use numeric data items with entry fields. When you use a numeric data item as an entry field's value, the runtime system prevents the user from entering non-numeric data
This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-CLASS should represent a corresponding class in the current theme (that is, a .class-name entry in the cascading style sheet) deployed when you run your program through AcuToWeb. This property can be applied to more than one control in your program.
If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.
See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.
This property enables you to apply CSS styles to the control when the program is run through AcuToWeb. The value of ATW-CSS-ID should represent a corresponding ID in the current theme (that is, a #class-name entry in the cascading style sheet) deployed when you run your program through AcuToWeb. The value of this property must be unique, and only applied to one control in your program.
If both the ATW-CSS-CLASS and ATW-CSS-ID properties are specified for this control, and both correspond to the same style in the style sheet, the style specified by ATW-CSS-ID takes precedence.
See Cascading Style Sheet Syntax for more information about additional in-built styles in AcuToWeb.
You may use the VALUE IS MULTIPLE value option with multi-line entry fields. The value data item should be a one-dimensional table with no subscript specified. The effect of the MULTIPLE phrase is to match each line of the entry field to occurrences in the table. The first line is matched to the first occurrence in the table, the second line with the second occurrence, and so on. Occurrences that are larger than the number of lines in the entry field are set to spaces when the entry field is accepted. The MULTIPLE option makes it easy to process a large multi-line entry field in COBOL.
There is one important issue to consider when you use the MULTIPLE value option. The runtime system does not provide a way to limit the amount of text the user can enter on a single line. Thus, the user could enter more text than a single occurrence of the value data item can hold. Normally, to prevent the user from entering extra data, you might set the width of the entry field to be the same as the size of the value data item. However, this does not always work, because entry fields typically use a proportionally spaced font. Some characters are smaller than others, and the user can thus enter more of those characters than the width of the entry field might suggest.
There are two possible ways of addressing this issue. One option is to use a fixed-width font with the entry field. Then the width of the field matches the number of characters that the user can enter. The other option is to use a value data item that is larger than the width of the entry field. You will need to experiment to find appropriate sizes. You might try a value data item that is 20% larger than the entry field.
This issue is not normally a problem for single-line entry fields: the MAX-TEXT property (see below) prevents the user from entering too much data.
Finally, note that you can have a multiple-line entry field without using the MULTIPLE value phrase. In this case, the entire contents of the entry field are returned as a single string. Any carriage returns that the user enters directly are kept as part of the string. Carriage returns implied by word-wrapping are discarded.
Use BORDER-COLOR to specify a color for the bounding area of the entry field. Use color names as values.
Entry fields determine their height by multiplying the LINES value by the height of the entry field's font. If the entry field is also boxed (the default), the space required for the box is added to the height.
Entry fields determine their width by multiplying the SIZE value by the standard or wide font measure. If the entry field is also boxed, the space required for the box is added to the width. Entry fields have a minimum width of at least one character.
When the program executes on a non-graphical system, the values specified in the CLINES and CSIZE phrases, if present, replace the values specified by the LINES and SIZE phrases.
The default LINES value is 1. The default SIZE value depends on whether or not a VALUE is specified when the field is created. If a VALUE is specified, the default SIZE equals the size of the VALUE literal or data item. Otherwise, the default SIZE is 8.
Most controls, including entry fields, base their width on the width of the 0 (zero) character in the control’s font. This usually works well because in most fonts, the 0 character is slightly wider than the average character. This means that the field is optimally sized for numeric data, and nearly optimally sized for alphanumeric data (actually it is slightly oversized, which is preferable because the user can enter data that is wider than average). In cases where the user enters very wide data, the entry field will scroll horizontally to fit all the data.
However, there are a few cases where this rule does not produce the best results. To handle these cases, several special sizing rules apply to entry fields.
The most pronounced problem arises when the input includes a lot of upper-case data. Upper-case characters are quite a lot wider than the average character (0), so when there are many upper-case characters they often do not fit in the space allotted by the normal rule. Therefore, additional rules handle two cases: (a) upper-case-only fields, and (b) small fields. Small fields require special handling because they tend to be coded fields (which are usually shown in upper-case). Also, scrolling in small fields feels odd to most users while scrolling in large fields is familiar.
To do a better job with these cases, the runtime employs a second font measurement. The second measure averages the width of the 0 (zero) character with the width of the maximum-width character in the font. This value is approximately the size of the average upper-case character in most fonts. We call this measurement the wide font measure. The size of the 0 character is known as the standard font measure.
When the runtime constructs an entry field, the first applicable rule from the list below is used to determine the entry field’s physical size. Overhead for the entry field’s box, if present, is added to this width.
See Appendix H. Configuration VariablesFor a detailed description of the FONT-SIZE-ADJUST and FONT-WIDE-SIZE-ADJUST configuration variables.
Entry fields will use any specified foreground or background color. If either color is omitted, that color uses a system-dependent default value. On most systems, the default foreground is black and the default background is white. Under Microsoft Windows, the default values are determined by the settings defined by the user in the Control Panel (usually black on bright-white). These system-dependent default colors are not transformed or mapped by the runtime's color-handling configuration options.
EVENT-LIST is an exclusive list of events that are either sent to or withheld (blocked) from the program, depending on the value of EXCLUDE-EVENT-LIST. See Common Screen Options for more information.
| NUMERIC | This style causes the entry field to accept only numeric data. The NUMERIC style is applied automatically to any entry field that has a numeric or numeric-edited VALUE specified for it before it is created. As a result, you don't normally need to specify this style explicitly. Use this style when creating an entry field that does not have an initial value, but which needs to be restricted to accepting only numeric data. |
| NO-BOX | On most host graphical systems, entry fields are boxed (on character-based systems, they are not). The NO-BOX style prevents the box from being shown. Generally speaking, boxed entry fields are preferred stylistically, but you may need to omit the box to conserve screen space. |
| BOXED | On graphical systems, this style causes a box to be drawn around the entry field (the default). You can use the BOXED style to override the FIELDS_UNBOXED configuration variable for individual entry fields. |
| 3-D |
This style causes the entry field to appear inscribed into the surface of the screen. This looks similar to the
LOWERED frame style. The runtime system uses the background color of the floating window to determine how to draw the frame. The
background color is set when the window is created and each time the window is erased. This color must be one of the low-intensity
standard colors, except for black (color numbers 2–7). Any other background color will prevent the 3-D effect from displaying.
Only boxed entry fields will display 3-D effects. See
Frame for more information.
Note: There are no 3D effects when using WIN32_NATIVECTLS. Instead the border will be blue-gray in color.
|
| LEFT | This style causes the value to be shown left-justified in the entry field (the default). Changing this style after the control has been created has no effect. |
| RIGHT | This style causes the value to be shown right-justified in the entry field. This style implies that the entry field is MULTILINE. Changing this style after the control has been created has no effect |
| CENTER, CENTERED | This style is supported only in Windows. It centers the text in the entry field. This style is allowed on other systems, but it has no effect. Changing this style after the control has been created has no effect. |
| MULTILINE |
This style indicates that the field can display and accept more than one line of text. An entry field created with a
LINES setting of two (2) or more automatically has this style applied to it, unless the
CELLS phrase is also used or implied. For this reason, you usually will not need to specify this style explicitly.
Note: An entry field created with the CELLS phrase following the
LINES
value phrase has the single-line style applied to it by default
|
| VSCROLL | This style allows the user to scroll the contents of the entry field vertically. Without this style, the user may not enter more lines of text than the entry field can hold. With this style, the field will scroll as needed to allow the user to enter multiple lines of text. This style automatically implies the MULTILINE style. |
| VSCROLL-BAR | This style is identical to the VSCROLL style (above), with the addition that a vertical scroll bar is placed to the side of the entry field. The size of the entry field is extended to include the space needed by the scroll bar. |
| USE-RETURN | The Enter (or Return) key typically terminates entry. If you specify the USE-RETURN style, the Enter key is instead used to start a new line within the entry field, when the field is active. Without this style, pressing Enter (normally) terminates input. |
| USE-TAB | The Tab key is typically used to move between fields. If you specify the USE-TAB style, the user can enter a tab within the entry field when the field is active. This prevents the user from using the Tab key to leave the field. |
| LOWER | This style converts all keyboard entry to lower-case for this field. This style can be changed to UPPER with the MODIFY statement after the control has been created. |
| UPPER | This style converts all keyboard entry to upper-case for this field. This style can be changed to LOWER with the MODIFY statement after the control has been created. |
| NO-AUTOSEL | Normally, when an entry field is activated, all of its current contents are selected and highlighted (exception: if the field is activated by the mouse, this does not occur). This allows users to replace the entire contents of the field by simply typing in a new value (they can edit the current contents by using editing keys, or keep the current value by terminating the field). The NO-AUTOSEL style prevents the automatic selection from occurring. This is most commonly used on large multi-line entry fields. |
| READ-ONLY | Prevents the user from typing or editing data in the entry field. In all other respects, the entry field behaves normally. As of Version 8.1, read-only entry fields were changed to conform to standard Windows behavior in that the background color is always gray (regardless of the COBOL program's Color setting). If you need the ability to change the color of read-only entry fields, set the runtime configuration variable ECN_3699 to 0. |
| SECURE | This style prevents the characters that are entered into the field from being displayed on the screen. In place of each character, an * is displayed. This style is normally used with fields that take a password. This style is not available with MULTILINE entry fields. |
| SPINNER (Available only for Windows-based systems) |
This style attaches up and down arrow buttons to the right side of the entry field. When the user clicks on the up arrow,
your program receives a
MSG-SPIN-UP event. Clicking the down arrow generates a
MSG-SPIN-DOWN event. Your program would normally respond to these events by incrementing or decrementing the entry field's value. Refer
to the
AUTO-SPIN style for simplified handling.
Note: The
SPINNER style may be used only with a single-line entry field. It is ignored if you specify
MULTILINE, or if you have an entry field that has more than two lines. In addition, a technical limitation of Windows prevents spinners
from being used by entry fields with
RIGHT or
CENTER justification. This limitation stems from the fact that Windows requires a multiline entry field to use these styles (even
if the entry field shows only one line). Windows interprets the up and down arrows as vertical scrolling messages to this
multiline field.
Using the SPINNER with a 3-D entry field produces a look significantly different when you use the WIN32-3D configuration option. |
| AUTO-SPIN |
Similar to the
SPINNER style,
AUTO-SPIN provides a more simplified way of handling spinners by automatically updating the value of the entry field. When the user
clicks the up arrow, the control's value is incremented by one. The down arrow decrements the value by one. The entry field
uses the properties
MIN-VAL and
MAX-VAL to set the allowed range of values. When the user modifies the entry field's value, the
AUTO-SPIN style interprets the current value as an integer and sets the resulting value as an integer. This could have non-obvious
results if the field contains something other than an integer when the arrows are clicked. The
AUTO-SPIN is available only to entry fields that are left justified.
Entry fields with the AUTO-SPIN style still generate MSG-SPIN-UP and MSG-SPIN-DOWN events. This occurs before the value is changed. If your program sets EVENT-ACTION to EVENT-ACTION-FAIL in response to these events, AUTO-SPIN does not change the value of the entry field. This allows you to do additional range checking; you can also substitute a different value by setting the entry field's value directly in response to the event. Note: The behavior of an entry field control with the
SPINNER,
MIN-VAL, and
MAX-VAL properties is determined by its event procedure, which processes messages from the spinner arrows. If your COBOL program
does not use an event procedure, the behavior is as follows:
When the user enters a value that is outside the permitted range and then uses the spinner arrows to increase or decrease it, the value of the field is incremented or decremented as required. Then, if the value is below MINVAL, it is set equal to MIN-VAL, and if the value is above MAXVAL, it is set equal to MAX-VAL. |
| AUTO | This style causes the entry field to terminate as soon as it is filled by the user. A field is considered filled when the number of characters it contains equals its MAX-TEXT setting (see below). You may also use the words AUTOTERMINATE and AUTO-SKIP as synonyms for AUTO. This provides compatibility with text-mode COBOL. |
| NOTIFY-CHANGE | This style causes the entry field to generate NTF-CHANGED events. An NTF-CHANGED event is generated whenever the user changes the value of the entry field. Use this style when you need to track character-by-character changes to an entry field. Note that if you use this style with AUTO, the auto-termination status will take precedence over the NTF-CHANGED event (that is, when the user fills the field, the field will auto-terminate instead of generating an NTF-CHANGED event). |