Common Properties

`TITLE`

Entry fields do not use titles.

`VALUE`

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

Note: Under Windows, you may encounter a peculiar behavior that looks like a bug but is actually a limitation of the Windows systems. If your entry field is formatted for numeric value and you paste non-numeric data into it from the clipboard, the runtime system has no way of checking and verifying that the data is of a correct format, and as a result, the entry field will be allowed to contain invalid data.

`MULTIPLE`

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.

`BORDER-COLOR`

Use BORDER-COLOR to specify a color for the bounding area of the entry field. Use color names as values.

`SIZE`

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.

An entry field is never allowed to be smaller than the size of the maximum width character. This ensures that at least one character of data is visible in the field.
If the field has the NUMERIC style, then its SIZE is multiplied by the standard font measure (i.e., numeric fields are normal).
If the field has the UPPER style, and the configuration variable EF-UPPER-WIDE is non-zero, then its SIZE is multiplied by the wide font measure (i.e., upper-case fields are wide).
If the field’s SIZE is less than or equal to the value of the configuration variable EF-WIDE-SIZE, then its SIZE is multiplied by the wide font measure (i.e., small fields are wide).
Otherwise, its SIZE is multiplied by the standard font measure (i.e., everything else is normal). The default setting of EF-UPPER-WIDE is 1 (on). The default setting of EF-WIDE-SIZE is 5.

Tip:

If your users will primarily enter upper-case characters in your application, you can set EF-WIDE-SIZEto a large value (for example 1000) to ensure that all of your non-numeric fields allow enough space for upper-case entry.
If you want to ensure that the standard measure is always applied, set both EF-WIDE-SIZE and EF-UPPER-WIDE to zero.
If your upper-case fields are still too narrow (because, for example, you tend to use upper-case W frequently), you can increase the entry field’s size further with the FONT-WIDE-SIZE-ADJUST configuration variable.

See Appendix H. Configuration VariablesFor a detailed description of the FONT-SIZE-ADJUST and FONT-WIDE-SIZE-ADJUST configuration variables.

COLOR

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, EXCLUDE-EVENT-LIST`

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.

`STYLES`

`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).