# screen.input utility

The screen.input utility displays a
formatted screen and waits for input from a user. Multiple fields
can be entered by the user before validation. Type checking is done
by the subroutine, and the caller can provide a custom external routine
to perform additional controls.

## Syntax

```
call "dm,bp, screen.input"
```

## Input

The common variables defined in dm,bp,includes screen.inc must be set as follows:

| screen | Array of up to 512 options. If MultiValued, the options are presented in a multicolumnar format, with the input field beneath the headers. Data is entered and validated when the cursor is moved out of the field with the cursor movement commands (CTRL+N: Next; CTRL+B: Back; CTRL+J: Move left; CTRL+K: Move right. CTRL+X clears an input field). |
| --- | --- |
| screen.data | Array of data. If nonnull, the data displays and can be modified by the user. |
| screen.type | Array of type controls. Controls user input. If the corresponding screen element is MultiValued, the control applies to all MultiValues. |
| screen.help | Array of help messages. The message displays starting at the line specified by screen.msgline. A value mark is a line separator. If nonnull, the help displays starting at the line specified by screen.msgline when the cursor is moved to the corresponding option. |
| screen.size | Number of actual entries in the screen array. |
| screen.title | Title. Displayed underlined. |
| screen.x | Coordinates of the upper-left corner of the menu, starting at 0,0. |
| screen.y | Coordinates of the upper-left corner of the menu, starting at 0,0. |
| screen.active | Option number to set as active (highlighted). |
| screen.lastline | Last line available to display the menu. If there are more options than there are available lines, the menu displays in columnar format. If there are more columns than possible to display on the 80 columns screen, only some columns are displayed. |
| screen.width | Width of an option. The default is 35 characters. |
| screen.msgline | Line number where the help messages can be displayed. The message area extends to the end of the screen. |
| screen.notice | If nonnull, contains the name of an external subroutine that is called periodically. The main program can provide a polling routine to display user information or perform some periodic task. |
| screen.control | If nonnull, contains the name of an external subroutine that performs custom controls on user input. This routine must either be cataloged in the current account, or, better, be an explicit path, such as accounting,bp, check.input. |

## Output

The variables below are updated:

| screen.active | User selection: |
| --- | --- |
| Q | Quit or Esc. |
| Y | Validated. |
| screen.maxsize | Last line actually displayed on screen. In most cases, it is screen.y+screen.size. However, if there are too many options to fit in one column, this variable reflects the actual last line on screen. This is used by screen.erase. |

## Input Control

The *screen.type* array elements contain these codes:

| null | Optional field. Can be left empty. No control. |
| --- | --- |
| t | Required field. Any text. |
| x | Display only. The user is not permitted to modify the data. The cursor cannot be moved into the corresponding field. |
| l | Explicit list. The user can enter only one of an explicit list of elements. Each element is separated by a tilde. For example: l~yes~no~. Note that a trailing tilde is required. |
| y | Confirmation field. The user can only select [y{es}\|n{o}\|q{uit}]. If y is entered, the routine terminates. |
| n | Numeric field. Followed by the min and max legal values (inclusive), separated by a dash. For example: n0-1024. |
| number | Custom control code. This strictly positive number is passed as the first argument to the user provided external routine specified in screen.control. |

## Input Control Subroutine

The user can specify
an external subroutine in *screen.control* that is
called when the control code in a *screen.type* array
element is a number. This number is passed as the first argument of
the subroutine, along with other information. The subroutine can then
either validate the subroutine, and/or modify the user input. The
user must provide a subroutine with these arguments:

| Input | 1st arg | Control type number. |
| --- | --- | --- |
| 2nd arg | User input data. | |
| 3rd arg | Data field to leave (the one to control). | |
| 4th arg | Data field to enter (where the cursor now is). | |
| Output | 1st arg | Set to 0 if data is invalid, or 1 if ok. |
| 2nd arg | Validated data, if 1st arg=1. | |
| 3rd arg | Unchanged. | |
| 4th arg | Unchanged. | |
Note: The numeric control does not allow negative numbers
as part of the valid range.

## Example(s)

The example below displays a
screen like:

```
User : ...........
Order #1 Order #2
................ .................
include dm,bp,includes screen.inc
* Init the screen
* ---------------
call "dm,bp, screen.init"
* Clear the whole screen
* ----------------------
crt @(-1)
* Build the menu
* --------------
screen.x=0 ; screen.y=0 ;* Top left corner
screen(1)="User" ;* Option 1
screen(2)=""
screen(2)<1,-1>="Order #1 " ;* 1st column
screen(2)<1,-1>="Order #2 " ;* 2nd column
screen.type(1)=’t’ ;* Mandatory text
screen.type(2)=1 ;* User provided control
mat screen.data=’’ ;* Clear result
screen.help(1)="User name" ;* Help messages
screen.help(2)="Account number and val date"
screen.size=2 ;* Number of options
screen.active=1 ;* Option 1 is default
screen.msgline=23 ;* Help line
screen.control="account,bp, check.input"
* Display the screen and input data
* ---------------------------------
call "dm,bp, screen.input"
begin case
 case screen.active=’x’
 * Back to TCL
 stop
 case screen.active=’q’
 * User typed ’q’ or Esc
 ...
 case screen.active=’y’
 * OK. Validated
 ...
end case
```

## See also

- [BASIC screen utilities](https://d3codex.com/pickbasic-flashbasic/basic-screen-utilities/)
- [screen.display utility](https://d3codex.com/pickbasic-flashbasic/screen-display-utility/)
- [screen.erase utility](https://d3codex.com/pickbasic-flashbasic/screen-erase-utility/)
- [screen.init utility](https://d3codex.com/pickbasic-flashbasic/screen-init-utility/)

---
Source: https://d3codex.com/pickbasic-flashbasic/screen-input-utility/ - part of the D3Codex reference.