# screen.display utility

The screen.display utility displays
a screen and waits for a selection.

## Syntax

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

## Input

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

| screen | Array of up to 512 options. The options are displayed in a columnar format, prefixed by their number on 3 digits. The routine then waits for user input. The first 10 options can be selected by entering their number. Other options can be selected by typing the first letter of the option or by moving the cursor (CTRL+N: Next; CTRL+B: Back; CTRL+J: Move left; CTRL+K: Move right). |
| --- | --- |
| 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 can display on the 80 column screen, some columns do not display. |
| screen.width | Width of an option. The default is 35 characters. |
| screen.doselect | Boolean. If true, the user can select more then one option before validating by pressing the Spacebar. An asterisk displays in front of the selected options. The list of selected option numbers is returned in screen.select. |
| 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. |

## Output

These variables are then updated:

| screen.active | User selection: |
| --- | --- |
| n | Option n. |
| Q | Quit or Esc. |
| X | Exit to TCL. |
| screen.select | If screen.doselect is true, contains the list of option numbers selected by the user, separated by an attribute mark. |
| 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. |

## Example(s)

```
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)="Account"
screen.help(1)="User name" ;* Help messages
screen.help(2)="Account name"
screen.size=2 ;* Number of options
screen.active=1 ;* Option 1 is default
screen.msgline=23 ;* Help line
* Display the menu
* ----------------
call "dm,bp, screen.display"
begin case
 case screen.active=’x’
 * Back to TCL
 stop
 case screen.active=’q’
 * User typed ’q’ or Esc
 ...
 case 1
 * Selected an option from 1 to screen.size
 ...
end case
```

## See also

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

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