You are here: Development Standards > OSAS Standards > Coding Conventions > Screen Display

# Screen Display

Text Screen Prompts

Field prompts are short descriptors that identify the purpose of each value. They should be short and meaningful. Do not abbreviate unless absolutely necessary. Begin each word, except articles and prepositions of less than four characters, with a capital letter. The color for these data prompts in text mode is in the global strings "FTXT", "FTXT2" and "FTXT3" and should be displayed in background ('SB').

Field prompts are displayed in the 7500 section. Do not display prompts from anywhere else. Go to this section at the beginning of each program before any file opens. The section must include the command GOSUB BOX. Because data cannot be entered outside predefined positions, this section usually needs to be used only once per screen.

This routine resides in lines 7500–7699. Use the following lines of code as the starting point of the routine. Place additional code in lines 7525–7699.

`7500 REM 7500,5 "Display Screen"`
`7505 PROMPTS:`
`7510 IF GUI THEN GOTO GUI_PROMPTS`
`7515 GOSUB BOX`
`7520 PRINT STBL("FTXT"),'SB',`
`.`
`.`
`.`
`7699 RETURN`

The routine performs the following operations:

- if the user is in GUI mode, go to GUI_PROMPTS section to paint the screen
- call the Screen Box Paint routine (see below)
- change the color for field names
- set up background intensity
- display the field names

These are the conventions for constructing the code for this routine:

- Print lines default output to the screen. Do not use a channel number.
- End print lines with a comma.
- Position with direct cursor addressing, @(c,r). Use both row and column numbers. If you print at more than one position on the same line, the additional items can be printed using column positioning only.
- Keep variable assignment statements to a minimum.
- Do not change precision. You could unintentionally alter the precision of other data. PRO/5 correctly displays masked numeric values above the current precision.
- Print the fields on a line from left to right and from top to bottom. Do not jump around to various print positions, and do not use any mnemonics except direct cursor addressing.
  This routine should be called before any other operations in each program. The screen should be displayed before any file opens.

GUI Screen Prompts

For GUI Screens, all prompts are stored in resource files called BRC files. These files store all prompt information as individual controls.

GUI screens are displayed using the 17500 section. Do not load screens from anywhere else. You must branch to this section of code from the text-based PROMPTS section if the user is in GUI mode. Because there is no box to display, there is no need for a GUI equivalent to the text-based BOX section of code.

This routine resides in lines 17500-17699. Use the following lines of code as the starting point of the routine. Place additional code in lines 17510-17689 as needed.

`17500 REM 17500 "Display Screen"`
`17505 GUI_PROMPTS:`
`.`
`.`
`17690 PRINT (OSGUI.CHAN)’TITLE’(0,TITLE$),’SHOW’(0)`
`17699 RETURN`

This routine performs these operations:

- loads up the GUI screen
- displays the GUI menu bar
- enables, disables, hides, or shows certain controls where necessary
- sets the title and displays the entire screen

There are several different examples, each varying in style on how to load screens. The most common example is shown below:

`17500 REM 17500 "Display Screen"`
`17505 GUI_PROMPTS:`
`17510 LET OSGUI.SCRNID$=”ARPRR.BRC”,OSGUI.WIND_ID[1]=1,OSGUI.CONTEXT_POINTER=1`
`17515 LET MSG$=””; CALL “GENGURES.PUB”,FILE[ALL],OSGUI$,MSG$; IF`
`17515:CVS(MSG$,3)<>”” THEN LET X9$=MSG$,O7=1; GOSUB GENERROR; GOTO QUIT`
`17520 CALL “GENGUFNC.PUB::BUILD_MENU_STRINGS”,MENUHLP$,MENU1$`
`17525 LET MENU1$=MENU1$+MENUHLP$; PRINT (OSGUI.CHAN)’SETMENU’,MENU1$; LET`
`17525:MENU1$=””,MENUHLP$=””`
`17690 PRINT (OSGUI.CHAN)’TITLE’(0,TITLE$),’SHOW’(0)`
`17699 RETURN`

This section of code performs these tasks:

- Sets the BRC name to ARPRR.BRC, sets the window number to get from the resource file to 1, and sets the context pointer to 1 (because there is only one screen to load). The number in OSGUI.CONTEXT_POINTER must be the same as the element of the OSGUI.WIND_ID[ALL] array with which you are currently working.
- Calls GENGURES.PUB to retrieve the screen from the resource file.
- Calls GENGUFNC.PUB to build the standard menu sections for GUI screens. These strings contain the Commands, Edit, Modes, Other, and Help pull-down menu functions.
- Creates the menu on the current form.
- Sets the title of the current form and displays the form.

It is important to note that GENGURES.PUB retrieves the screen and displays it. Because all standard OSAS screens are set to be initially invisible, you will not see the screen until the ‘SHOW’ mnemonic is executed. Until then, you can manipulate the form without the user seeing any changes.

The following example of loading GUI screens handles screens that have a scroll region, or HLE (horizontal line entry) screens:

`17500 REM 17500 "Display Screen"`
`17510 GUI_PROMPTS:`
`17515 IF TASK$<>”” THEN PRINT (OSGUI.CHAN)’HIDE’(0),’CONTEXT’`
`17515:(OSGUI.CUR_CONTEXT[1]) ; LET OSGUI.CONTEXT_POINTER=1; RETURN`
`17520 LET OSGUI.SCRNID$=”ARCSH.BRC”,OSGUI.WIND_ID[1]=1,OSGUI.CONTEXT_POINTER=1`
`17525 LET MSG$=””; CALL “GENGURES.PUB”,FILE[ALL],OSGUI$,MSG$; IF`
`17525:CVS(MSG$,3)<>”” THEN LET X9$=MSG$,O7=1; GOSUB GENERROR; GOTO QUIT`
`17530 CALL “GENGUFNC.PUB::BUILD_MENU_STRINGS”,MENUHLP$,MENU1$`
`17535 CALl “GENGUFNC.PUB::BUILD_HLE_MENU”,MENUHLE$`
`17540 CALL “GENINFO.PUB::GET_GUI_INFO_MENU”,MENUINFO$,O2$`
`17545 LET MENU$=MENU1$+MENUHLE$+MENUINFO$+MENUHLP$; PRINT`
`17545:(OSGUI.CHAN)’SETMENU’,MENU$`
`17550 IF O2$(10,1)=”1” THEN PRINT (OSGUI.CHAN)’SHOW’(1000,4000,14000),`
`17550:’ENABLE’(1000,4000,14000)`
`17605 PRINT (OSGUI.CHAN)’TITLE’(0,TITLE$),’SHOW’(0)`
`17610 RETURN`

This section of code (which is executed in OSAS when you return to the Cash Receipts screen from the Edit Cash Receipts screen):

- Checks TASK$, and if it is null, hides the form and sets the current context.
- Sets the BRC name to ARCSH.BRC, sets the window number to get from the resource file to 1, and sets the context pointer to 1 (again, there is only one screen to load).
- Calls GENGURES.PUB to retrieve the screen from the resource file.
- Calls GENGUFNC.PUB to build both the standard menu sections for GUI screens and also the scroll commands menu for use on HLE screens only.
- Calls GENINFO.PUB to build the Information menu. In character mode this is the Shift-F2 menu.
- Creates the menu on the current form. Notice that the individual menu strings are not cleared so that they can be reused later in the code without having to call GENGUFNC.PUB or GENINFO.PUB again.
- Checks to see if batching is used and either hides or shows the batch ID prompt and entry fields, as necessary.
- Sets the title of the current form and displays the form.

There are other programs that display screens on top of other screens (for example, daily work entry chains), or that use a chain of screens shown one at a time (for example, customer or vendor maintenance). Here is an example of the code used in loading such screens:

`17500 REM 17500 "Display Screen"`
`17510 GUI_PROMPTS:`
`17520 IF ARENT_HEAD_CONTEXT THEN PRINT (OSGUI.CHAN)'CONTEXT'`
`17520:(OSGUI.CUR_CONTEXT[ARENT_HEAD_CONTEXT]); LET`
`17520:OSGUI.CONTEXT_POINTER=ARENT_HEAD_CONTEXT; GOTO 17555`
`17525 LET OSGUI.SCRNID$="ARENT.BRC"; FOR I=1 TO NUM(STBL("GUIWIND")); IF`
`17525:OSGUI.WIND_ID[I]=0 THEN LET OSGUI.WIND_ID[I]=2,OSGUI.BASE_CONTEXT[I]=`
`17525:-1,OSGUI.CONTEXT_POINTER=I,ARENT_HEAD_CONTEXT=I; EXITTO 17530 FI; NEXT I`
`17530 CALL "GENGURES.PUB",FILE[ALL],OSGUI$,MSG$; IF CVS(MSG$,3)<>"" THEN LET`
`17530:X9$=MSG$,O7=1; GOSUB GENERROR; GOTO QUIT`
`17535 LET OSGUI.BASE_CONTEXT[I]=OSGUI.BASE_CONTEXT[1]`
`17540 LET MENU$=MENU1$+MENUINFO$+MENUHLP$; PRINT (OSGUI.CHAN)'SETMENU',MENU$`
`17545 IF O2$(2,1)="1" THEN PRINT (OSGUI.CHAN)'SHOW'(14020),'ENABLE'(14020)`
`17550 IF O2$(10,1)="1" THEN PRINT (OSGUI.CHAN)'SHOW'(1000,4000,14000)`
`17555 PRINT (OSGUI.CHAN)'TITLE'(0," Header Information "),'SHOW'(0)`
`17560 RETURN`

This section of code performs these tasks:

- Checks ARENT_HEAD_CONTEXT and, if it is set, changes the context to that array element. This variable is set once the form is loaded (see line 17525). The routine also skips the next form load because it is already loaded.
- Sets the BRC name to ARENT.BRC and searches the OSGUI.WIND_ID[ALL] array for an unused element that can be used for the header screen. The unused element is then set to the window ID. The routine also sets OSGUI.BASE_CONTEXT[I] to -1 because there is no status bar on this form. Then the routine sets ARENT_HEAD_CONTEXT to the value of the loop counter, in this case, I.
- Calls GENGURES.PUB to load the form and then shows or hides controls based on option settings (Interface to Inventory and Batching in this example).

On forms that need to hide other forms before they are displayed, use the ‘HIDE’ mnemonic at the top of this section of code to hide other forms, then check the context (as in the example on line 17520) to switch to or load up the next screen.

Character Data Display

Data should be displayed only in the 7700 section. Keep manual field repainting to a minimum inside the main processing section of code. The color for the data fields is kept in the global strings "FTXT", "FTXT2" and "FTXT3" and should be displayed in foreground ('SF').

The 7700 section contains the print information for the data to be painted on the screen. Use this section to refresh the screen data when needed. Use temporary variables to display data sparingly. You should display the same variables that will be written to the file unless a translation is required.

This routine resides in lines 7700–7899. The following lines of code should be used as the starting point of the routine. Place additional code in lines 7710– 7889.

`7700 REM 7700 "Display Data"`
`7701 DATA:`
`7704 PRINT 'CF','SF',STBL("FTXT"),`
`.`
`.`
`.`
`7890 RETURN`

The routine performs the following operations:

- clears data displayed in foreground mode
- changes the color to foreground text color for the field names
- displays the data fields

These conventions are used in constructing the code for this routine:

- Print lines default output to the screen. Do not use a channel number.
- End print lines with a comma.
- Position with direct cursor addressing, @(c,r). Use direct row and column positioning unless you are printing multiple items on the same line.
- Keep variable assignment statements to a minimum.
- Do not change precision.

PRO/5 correctly displays masked numeric values regardless of the internal value. If you use a PRECISION statement and perform a calculation, you might inadvertently alter the precision of the data you are displaying. If you need to perform a multiplication or division operation on a variable before display, use the ROUND() function to round the calculation appropriately, regardless of the current precision setting. This does not affect the precision of other calculations in the program.

Precision setting is required only when you want to force internal stored data to have a specific decimal size. The displayed value is rounded off when printing with a mask, and it does not affect the internal value in memory. You need to use PRECISION only to format the output of a multiplication or division calculation.

- Print the fields on a line from left to right and top to bottom. Do not jump around to various print positions.
- Do not use mnemonics except direct cursor addressing.
- Use the FNNUM$(x,x$) function, rather than the x:x$ construct, to print numeric variables. This function traps mask errors automatically, and is present in any program in which the GENNUM routine has been included.
- For phone numbers, use the FNPHONE function to display the phone number properly. You must make sure your phone number fields are using 20 characters, with the mask coming from the Country file.

GUI Data Display

Data should be displayed only in the 17700 section. Keep manual field repainting to a minimum inside the main processing section of code.

The 17700 section contains the print information for the data to be displayed in the fields on the screen. Use this section to refresh the data as needed. Use temporary variables to display data sparingly. You should display the same variables that will be written to the file unless a translation is required.

This routine resides in lines 17700–17899. The lines of code below should be used as the starting point of the routine. Place additional code in lines 17710–17889.

`17700 REM 17700 "Display Data"`
`17705 GUI_DATA:`
`17710`
`.`
`.`
`.`
`17890 RETURN`

Because all data should be displayed on the screen, and printing any data to any INPUTE or INPUTN controls will clear those controls of the previous data, there is no need to clear all controls before printing data.

When you print data in an INPUTN control, you must use the STR() function on the variable, removing leading and trailing spaces, when you print to the control. The INPUTN control handles the mask formatting automatically.

The rules of precision are the same as in character screens. However, where the FNNUM function is used on character screens for fields in which the numeric mask can vary, you must use the FNGUINUM function for GUI controls. The FNGUINUM function sets the proper mask for numeric GUI controls.

Use the FNGUIPHONEMASK function to display phone numbers on graphical screens. This function sets the proper mask for phone number controls.

Other functions are provided to assist in displaying data to screens, including

- FNCHECK, which selects or clears a GUI check box
- FNCHECKBOX_RADIO, which selects or clears radio buttons
- FNLIST, which selects a value from a list button control

Display Character Boxes and Lines

Each text screen in OSAS is logically boxed to break up the fields on the screen in a logical order. The general boxing routine is always coded within line numbers 7900–7999. See the definition of this routine below.

`7900 REM 7900 "Display Boxes"`
`7901 BOX:`
`7905 PRINT 'BACKGR',STBL("FBKG"),STBL("FBX"),'DEFAULT','CS','SB',`
`7910 PRINT 'BOX'(0,0,79,24),'GS',`
`7920 PRINT @(0,21),"6",'BOX'(1,21,77,0),@(78,21),"7",`
`7930 PRINT @(xpos,ypos),"6",'BOX'(xpos+1,ypos,xlen,0),@(xlen+1,ypos),"7",`
`7940 PRINT @(xpos,ypos),"9",'BOX'(xpos,ypos+1,0,ylen),@(xpos,ypos+ylen+1),"8",`
`7940:'GE'`
`7985 PRINT 'SB',STBL("FTTL"),@(INT((79-LEN(TITLE$))/2),0),TITLE$,`
`7995 RETURN`

7905 | Clears the screen, sets background, and sets up the color for the box.
7910 | Prints the surrounding box and turns graphics on for the lines that follow.
7920 | Prints the line on line 21 that commonly appears on input screens.
7930 | Prints a horizontal line with left and right tees. This line is duplicated for each horizontal line.
| xpos x-coordinate of the starting position of the line-where a line intersects a vertical line
| ypos y-coordinate of the line
| xlen length of the line without the tees
7940 | Prints a vertical line with top and bottom tees. This line is duplicated for each vertical line.
| xpos x-coordinate of the line
| ypos y-coordinate of the starting position of the line-where a line intersects a horizontal line
| xlen length of the line without the tees
7985 | Prints the title of the program

The last line must include the 'GE' mnemonic to turn off graphics (see line 7940 above). Put commas at the end of each line to hold the cursor and speed up printing.

Below is a table of common line symbols and the corresponding characters to print in graphics mode to produce them. Add lines to the box as desired for your task.