CHARWIN: Character-based Windowing API
[Back] [Next]
Go to:

The application programming interface (API) described here allows programmers to build windowing interfaces on character-based terminals using a mnemonic space syntax.

This interface provides:
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.
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.
terminal capabilities
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:
   USE 0::"^%CHARWIN" 
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:
   USE 0::"^%XDTM2"
Input/Output Translation
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.