Migrating from Zim 4.x to Zim 7.x

This guide is tailored for developers of Zim 4.x applications who intend to migrate their databases and applications from Zim 4.x to Zim 7.x, as an intermediate step in the migration path to Zim 8.

This document is divided into the following sections:


Compatibility of Zim 7.x and Zim 8 with Zim 4.x A description of the compatibility between Zim 7.x with previous versions of Zim (Zim 4.x, 5.x, 6.x and Aria Zim 2.x)
Changes to the Zim Language A list of new objects, keywords, commands, syntax, events, and properties introduced since Zim 4.x
Other Issues and Changes A discussion of changes in the Zim Application Framework and the new application development tools in Zim 7.x
Converting Text Forms to Graphical Form Information on the process of migrating user interfaces from text-based (TUI) to graphical (GUI)
End-User Preferences under Microsoft Windows A discussion of the effects of End-User preferences on the functioning of Zim 7.x applications on Microsoft Windows.


Compatibility of Zim 7.x with Zim 4.x

Backward Compatibility

Zim 7.x is designed to be backward compatible with Zim 4.x applications:


However, existing Object Dictionaries in Zim 4.x applications must be upgraded before new object classes and features of Zim 7.x can be used:


Zim 4.x forms can still be edited with the Zim 4.x Screen Painter as long as they are still text-based:


Since Zim 7.x extends the Object Dictionary, make a backup copy of any Zim 4.x application before using it with Zim 7.x.

Upgrading Zim 4.x Object Dictionaries

Zim 4.x Object Dictionaries must be upgraded to Zim 7.x before any of new Zim 7.x features and tools can be used.  The steps to upgrade your Zim 4.x Object Dictionary are:

1. Back up your Zim 4.x application and database.

As the Development Center initializes, the Object Dictionary Update and/or Development Center Update Procedures detect a Zim 4.x Object Dictionary.

2. If your Operating system is Windows, create a shortcut for the Zim application and start Zim 7.x.

Under other operating systems (Unix and Linux), invoke Zim single user as usual from the operating system command prompt.

3. At the Zim command prompt, enter DC or, under Windows, you can also select Actions/Start DC from the Zim 7 main menu.

4. The Object Dictionary Update and/or Development Center Update Procedures prompt you to upgrade the Object Dictionary to Zim 7 by asking


(Windows)                                             (Unix with Set Color off)


                      (Unix with Set Color on)


Select Yes (press Tab to move the focus) and press Enter or click on the Yes button (Windows only) to start the upgrade procedure.

The Upgrade procedure adds fields to existing dictionary tables, adds new dictionary tables, adds new constants, and installs new file system directories and files into the database directory.

Note: After extending the Object Dictionary, do not use previous versions of Zim with the this database.

5. When the dictionary upgrade has successfully completed you will be prompted to upgrade your Development Center (DC) by asking


                         (Windows)                                                         (Unix)


Again, select Yes to continue the upgrade.

Zim 7 Development Center activates the Zim Object Manager (ZOM) and uses it for all object maintenance. We strongly recommend to always using the ZOM services (like zomrecreate) to maintain the database objects when using the Zim prompt.

After the upgrade is completed, you will be asked to update the object description within ZOM.



This is an optional step since you can do it later using the ZOM service ZOMTouch. We strongly recommend you to refresh the descriptions since ZOM is the core of DC hence this process is crucial to get correct result using DC. It is also very important to have this description up-to-date. The touch process may take few minutes in Zim version 7.

If you choose ”Yes” all existing objects in the Object Dictionary are registered with ZOM so that you can take advantage of the object management services it provides.

When the DC upgrade has successfully completed, the main DC window appears. (Note: DC does not run unless the Object Dictionary and DC are upgraded.)

The upgrade is complete. Applications operate as before, but the object dictionary has been upgraded to Zim 7. Read the rest of this guide for suggestions on migrating applications to GUI (Graphical User Interface) applications. Other new concepts and detail differences in the 4GL and the behavior of TUI (Text User Interface) applications from GUI (Graphical User Interface) applications are also presented.

The next time DC is accessed, the Object Dictionary Update and/or Development Center Update Procedures should not be encountered. If they are, a step in the upgrade procedure has failed.  Contact ZIM Technologies Technical Support for assistance.

Changes in Terminology

One of the changes brought about by Zim for Windows is a change in terminology. The concepts in most cases are identical, but some terms have changed to conform to the norm for GUI environments. The following table shows the key terminology differences between Zim for Windows and Zim 4.x.


Zim 7.x Zim 4.x Comments
object dictionary data dictionary The data dictionary is now referred to by the more accurate name, "object dictionary", since it contains the definitions of all application objects and not just database objects.
focus cursor There are user interface objects, such as the push button, in Zim 5.x with which the user can interact but they do not use a text cursor. Focus indicates where the next user interaction  takes place.
event transmit The concept of transmission has been replaced by the more general concept of events. The familiar Transmit, Enter-Transmit, and Transmit-Always events from the past are now known as LostFocusModified, GotFocus, and LostFocus events.
accelerator key exit key Exit keys are now called "accelerator" keys. Accelerator is also used to describe key sequences that the user can use to quickly move the focus to an object. The notion of a Transmit key is not promoted in Zim 5.x. (See "Validating Input" in the Changes to the Zim 4GL.)
availability protection The protection status of an object is now described in terms of availability. An object is available (i.e., unprotected), protected, guarded, or unavailable (i.e., protected and grayed).

Changes to the Zim Language

The next few sections highlight the language differences between versions 4.x and Zim for Windows.

New Objects

The following lists the names of system-defined objects new in Zim for Windows:


Documents: _zimprof clipboard
Object Dictionary EntitySets: Menus DefinitionsLog
Role: MenuItem  
Relationship: MenuFormFields  


New Object Dictionary Field Names:

HMargin MenuName MenuNum MenuType RemoteName RemoteOwnerName
UniqueMenuDirName Vmargin WdgAlwaysOnTop WdgAutoDrop WdgAutoSelect WdgAutoSize
WdgAvailable WdgBCBlue WdgBCGreen WdgBCRed WdgBackground WdgBorderStyle
WdgCaption WdgClass WdgClick WdgClosed WdgCol WdgDblClick
WdgDragIcon WdgDragMode WdgDropTarget WdgEditOptions WdgFCBlue WdgFCGreen
WdgFCRed WdgFont WdgFontSize WdgGotFocus WdgHMargin WdgHScrolled
WdgHeading WdgHght WdgIcon WdgId WdgInputMask WdgIsDefault
WdgItems WdgLabel WdgLabelPosition WdgLargeIncrement WdgLostFocus WdgMaxValue
WdgMaximize WdgMaximized WdgMinValue WdgMinimize WdgMinimized WdgModal
WdgModified WdgMove WdgMoved WdgMultiLine WdgNullImage WdgNullValue
WdgNumVisibleCols WdgNumVisibleLines WdgOffImage WdgOffValue WdgOnImage WdgOnValue
WdgPSWdth WdgParId WdgPointerStyle WdgResize WdgOrientation WdgPSCol
WdgPSHght WdgPSRow WdgResized WdgRestored WdgRow WdgScrollBars
WdgShadowSize WdgSmallIncrement WdgStyle WdgSubClass WdgSysMenu WdgTabStop
WdgTag WdgVMargin WdgVScrolled WdgWdth WdgZOrder WinOwnerDirName
WinOwnerName WinType        


New Keywords

The following is a list of new keywords in Zim for Windows.


$ansitodos $browsefile $ddefunction $deadlockreason $dirpath $dostoansi
$filebrowse $fileprint $getproperty $iswinopen $messagebox $ODVersion
$paintfunction $printersetup $screenprint $screensave $setproperty $sqlpath
$squeeze ANSI accelerator autoselect available bold
CButtonHighlight CButtonShadow CButtonText CCaptionText CDEFAULTBUTTON1 CDEFAULTBUTTON2
CHighlightText CInactivCaptionTxt CInactiveBorder CInactiveCaption CINFOMSG CINHERITED
CLASS click closed CMenuColor CMenuTextColor CNOREADONLYFILES
CScrollBarColor CWARNINGMSG CWindowBackground CWindowColor CWindowFrame CWindowText
DefaultType DefinitionsLog DOS doubleclick ENDCLASS ENDMETHOD
eolntranslate fillcolor focus gotFocus help italic
label LightGray LogDefinitions lostFocus lostFocusModified menu
METHOD modal modified nolabel pencolor print
RemName RemOwner strikeOut tabindex TableType textDelimiter
unavailable visible        


New Commands

The following lists the new 4GL commands and sub-commands in Zim for Windows:


PRINT <window-name or doc-name> SET <ent_or_rel> TABLETYPE <server name>
SET <ent_or_rel> REMOWNER <owner name> SET <ent_or_rel> REMNAME <remote name>
SET <fieldname> FIELDLISTWIDTH <number> SET <fieldname> HEADING <char string>
SET <fieldname> MASKFIELD <char string> SET <fieldname> REMNAME <char string>
SET <fieldname> REQUIRED on|off SET <fieldname> SELECTIVITY <eqsel><bwsel><lgsel>
WINDOW OPEN <name> IN <expr> WINDOW OPEN name AT <posn>\  % TOP, BOTTOM, CENTER, etc.
WINDOW SCROLL <name> <direction> WINDOW SCROLL <name> TO <row> <col>
WINDOW SET ([NOT] LOSTFOCUS) WINDOW SIZE <name> TO <height> <width>


Revised Zim 4.x Syntax

For compatibility with 4.x applications, the Zim 4.x language constructs are supported under Zim for Windows. However, to evolve the 4GL to be more self-consistent, and to introduce new syntax in a consistent fashion, a number of commands and keywords have been superseded; these are still supported in applications, but do not appear in the documentation and on-line help.

The following table lists 4.x command syntax that has been superseded and the Zim for Windows equivalent.


Zim 4.x Syntax Equivalent Zim for Windows Syntax
FORM SELECT <form-name> FORM OPEN <form-name>
FORM SET SCROLL <key-assignments> WINDOW SET SCROLL <key-assignments>

System Variable Aggregation

In Zim 4.x, the FORM INPUT command returned user interface information to the application program in a number in system-defined variables. In Zim for Windows, this information is delivered in system-defined structures that collect the old system variables into logical groups and are much simpler to deal with from a programmer's point of view. The obsolete system variables still exist and are still set, but their use is discouraged.

The obsolete system variables from Zim 4.1 and Zim 4.2 are


$CurrentWindow $CurrentWindowNum $Direction $FieldNum $FormChanged $FormExit $FormNum
$MouseClick $ReqError $ReqFieldNum $ReqFormNum $ReqSubscript $ScrollingKey $Subscript
$TransmitKey $WindowCol $WindowHeight $WindowRow $WindowState $WindowWidth  


New Structures: Field Mapping from Zim for Windows to Zim 4.x System Variable Names


The Event structure in Zim for Windows contains fields that describe the last user interface event (e.g., the event that cause the last FORM INPUT command to complete). The fields of the Event structure are outlined below.

FieldName 4.x System Variable Name
Event.EventType similar to $FormExit (4.0)
Event.EventName $TransmitKey (4.0)
Event.EventTag $EventTag (4.5 beta)
Event.WindowTag $WindowTag (4.5 beta)
Event.FormTag $FormTag (4.5 beta)
Event.FieldTag $FieldTag (4.5 beta)
Event.MenuTag $MenuTag (4.5 beta)
Event.MenuItemTag $MenuItemTag (4.5 beta)
Event.AcceleratorKey [some overlap with $FormExit (4.0)]
Event.ScrollingKey $ScrollingKey (4.0)
Event.KeyPressed $KeyPressed (4.5 beta)
Event.ShiftKey $ShiftKey (4.5 beta)
Event.CtrlKey $CtrlKey (4.5 beta)
Event.AltKey $AltKey (4.5 beta)
Event.MouseClick $MouseClick (4.1)


The ThisForm structure describes the currently open form (or display) in the current window. It contains information related to the focus field (i.e., where the cursor is), required field checking, and invalid form fields, if any. ThisForm represents the current window; if the current window changes, the contents of ThisForm change as well. The fields of the ThisForm structure are listed below.


FieldName 4.x System Variable Name
ThisForm.DisplayTag $DisplayTag (4.5 beta)
ThisForm.FormTag $FormTag (4.5 beta)
ThisForm.FieldTag $FieldTag (4.5 beta)
ThisForm.FormNum $FormNum (4.0)
ThisForm.FFFieldNum $FieldNum (4.0)
ThisForm.Subscript $Subscript (4.0)
ThisForm.FormChanged $FormChanged (4.0)
ThisForm.FieldChanged $FieldChanged (4.5 beta)
ThisForm.ReqError $ReqError (4.0)
ThisForm.ReqTag $ReqTag (4.5 beta)
ThisForm.ReqFormNum $ReqFormNum (4.0)
ThisForm.ReqFieldNum $ReqFieldNum (4.0)
ThisForm.ReqSubscript $ReqSubscript (4.0)
ThisForm.ValError $ValError (4.5 beta)
ThisForm.ValTag $ValTag (4.5 beta)
ThisForm.ValFormNum $ValFormNum (4.5 beta)
ThisForm.ValFieldNum $ValFieldNum (4.5 beta)
ThisForm.ValSubscript $ValSubscript (4.5 beta)


The ThisWindow structure describes the currently open window. It contains information related to the window and the last user interface event to occur in the window. ThisWindow always represents the current window; if the current window changes, the contents of ThisWindow change as well. The fields of the ThisWindow structure are listed below.


FieldName 4.x System Variable Name
ThisWindow.WindowName $CurrentWindow (4.0)
ThisWindow.WindowTag $WindowTag (4.5 beta)
ThisWindow.WindowNum $CurrentWindowNum (4.1)
ThisWindow.WindowState $WindowState (4.5 beta)
ThisWindow.WindowRow $WindowRow (4.0)
ThisWindow.WindowCol $WindowCol (4.0)
ThisWindow.WindowHeight $WindowHeight (4.0)
ThisWindow.WindowWidth $WindowWidth (4.0)
ThisWindow.EventType similar to $FormExit (4.0)
ThisWindow.EventName some overlap with $TransmitKey (4.0)
ThisWindow.EventTag $EventTag (4.5 beta)
ThisWindow.AcceleratorKey some overlap with $FormExit (4.0)
ThisWindow.ScrollingKey $ScrollingKey (4.0)
ThisWindow.KeyPressed $KeyPressed (4.5 beta)
ThisWindow.ShiftKey $ShiftKey (4.5 beta)
ThisWindow.CtrlKey $CtrlKey (4.5 beta)
ThisWindow.AltKey $AltKey (4.5 beta)
ThisWindow.MouseClick $MouseClick (4.1)


The ThisMenu event structure is new. The ThisMenu event contains information about the currently open menu in the current window.

Menu Commands

Zim for Windows introduces menus as an object class. Zim 4.x applications could create menus by programming forms; typically menus were created with a code generator. The new menus enable several 4.x forms to be collapsed to a single object. This object can then be manipulated with new 4GL commands that are polymorphic to their respective FORM commands.

There are nine new menu commands whose syntax exactly matches the equivalent FORM command, but with the word "FORM" replaced with "MENU":

MENU DEFINE <menu-name>
MENU OPEN <name>
MENU SET ( <attributes> ... ) <name>


For the most-part, these menu commands behave exactly as their FORM counterparts do, although the MENU SET ( ... ) command accepts a more restricted set of attributes.

For example, the code below opens a window, places a menu in it, gets user input, and then closes the window:

MENU OPEN mMainWindow
LIST ThisMenu % list menu event structure

Using Menus in Conjunction with Forms

Zim for Windows menus can coexist with a form in a window. There can only be one open menu in a given window at one time, and one open form/display at one time. The user can interact with both the form/display and menu, moving freely from one to another during input requests.

For example, the following code opens a form and menu in a window, gets user input, and then determines where the event occurred:

   WHEN Event.EventType = "MenuItem"
      % user has selected item off of menu
   WHEN Event.EventType = "FormField"
      % user has interacted with form
   WHEN Event.EventType = "Window"
      % user has tried to close window
   WHEN ....
      % other cases, such as accelerator keys, etc.

The code above first makes both a form and a menu visible in the window using the FORM DISPLAY and MENU DISPLAY commands. If, for example, the MENU DISPLAY command had been omitted, the menu bar would not be visible to the end-user. The FORM INPUT command gives control of the user interface to the end user. At this point, the end-user can interact with either the form or the menu (or any other objects in other available windows). The focus is in the form if that form contains any available or guarded fields. A MENU INPUT command achieves the same thing.

When the end-user triggers some event that completes FORM INPUT, the program then determines what action to take, if any, based on that event. For example, an event might be selecting a menu item, modifying a form field, pressing an accelerator key, and so on.

To recap, a menu is very similar to a form from a language perspective. Menus can replace Zim 4.x menus that were implemented as several distinct forms. A menu can be opened concurrently with a form, and manipulated as a distinct object in the code. The next subsections highlight a few more properties of Zim menu objects.

Additional Properties of Menus over 4.x Menus

In addition to "typical" choose-one-from-a-list menu items, Zim supports many different types of menu items:

These features enable you to develop application menus with a rich functionality similar to other GUI applications.

Using Tags to Identify Objects

In Zim 4.x applications, user interface objects were often identified by their identification numbers: FormNum, FieldNum and Subscript. In Zim for Windows, each user interface object also has an associated object tag. An object tag is a literal identifier for the object which defaults to the object's name. You can use object tags to give meaningful identifiers to your objects.

Tags can also be used to indicate a default action for an object. For example, you might assign the literal "Save" as the tag for a menu item labeled "Save" and also for a push button labeled "OK". A program can then be written as

form input
when Event.EventTag = "Save"
   % Perform Save action.
when Event.EventTag = "Cancel"
   % Perform Cancel action.
when ...

Non-Modal User Interfaces

Zim for Windows enables you to more easily create non-modal user interfaces in which the end-user is free to move among the application windows appearing on the screen.

In Zim 4.x, non-modal interfaces were typically created by providing "hot keys" (e.g., function keys, mouse buttons) that the user used to initiate a focus switch from the current window to some other window. In Zim for Windows, the user has access to all the user interface objects available on the screen and can move among them by simply clicking on the desired object or by using navigation keys.

Access to objects appearing on the screen is controlled by two attributes: modality and availability. Assume a particular object has the focus. If the object is modal, the user can only interact with that object (and any objects it contains). If the object is non-modal, the user can interact with any other available object as well. Only window objects have the modality attribute.

Using the modality and availability attributes, you can control which objects the user can interact with. In addition, you can detect a switch in focus from one object to another (i.e., GotFocus, LostFocus and LostFocusModified events) and program any special responses.

Another feature designed to support non-modal applications is the new context structures: ThisForm, ThisMenu and ThisWindow. Unlike the system variables of the past (ex. $FormNum, $Transmitkey), the information in these structures always represents the state of the current window. Therefore, as the focus moves from one window to the next, the information in these structures is automatically changed to represent the user interface objects in the current window.

For example, if Form1 is open in Window1 and Window1 is the current window, then ThisForm.ReqError indicates if there is a field in Form1 that violates the "required value" check. If another window becomes current, ThisForm.ReqError reflects the state of the form open in that window. Later, if Window1 becomes current again, ThisForm.ReqError once again reflects the state of Form1.

Validating Input

In a Zim for Windows application, a "save" action can be initiated in many ways, such as a push button, menu item, function key and tool bar button. Some of these mechanisms (ex. tool bars) involve objects outside of the window containing the data to save (assuming a non-modal interface). In these cases, the program can no longer rely on automatic detection of missing required fields and (possibly) invalid data. Instead, the program must also include an explicit check for these conditions; i.e., check ThisForm.ReqError and ThisForm.ValError.

This seemingly backward step in the development of user interfaces is imposed mainly by the onset of non-modal interfaces. In the past, you could count on the required property being enforced by working with a single window at a time and using "transmit" keys. (Transmit keys are supported in Zim for Windows but not documented.) Since there are usually other means of causing a "save" action, the program must take steps to ensure the required value requirement has been satisfied (by checking if ThisForm.ReqError=$true).

The situation is similar in validating data values if you implement a non-modal interface. Validation rules are enforced automatically when the user moves the focus from one field to another in a window, but not if the focus is moved from a field in one window to another window. Therefore, in a non-modal interface, the program must take steps to ensure forms contain valid data (by checking if ThisForm.ValError=$true).

For example, suppose a user types invalid data into a form field and then clicks on another window, causing the current window to be "suspended" and the focus to move to the target window. Later the user requests the data in the original form be saved without ever returning to that window (perhaps by attempting to exit the application or by pressing a button on a tool bar). At this point, the original form still contains the invalid data.

Other Issues and Changes

Windows Cross-Platform Development Environment

Unix Zim 7 applications can be developed using the Zim for Windows' Cross Platform Development Environment on Windows platforms.

The Windows development environment can target deployment environments on Windows or Unix. Applications developed by the Zim Application Generator are designed for both graphical and text-based environments As well, 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 Microsoft Windows, it can be exported to other Zim 7 environments using DC's Import/Export Wizards. DC's Import/Export Utilities are found on the DC/ Tools menu. These wizards enable very specialized import/exports used by multi-user development environments and for simple import/exports of components or entire applications.

Application Framework

Zim for Windows provides an Application Framework, a set of EntitySets and programs, that facilitate application development. The Framework encourages the development of applications according to a new "application model" that includes full non-modal as well as modal interaction. Both user-driven and program applications are easy to develop.

The main components of the Application Framework are:

Enhanced Development Center

The Zim for Windows Development Center (DC) is an application editor and has a GUI user interface. Complete applications can be designed, tested, and modified within DC. The application generator include single table editing code as well as header/detail windows. The system is completely open-ended so that users can add their own compliant generators into the system. Generated applications make extensive use of Application Framework facilities and large parts of the DC have been "generated" themselves. DC also provides access to the Zim Object Manager (ZOM) services using a graphical interface.

To access the Development Center, type 'DC' at the command prompt or from the Zim main menu select Actions/Start DC. (Note: DC starts automatically when you start Zim if you do not have a ZIMPROF program.). On-line help is provided.

Graphical Screen Painter

The Zim 4.x screen painter has been replaced with a graphical screen painter. During the initial stages of converting text applications to GUI, you work with the painter most of the time.

Accessing the Painter

The screen painter is accessed through DC (or from the command prompt using one of the following four commands: FORM DEFINE, DISPLAY DEFINE, MENU DEFINE, or WINDOW DEFINE).

The painter enables you to create many objects simultaneously. For example, in painting a display, you can create a display, several forms, a window, and in MS Windows environments, a menu as well. The Painter "remembers" the associations among these objects so that the next time you paint that display object, for example, the associated menu and window automatically appear.

Converting Text Forms to Graphical Forms

The screen painter can read the definition of 4.x "text" forms, displays and 4.x windows; however, when a 4.x form or display is detected the Screen Painter will ask if you want to convert it to a graphical form.



If you choose ”Yes”, the form will be converted and the Screen Painter will continue. The conversion is permanent, so if you are unsure about the process, keep a copy of your form before the conversion. You can use the Export Wizard to save all or some of your forms and displays or even use the ZOMCopy myform > myformBK to create a copy of the form. Even after converted, the form can be reverted to text mode using the GUI to TUI converter tool in DC.

The 4.x form is initially displayed by the painter inside a default "painting" window. The position and size of the form fields are determined by their row/column and height/width attributes, and also, in MS Windows environments only, by their (new) font and border attributes. Some of the fields could be assigned borders that overlap slightly. You can turn off the border by selecting the field(s) and using Border on the Style menu.

In MS Windows environments, the form initially inherits attributes such as font and point size from the painting window. Make global changes to the form by changing the painting windows attributes. For example, select the painting window (by clicking on the window), then use Font on the Style menu to change the font for all form fields.

The TRANSFORM option on the screen painter's EDIT menu can be used to convert fields from one type to another. Use the TRANSFORM option to convert variable boolean fields into checkboxs.

Using the DC TUI to GUI tools

DC 7.1 has three new tools to help users to migrate from text-based interface to a graphical application interface.

The TUI to GUI Conversion tool converts forms and displays based on three different methods – fixed origin fields with border entry fields, fixed origin borderless fields and relative origin  fields with borders. From the TUI to GUI Conversion dialog window the user can select the method and the forms or displays to be converted.



The first two methods allow the user customize some of the parameters used in the conversion algorithm like the number of twips used per row and per column, the background and foreground colors of entry fields and date masks.





When many blank rows exist, the converted form may seem too big. Using the Blank Lines Weight the user can reduce the ”white space” effect. A Blank line Weight of 0.5, reduces each line to half line.

The Preview option allow the user to see how the form or display will look before its actual creation ; a dialog box is displayed and the user can save the form, discard it or try another method or different parameters.

If after the form or display conversion to the graphical mode, the user decides to keep the text mode, the GUI to TUI tool can be used to transform back the converted for to text again.

For users that intend to maintain for some time the text interface, the Text Window Generator allow the creation and maintenance of text windows inside the graphical environment.

The user can customize several of the text window attributes and also preview it before the actual creation.

Experimenting with GUI Objects

To understand the behavior and appearance of graphical objects, as well as the workings of FORM INPUT, use the "Test" mode of the painter. To access Test mode, select Test from the Painter's File menu. The painter creates an exact replica of your Zim window, display, form or, in MS Windows, menu. As you interact with these objects, a dialog appears enabling you to browse the Event, ThisForm, ThisWindow, and ThisMenu event structures. Leave "Test" mode by pressing the escape key ("Esc").

Tips and Hints for Painting GUI Interfaces

Although a list of hints for using the Screen Painter to convert your TUI forms and displays to GUI could go on forever (and is subject to taste), here are some helpful hints:

Co-ordinate Systems

The Screen Painter in the MS Windows environment enables you to work in very fine co-ordinate systems (Points, Decipoints, Twips) to position and size your interface objects. The 4GL, however, continues to work in a character (row/column) co-ordinate system. If you are working with positions and sizes in 4GL syntax, you give (and receive) character co-ordinates, for example

window move Win1 to 10 5

These character co-ordinates are automatically translated into the appropriate screen co-ordinates for display. Conversely, screen co-ordinates are delivered to the application program in structures such as ThisWindow (ex. ThisWindow.WindowRow) in character co-ordinates.

End-User Preferences under Microsoft Windows

Zim applications have been traditionally released into a non-standardized environment; that is, the application-defined user interface colors, date masks, etc. Windows, however, provides an environment where the end-user can declare a series of preferences (using the Control Panel) such as window background color, window text color and date mask format.

Consider changing your color scheme to accommodate end-user's preferences. For example, use inherited colors or pick colors that map onto Control Panel colors. Do not use explicit input masks for Date fields so that Zim uses the short date format defined in Control Panel's "International" settings.

In addition to the standard sixteen colors in Zim 4.x, Zim for Windows defines another 21 colors, corresponding to the Windows standard colors, that can be assigned in the Control Panel. The table below lists the Zim name of the Control Panel colors used most often:


Zim Color Constant Description
cWindowColor Background of window and window text background.
cWindowText Window text foreground.
cGrayText Window text foreground if corresponding object is unavailable.
cWindowBackground MS Windows desktop background color.
cAppWorkSpace Background color of main application window (Windows MDI).
cHighlightText Foreground color of "selected" text.
cHighlightColor Background color of "selected" text.
c3DObjectTextColor Foreground color of Windows 95-like widgets.
c3DObjectColor Background color of Windows 95- lilke widgets.


To have your application respect the end-user's color preferences, you should

 cHighlightText) CURSOR

This discussion refers to ordinary use of forms and windows; use of special highlighting or other display mode (DM) attributes should be examined to ensure conformity with a Windows environment.

Using the Mouse

If you have written a Zim 4.x application that makes use of the mouse and would like to convert your text windows to graphical ones, be aware that the mouse-related 4.x 4GL statements are not supported in under graphical windows. However, the application behaves very nearly as designed, with a few exceptions.

Under graphical windows, none of the mouse button events BUTTON1 through BUTTON6 are produced. For example, if you were catching BUTTON1 and then moving the cursor via

FORM SET (CURSOR) ($MouseFormNum,\
 $MouseFieldNum, $MouseSubscript)

 Zim 5.x does this automatically (the field must be available).

If you were detecting one of the mouse events to invoke some action (such as open a new window), then find an alternative means of triggering that same action. Under MS Windows, it is preferable to use push buttons and menus to trigger actions.

Keyword Conflicts

When new keywords are introduced into the Zim language, there is potential for conflicts with application object names. Use the PARSE command with your programs to verify that none of your application object names are in conflict with new keywords.

If you encounter a conflict, you can continue to use the conflicting object name if you qualify it with its owner name. For example, if you have a field called "Menu" in an EntitySet called "Ent1" which now is in conflict with the keyword "MENU", use "Ent1.Menu" instead of "Menu" in your programs.

A Default Accelerator Key

The Escape key is, by default, an accelerator (i.e. exit) key for any graphical window. If you convert your text windows to graphical ones and this behavior is not appropriate, ensure that the appropriate keys are set via WINDOW SET [NOT] ACCELERATOR.

Blink Display Mode not Supported Under MS Windows

The window or form field display mode (DM) "blink" in 4.x is not supported (there is no hardware assist for blinking text under MS Windows). Instead, any text drawn with a "blink" display mode appears italicized.

The Backscreen Window

The BACKSCREEN window in Zim for Windows is intended to be used only while developing an application. The BACKSCREEN window cannot be used to display graphical objects, but supports Zim 4.x forms and displays, as well as line-at-a-time I/O.

In MS Windows environments, the BACKSCREEN window is always available and contains menu options to assist you during development. When running a completed application, use the configuration option "backscreen hide yes" to suppress the appearance of the BACKSCREEN window. (The new Example Application uses this option.)

For more information, refer to the Backscreen Hide topic.

Query Reporting Facility

Existing 4.2 applications with the Query Reporting Facility require the configuration option "Parameter Size 80" in their configuration files. The Query Reporting Facility is no longer supported. The default value of Parameter Size option has been increased to 256 in Zim for Windows from its default of 80 in previous versions of Zim.

Character Set Differences (MS Windows Only)

Microsoft Windows uses, by default, a different character set than the standard PC character set. When you create a new Zim 5.x database, you are given the option to use either the Windows character set or the OEM character set.

If you use Zim for Windows with a Zim 4.x database, the OEM character set is assumed.

Time-out Event Latency (MS Windows Only)

If you are using time-outs to expire a FORM INPUT command, be aware that under Windows, the time-out period you set represents a minimum of time after which a time-out occurs (i.e., if you set a time-out of 10 seconds it may occur after 10 seconds, or perhaps 20 seconds). The delay can occur because Windows considers the delivery of timer messages to be of low priority, and does not guarantee on-time delivery.

This delay can cause problems if you are trying to perform exact delays with the SLEEP command.