FORMAT MODULE

This module is used to display a format on the screen, similar to a Windows screen. It can format the whole screen, and then modify sections of the screen as required. The format is specified by the programmer as an ascii string containing function codes and data, which is interpreted by the module as graphic and ascii displays.

Video mode 12H is a graphics mode, 640 pixels wide by 480 pixels deep. COBOL12 uses the graphics capability to display the various constructs which may be specified in this module, but the programmer is concerned only with the following screen format.

Character locations may be in any row, and the following row is automatically included. Thus, a screen can contain a maximum of thirty characters in a vertical column; if characters are specified in contiguous rows vertically, they will overlap. Note that a character may not start in row 60 because there is no following row to accommodate the full character.

Screen locations and extents are specified in the usual form rrcc. There is one function which specifies the current cursor location, where ll is a row from 01 to 60, and cc is a column from 01 to 80. In all other functions, rrcc specifies the size of a construct, starting at the current cursor location, where ll is the number of rows and cc is the number of columns.

The functions which specify an area that is bounded by some form of border, draw the border immediately outside the area. Such areas should therefore be separated from other constructs by at least one column and row if the borders are not to be overwritten. 

DISPLAY FORMAT dataname

Dataname refers to an ascii string in the Data Division containing format functions and text. Each function in the string is a single CAPITAL letter, preceded by the character | to identify it, and followed by any operands required. The first character in dataname must therefore be the character |. The operands are shown below as lower case letters.

A common operand is shown as 'rrcc' as described above. It must always be four numeric characters. This is the same format used in the Screen Module.

Another common operand is 'text...' which represents a text string to be displayed as part of this function. All other data in the string are assumed to be text which is to be displayed at the current cursor location. This means that if there are errors in the data string - wrong or misplaced functions, etc - the data will be assumed to be text and will be displayed on the screen. This makes it relatively easy to identify errors in the format strings.

Note two special characters.

_ The underline character.
This is used to underline the previous character in the text string. For example, 'S tring' is displayed as 'String. To display the underline character separately, precede it with a space.
| The function identifier.
If this character is to be displayed on the screen, it is included twice consecutively in the text string. For example, 'S||tring' displays as 'S|tring'.
These are special characters only in Format strings. They are normal characters in the Screen Module.

Demonstration Program
The program FMTDEMO.RUN is provided to demonstrate the various features available in the Format Module, and the source program is also available, as FMTDEMO.COB.

|Vtext...
Full Video screen window. The text is the title at row 02 column 02, for 76 characters. There is an exit button at row 02, column 78, 2 characters long. There are 26 free text lines within the window, for rows 04 to 54, columns 02 to 79. The comment field is at row 58, column 25, for 32 characters.
|Gtext...
General window. As for V above but with no comment field. There are 28 free text lines within the window, for rows 04 to 58.
|Crrcc
Set the Cursor location to rrcc.
|N
Reset cursor to the Next line - not the next row - and the same column. |Crrcc is not altered by most operations.
|Wrrcc[text...]
A Window from the current location with rrcc as its size, and cleared to light gray. If text is included, a title line is drawn on its first line with the text inside and an exit button in its last two columns. All lines and columns are available, except the first line if a title line is included. The exit button is in the last two columns of the title line.
|Lrrcc
List area from the current location with rrcc as its size, typically used as a drop- down menu. It is cleared to the background attribute, with a gray border.
|Frrcc
A box for a screen Field from the current location with rrcc as its size. It may extend over more than one line. It is cleared to white, with a field border.
|Prrcc
Plot a box or line from the current location with rrcc as its size, in dark gray and white. A vertical line is drawn if the same column is specified, a horizontal line if the same row is specified, otherwise it is a box.
 
Unlike other functions, plotted lines are actually in the specified rows and columns. This means that if a box is to be plotted around an area, the surrounding rows and columns must be specified, rather than those of the area itself, as is used for a List area or a Field box.
|Brrcc[text...]
Button from the current location with rrcc as its size, optionally containing text. It may be one or more lines in depth. The text for more than one line is in the form 
        |NLine 1|NLine 2 ....

Note that if text is inserted on a line immediately above a button which has already been defined, the top of the button will be lost. To avoid it, define the text before the button.

|Ic
Toolbar Icons where c is the one character icon code. These icons are similar to the toolbar icons used in Windows applications. They occupy three columns each with their borders within these columns, and they are two rows deep, with their borders outside these columns. They are similar to Buttons, except that buttons have their left and right borders outside the specified columns, Thus, icons may be defined in adjacent columns with no spaces, although a row must be left above and below them.
Unlike other functions, this function updates the current cursor location. This allows icons to be defined one after the other without respecifying the cursor, to form a toolbar row. The current foreground and background colours are used. The available icons are described below; their forms may be seen in the program FMTDEMO.COM. 
M  Mark (select)               F  Find
E  Erase (scissors)            H  Help
C  Copy                        Q  Query
I  Insert (paste)              X  X (delete)

U  Up arrow                    S  Save
D  Down arrow                  O  Output (print)
L  Left arrow                  V  View list
R  Right arrow                 W  Full window
T  Tick                        G  Get subform
B  Blank icon                  K  Keep record (enter)

A  First of a vertical series  a  First of a horizontal series
P  Prior of a vertical series  p  Prior of a horizontal series
N  Next of a vertical series   n  Next of a horizontal series
Z  Last of a vertical series   z  Last of a horizontal series
|IBx is a character icon where x represents an ascii character which is placed in the centre of the blank icon. A space must be left if a blank icon is required.
|D
Down (List) button at the current location, two columns wide and two rows high, normally at the end of an input field. If a |F field box is used, make it two columns longer and set the Down button within it.
|U
Up button, used with the down button for up and down selection.
|Mn[text...]
Message box, which is automatically displayed in a fixed position in rows 21 to 35, and columns 24 to 57. The title may be up to 28 characters, and the Exit button is at row 21, columns 56 and 57.
There are one, two or three buttons in the box at row 34, each 6 characters long, specified by the "n" following "M". 
n: 1 = one OK button, at column 38
   2 = Yes button at column 30 and a No button at column 46
   3 = As above, and a Cancel button at column 38.
The body contains up to four comment lines of 34 columns: 
        |N[Line 1]|N[Line 2]|N[Line 3]|N[Line 4]

Black text on the background attribute unless respecified. Lines may be omitted but the spacing is maintained by including '|N with no text. (The comment lines are at rows 25, 27, 29, 31.)

|Errcc
Erase a block from the current location with rrcc as its size, with the background attribute.
|Afb
Set the foreground and background attributes: 
           None (black)            Red
           Blue                    Tan (brown)
           White                   Green
           Light gray              Yellow (light)
           Dark gray               Cyan   (light)

Any of these colours may be used for foreground and background. These codes are also used in the SET - ATTRIBUTE statement of the Screen Module.

|Tf
Select Text font: 
     C  Courier type  ³ These two only cater for characters
     F  FixedSys type ³ 20H-7EH, normal keyboard characters.
     D  Dos standard    Full 256 character set.

Fonts C and F provide only for characters 20h to 7Eh, the normal keyboard characters.

|H
Halt until any key is pressed. This is used only as an aid in program testing.
|Srrcc
Save the area on the screen from the current location with rrcc as its size. This block may be restored later with |R. This is not required with |L or |M which save automatically.
|R
Restore the screen area last saved by |L |M or |S.
|Z
Zap - inhibit the next save operation by |L |M or |S. Subsequent save operations will proceed normally. If multiple |L functions are used in a group for instance, the save after the first |L must be inhibited if the first |L save is not to be lost.
|X
Exit. The mandatory last entry in a Format string. This approach allows |X to be inserted in an existing string during the program to change the extent of the data to be displayed.

COLOURS
Video mode 12H provides 16 colours, of which ten are used by COBOL12. Three of these colours have been altered, as follows. 

  Green    A darker shade, sutiable for text.
  Cyan     Very light, suitable as a background.
  Yellow   Very light, suitable as a background.
These changes are effective only within the current COBOL program.

TYPE FONTS
Three type fonts are available:
    Normal DOS font, whichever one is currently in use.
The two alternative fonts are:
    A font based on Windows Courier, a thinner type set.
    A font based on Windows FixedSys, a clean type set.
Both these sets are without serifs.

These alternative fonts contain only characters for Ascii 20h-7EH, the characters on the normal keyboard. There are two exceptions however, for the top left key on the normal keyboard:
    The ~ character displays a filled circle
    The ` character displays a tick.

SCREEN SAVING
The format routines save areas of the screen in a full 65k segment. This provides enough space for 1024 screen characters of the 2400 on the screen, or 42.7% of the total screen. (One screen character requires 64 bytes in the saved area.)
This should provide enough space for most requirements. For example, it can contains an area of 42 columns by 24 lines (1008 bytes) or 64 columns by 15 lines (960 bytes). As a further example, the message box requires a save area of only 360 bytes.
If an attempt is made to save a larger area, no error is noted and the end of the saved data overwrites the start of the saved data.
Only one save area is available. Subsequent saves overwrite the previous information.