This property limits the maximum number of characters that can be entered by the user into the field. This includes any characters generated by entering a return in a multi-line field. If the user attempts to enter more characters than allowed, the system's bell sounds. By default, this property is set to the field's SIZE setting (rounded up to the next whole integer) multiplied by the LINES setting (truncated to the next lower integer). For a single-line field, if you use the default MAX-TEXT and SIZE settings, the user will not be able to enter more characters than the field's VALUE data item can hold. The default MAX-TEXT setting is made when the control is created. After that, the setting changes only if you explicitly change it.
If MAX-TEXT is set to zero, the only limits placed on keyboard input are those imposed by the host system.
To make a single-line entry field that scrolls horizontally, you would typically make the SIZE smaller than the size of the VALUE data item, and then set MAX-TEXT to be the size of the VALUE data item. See below for an example.
Changes the active entry field background color that corresponds to the specified value. For a list of valid values, see the FOREGROUND-COLOR and BACKGROUND-COLOR Phrases topic.
For example, to create an entry field with a white background-color, black foreground-color (text), and a green active-background:
03 ENTRY-FIELD [...] BACKGROUND-COLOR is 7, FOREGROUND-COLOR IS 0, ACTIVE-BACKGROUND is GREEN.
This property identifies the entry field as an autofill entry field. The ID identifies the values that should be presented to the user as possible suggestions. Only previous entries from an entry field with this ID will be presented. If this property is not specified, then the other AUTOFILL properties are ignored.
Note that use of this property prevents use of NOTIFY-CHANGE, and your COBOL program will not receive any NTF-CHANGED events for any controls with this property set.
This property identifies the data store. The data store is where to look for suggestions, and where to store suggestions for future use. If all users have access to this file, then suggestions will be made from all users who have entered data into the entry field with this ID. If only a subset of users have access, then only those users will get and store suggestions for entry fields with this ID. If this file does not exist, it will be created on the first use. All configuration file translating will be done on this filename, including which file system to use (e.g. MSSQL), with a default file system of VISION. If no filename is given, a filename will be constructed from program-name and ID.
If you want this data file to be a database table (for use with Acu4GL), an XFD file can be created automatically, before the file is opened, by setting the configuration variable AUTOFILL-NEEDS-XFD TRUE; without this variable, the XFD is not created.
This is the maximum number of suggestions that a user will be presented with. The default value is 10.
This property provides a way to position the cursor within the entry field when the field is activated. You must use CURSOR in conjunction with NO-AUTOSEL; otherwise, the default selection logic will automatically reposition the cursor to the end of the field.
If you use the CURSOR property in a multi-line entry field, it will control the cursor position by counting the characters in the entry field without regard to lines. Significantly, internal control characters are also counted, which often makes it difficult to use the CURSOR property effectively in a multi-line entry field.
When CURSOR equals -1, all of the text in the entry field is selected and the cursor is positioned to the end of the selection.
Ordinarily, this property is not needed. However, one case in which you might want to use it is in combination with the NOTIFY-CHANGE style. As the user fills in the field, your program acts on each keystroke. If you change the value of the field in response, the system returns the cursor to column one of the field. Use CURSOR to reposition the cursor to the point where the user was typing, or to some other position in the field
This property controls and reports the cursor position in a multiline entry field. Inquiring on CURSOR-COL returns the column number (starting at 1) of the cursor. CURSOR-COL is often used interdependently with the CURSOR-ROW property to determine the exact position of the cursor with respect to the lines and columns of a multiline entry field. For that reason, the two properties are discussed together under the CURSOR-ROW paragraph (below).
This property controls and reports the cursor position in a multiline entry field. Inquiring on CURSOR-ROW returns the line number (starting at 1) of the cursor.
Setting CURSOR-ROW alone has no immediate effect. However, when you set CURSOR-COL, the values of CURSOR-ROW and CURSOR-COL will be taken together to place the cursor at the specified line and column. Thus you should always set CURSOR-ROW before CURSOR-COL if you want to place the cursor at a particular line and column.
If CURSOR-ROW specifies a value =0, the cursor will be placed at the beginning of the entry field. If CURSOR-ROW specifies a line number beyond the end of the text, the cursor will be placed at the end of the text. If CURSOR-ROW is valid and CURSOR-COL specifies a value =0, the cursor will be placed in column 1 of the specified line. If CURSOR-ROW is valid and CURSOR-COL specifies a value greater than the number of characters in the line, the cursor will be placed at the end of the text in that line.
When set to a non-zero value, this special property initiates a specific operation in the entry field. The meaningful values are as follows:
| ACTION-CUT | Cuts the current selection to the clipboard |
| ACTION-COPY | Copies the current selection to the clipboard |
| ACTION-PASTE | Pastes the clipboard contents into the entry field at the cursor location. If any text is selected, it is replaced by the paste operation. Text pasted in excess of the field's capacity is truncated |
| ACTION-DELETE | Deletes the current selection |
| ACTION-UNDO | Undoes the last change |
See the COPY library acugui.def for the value names. Actions are supported only under Windows; specifying these actions under other systems has no effect. Specifying a value other than one listed here has no effect.
See the SET statement for a technique to automate the generation of actions by other screen elements (such as push buttons or menu items).
This property sets the lower bound for the range of numeric values the user may enter into the entry field. The user may enter numeric values between MIN-VAL and MAX-VAL (inclusive). This property also sets the lower bound for the range of values used by the AUTO-SPIN style. The value of MIN-VAL must be an integer in the range of -2147483647 to 2147483647. If both MIN-VAL and MAX-VAL are set to the default (zero), no range checking is performed.
When the user enters a value that is out of range and shifts the input focus away from the text box of the entry field control (i.e, clicks the spinner or attempts to leave the control altogether), the entry field displays a message box informing the user of the error. The default error message reads Please enter a value between min-val and max-val. You can change this with the TEXT configuration variable.
This property sets the upper bound for the range of numeric values that the user may enter into the entry field. Along with MIN-VAL, this property is used for range validation; it is also used in conjunction with the AUTO-SPIN style. See MIN-VAL for additional information.
This property replaces the text currently selected in the control with the value assigned to SELECTION-TEXT. If no text is currently selected, the value is inserted at the current cursor location. When inquired, this property returns the text currently selected or spaces if nothing is selected. Note that you can determine the exact text that is selected by using the LENGTH option when inquiring on SELECTION-TEXT. The following example displays a message box with the currently selected text in quotes:
77 SEL-TEXT PIC X(100).
77 SEL-LEN PIC 9(3).
INQUIRE ENTRY-FIELD-1, SELECTION-TEXT IN SEL-TEXT,
LENGTH IN SEL-LEN
IF SEL-LEN = ZERO
DISPLAY MESSAGE BOX, "Nothing selected"
ELSE
DISPLAY MESSAGE BOX,
QUOTE, SEL-TEXT(1 : SEL-LEN), QUOTE
END-IF
If the selection spans multiple lines, any soft returns added internally by the control to manage word-wrapping are omitted from the returned value. Any hard returns (those inserted by the user via the <Enter> or <Return> key) are represented by the two-character sequence h"0D" h"0A" (carriage-return, line-feed).
This property enables you to specify a minimum number of digits right of the decimal point required for the automatic termination of the entry field. When used as a property, the number of decimals should be given like this:
AUTO-DECIMAL 2
This will auto-terminate the entry field once you have entered two decimals.
When AUTO-DECIMAL is used as a property, the phrase AUTO/AUTOTERMINATE is implied.