| screen.init | Index Level | SETTING |
| Syntax | call "dm,bp, screen.input" |
| Category | BASIC |
| Type | Subroutine |
| Description |
displays a formated 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 may provide a custom external routine to perform additional controls.
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 underneath the headers. Data is entered and validated when the cursor is moved out of the field by: CTRL-N: Next; CTRL-B: Back; CTRL-J: Move left; CTRL-K: Move right. CTRL-X erases an input field. screen.data Array of data. If non null, the data is displayed 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. See the section 'Input Control' below. screen.help Array of help messages. The message is displayed starting at the line specified by 'screen.msgline'. A value mark is a line separator. If non null, the help is displayed 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 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 is displayed 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 then extends up to the end of the screen. screen.notice If non null, contains the name of an external subroutine which is called periodically. The main program can provide a polling routine to display user information or perform some periodic task. screen.control If non null, contains the name of an external subroutine which performs custom controls on user input. This routine must either be cataloged in the current account, or, better, be an explicit path name, like 'accounting,bp, check.input'. See the section 'Input Control Subroutine' below Output : The following variables are then 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, but, if there are too many options to fit in one column, this variable will reflect the actual last line on screen. This is used by screen.erase. Input Control : The 'screen.type' array elements contains the following codes: <null> Optional field. May be left empty. No control. t Required field. Any text. x Display only. The user is not allowed 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 a trailing tilde is required. y Confirmation field. The user can only select [y{es}|n{o}|q{uit}]. If 'y{es}' is entered, the routine terminate. 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' which 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 the following arguments: Input: 1st arg: Control type number 2nd arg: User input data 3rd arg: Data field we are leaving (the one to control) 4th arg: Data field we are entering (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 |
| Options | |
| See Also | screen screen.init screen.display screen.erase |
| Example |
Example :
The following example 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 |
| Warnings | The numeric control does not allow negative numbers as part of the valid range. |
| Compatibility |
| screen.init | Index Level | SETTING |