Migrating from Graphical to Text-Based Systems

Note: This guide is intended for developers using Zim on Windows Platforms. It describes how to migrate a Zim for Windows application to run in a Zim text-based environment.

Backward Compatibility

Zim for Windows 2.0 designed to be backward-compatible with earlier Zim versions.

The data dictionary and development center environment are automatically upgraded (on request) when you first access any of the development tools (e.g., DC, Screen Painter) in Zim for Windows. Once the object dictionary and development center environments have been upgraded or you begin to use the new features in Zim for Windows, you should no longer run the application with previous versions of Zim.

Enhanced Development Center

This is a Common User Interface ( CUI) version of DC, and contains enhancements to the Development Center that were distributed with Zim for Windows. Common User Interface refers to Zim's ability to display the same form on both GUI and TUI environments; Zim achieves this by storing GUI coordinates separately from TUI coordinates.

The enhanced development center provides new features that enable you to create Common User Interfaces for your applications. In addition, new high-powered development tools, such as a CUI screen painter enable you to paint windows and menus as well as forms and displays.

The new services provided in the Development Center are

Limitations of Zim on Text-Based Environments

The create and compile commands operate identically in all environments. Code that runs under Windows can be run without any changes on text based environments with the following exceptions:

System commands need to be altered.

  1. Certain Windows-specific functions and commands do not have any effect on text-based environments; these are described below.
  2. The behavior or appearance of graphical widgets is not identical under text-based environments although they have a similar look and feel.
  3. The help command is implemented on text-based environments to read text or compressed text files instead of Windows Help Files.

Unsupported Zim Functions

The following Zim functions are ignored in text-based environments:

  1. $ PrinterSetup

  2. $ FilePrint

  3. $ ScreenPrint

  4. $ ScreenSave

Unsupported Zim Commands

The following Zim commands are ignored in text-based environments:

  1. PRINT

Unsupported or Changed Window Attributes

The following window attributes are either unsupported or changed in text-based environments:





Clipped Windows



Italic maps to blink.

Blended colors

RGB colors are approximated to Zim colors by default The use rgb colors configuration option permits them to be ignored and background (BC), foreground colors (FC) used instead.







Ctrl+R Key Combination

Refreshes screen (in case system command or output to backscreen has overwritten the screen).

Alt+F6 Key Combination

Cycles the user through all available windows during form input mode.


Supported only if window contains graphical forms; windows receiving document input (due to WINDOW SET INPUT ON) ignore mouse clicks.

Unsupported or Changed Widget Attributes

The following widget attributes are either unsupported or changed in text-based environments:






Does NOT SUPPORT non-standard size.


Ignores graphics other than line and rectangle.


Default pushbutton attribute is the surrounding angle brackets if the widgets width is 4 or more greater than its text width. Push buttons can display a shadowed border style on text-based environments.

Font/ Displaymode differences

Does NOT SUPPORT fonts and the strikeout and italic displaymodes.

Images, image pushbuttons and toggles

Displays a rectangular area containing the field value. If the widget contains a label or a FORM SET (LABEL .. is performed, the label appears centered in the field.

Unsupported Menu Attributes

The following menu attributes are unsupported:



Horizontal Separators


Predefined menuitems

Supported actions are exit, break, about and help. Other actions are ignored.

Converting GUI Applications

If an application is to run on both Windows and text-based environments, it can be built using the following methods:

When an existing window or form is brought into the Screen Painter and the Coordinate system is set to Text, its twip values are converted to appropriate row and column character cells. If the window or form is saved, only its row and column character cell values are written back. Zim for text-based systems uses the character cell values of a widget if they are present.

Once a window or form contains both character cell and twip values, the Screen Painter in text -based mode uses only the character cell values (and graphical mode uses only the twip values). Thus a form can contain two sets of unrelated positions and dimensions: those used in a Windows environment and those used on text-based environments.

Note: Sometimes, an existing window or form contains some character cell dimensions that are no longer in use. The row, col, wdth and hght fields can contain invalid values that cause the text-based version of Zim to display the widget inappropriately. When this is the case, the Screen Painter's coordinates menu provides an option to "Adapt Text from Graphical"; this option is equivalent to setting the row, col, wdth and hght fields to $null so that the Screen Painter's text mode can initialize them to appropriate values.

If a widget contains both an RGB and a standard Zim color number, the Zim for Windows uses the RGB value, while the text-based version uses the standard Zim color number.

The first time a graphical form is brought into the Screen Painter in text mode, the Painter attempts to choose appropriate character cell positions and dimensions. However, tailoring is usually required.

Experimenting with GUI Objects

The configuration issues described in the attached Release Notes permit a developer to turn off the default behavior of Zim. The Use Twip Dimensions Yes configuration option can be helpful when widgets contain inappropriate character cell values and a developer wants to get an idea of what a GUI application would look like when it is run in a text-based environment without any tailoring.

Using the Windows Cross Platform Development Environment

Development of a text-based application can still be performed under Windows. The Zim for Windows Screen Painter utilizes features not available in text-based Screen Painter, including split screens, image buttons, drag and drop, print, and a structure chart.

Whether the application runs on Windows or UNIX, the Windows development environment can target them all. Applications developed by the Zim Application Generator are designed for both graphical and text-based environments The Windows Screen Painter can design screens for both graphical and text-based environments by setting the coordinate system during the painting session.

Once an application is developed under Windows, it can be exported to other environments using DC's Import/Export Wizards. DC's Import/Export Utilities are found on the DC Tools pulldown. These wizards enable specialized import/exports used by multi-user development environments; however, component and entire application import/exports are less complex.

Screen Painters Text Coordinates Mode of Operation

There are several features unique to the Text Mode of Operation of the Screen Painter:

  1. Widgets are placed on the character grid.
  2. Dimensions and origins are displayed based on character cells.
  3. Grid menu options are grayed.
  4. Preferences menu options is grayed.
  5. Graphical mode is in effect when Text mode is toggled on (via the Coordinates pulldown).
  6. Fill characters are displayed in PAINT mode in data entry fields and the entry portion of combination boxes. The fill characters appear as dots and simulate Zim's default fill character; they do not simulate the fill character that actually exists for the widget. This dot-like fill character is visible only in PAINT mode.
  7. Toggle buttons (radio buttons and check boxes) are made two characters larger than they might appear to require to account for Text environments square brackets [ ]. Currently, blanks are appended after the text of the checkbox.
  8. Pushbuttons that are only one row high can use a shadowed borderstyle. The shadow takes up an extra row below the button and an extra column to the right of the button. Although the shadowed border attribute can be set in the Screen Painter, it is not visible in either PAINT or TEST mode.