The application programming interface (API) described here allows programmers to build windowing interfaces on character-based terminals using a mnemonic space syntax.
Users around the world use different terminal types, so it is not efficient to use the control sequences of a particular model. Even ANSI-like terminals such as DEC's VT line are not universal. This API relies on a terminal capability database similar to that provided by termcap/terminfo in UNIX®.
Compatibility with existing windowing APIs
CharWin is based on mnemonic space syntax and is a superset of both DTM and Ipsum APIs. The syntax used by Extensao depends on a Z command (ZWINDOW) and is not directly source compatible with the current implementation. However, it is easily translated to the new syntax, since all the Extensao functionality is present in this implementation.
Feature activation by command only
By default, the character windows feature is disabled and the system has no overhead either in terms of memory usage or CPU cycles. Only when the programmer issues the appropriate command to enable this feature for the current terminal does the system allocate resources and traps I/O terminal operations. The feature may also be disabled at any time.
The following concepts are important for a clear understanding of the character windows API:
A rectangular area on the screen. It may have an optional border (with an optional caption) around it. A window must be opened and closed by command. When it is opened, the client area is cleared, the border is optionally drawn and the cursor is positioned at the upper left corner. READ and WRITE commands are restricted to the client area. When the window is closed, the screen characters that occupied its area before it was opened are restored.
The actual region inside a window where READs and WRITEs are confined. When the window is opened, the frame occupies the whole client area. By command (/WLIM), the user may restrict the frame to a smaller rectangle inside the window. It may then grow larger again, but not larger than the original client area.
The rectangle inside the window border. If the window has no border, the client area is the whole window.
An attribute is one of the status flags set for a character on the screen, controlling HIGHLIGHT, UNDERLINE, REVERSE, and BLINK. If the terminal is of an older type and does not keep a separate attribute byte for each character (if it stores attributes as invisible characters, for example) it cannot be used with this implementation.
A set of terminal characteristics, including the number of lines and columns and various control sequences. Control sequences perform functions like cursor positioning and erasing to the end of the line. The cursor position and the clear screen sequences are indispensable to this API.
The sequence in which windows are stacked on the screen. Initially this corresponds to the order in which the windows were opened. This can be changed by the /WUSE
command. A window may be above another one in z-order (meaning it is placed at a higher coordinate of a hypothetical z-axis coming out of the screen) but not overlap it visually.
The syntax makes it easy to port programs written in DTM, Ipsum MUMPS, and Extensao SuperMUMPS. It is based on the mnemonic space syntax, so the first command to be issued is USE. For example, the following command uses terminal device 0 and activates the %CHARWIN routine as the current mnemonic space:
This and future WRITEs / are translated to DOs to corresponding labels in this routine.
Users migrating from DTM may also consider using instead the mnemonic namespace %XDTM, which provides more compatibility with the DTM commands in MUMPS.DVF. For example, the following command uses terminal device 0 and activates %XDTM2 as the current mnemonic space:
The character windows API does not perform any input translation. If any keyboard mapping is desired, you must provide it using the NLS tables.
The same is true for the output side. No built-in translation is performed on the text written in windows, except for border characters. This feature is included as a convenience, because most users do not need to deal with the complexities of NLS to create nice looking windows. It can be disabled by setting the "Disable Border Mapping" boolean flag attribute. Then the user should provide the mapping from the internal border character codes (see Border Characters and Codes
) to the desired external representation using NLS.