Skip to main content
Previous sectionNext section

Introduction

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:

  • Terminal independence — 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 NLS features — Character set, $X/$Y action table, Input/Output translation tables.

  • Compatibility with existing output buffering scheme — Terminal output is accumulated in a buffer and only sent to the line at some predefined situations like the READ and HANG commands.

  • 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.

Definitions

The following concepts are important for a clear understanding of the character windows API:

window

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.

frame

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.

attribute

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.

z-order

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.

Syntax

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" 
Copy code to clipboard

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"
Copy code to clipboard

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.