--------------------------------------------------------------------
--------------------  Zinc Interface Library  ----------------------
------------------ Version 3.0 Upgrade Changes ---------------------
--------------------------------------------------------------------


This document describes the changes that must be made to your
existing code using Zinc Interface Library versions prior to 3.0.


--------------------------------------------------------------------
Country information:
      Change:    The structure ui_country_info has been replaced by the
                 class UI_INTERNATIONAL.  

      Purpose:   The new class will allow for greater flexibility and
                 robustness for handling country-specific information.

--------------------------------------------------------------------
.DAT:
      Change:    The .DAT file structure has changed significantly.
                 Existing .DAT files can be converted to version 3.0
                 format using the convert utility CONVERT.ZIP found
                 on the Zinc BBS.

      Purpose:   More objects can now be stored in the data files and
                 can be accessed within a quicker access time.  A data
                 file can contain up to 16,000 objects with the file
                 size being up to 16 megabytes.  A single object has
                 a maximum size of 4 megabytes.

--------------------------------------------------------------------
Date:
      Change:    The UI_DATE class is now derived from
                 UI_INTERNATIONAL.

      Purpose:   UI_INTERNATIONAL will aid with the conversion
                 between country specific date formats.

      Change:    The =, +, -, ++, --, >=, <=, !=, +=, -= operator
                 overloads have been added.

      Purpose:   The additional operators will allow for more ways to
                 manipulate dates.

--------------------------------------------------------------------
Device:
      Change:    The names of the devices have been changed, as
                 follows:

                      UI_CURSOR                  ->     UID_CURSOR
                      UI_BIOS_KEYBOARD           ->     UID_KEYBOARD
                      UI_MS_MOUSE                ->     UID_MOUSE

      Purpose:   This change was made to provide a better relation
                 between the device classes.  All device classes will have
                 the UID_ prefix.

--------------------------------------------------------------------
Display:
      Change:    The names of the displays have been changed, as
                 follows:

                      UI_DOS_BGI_DISPLAY         ->     UI_BGI_DISPLAY
                      UI_DOS_FG_DISPLAY          ->     UI_FG_DISPLAY
                      UI_DOS_TEXT_DISPLAY        ->     UI_TEXT_DISPLAY

      Purpose:   The _DOS_ portion of the above class names was
                 considered to be redundant.  

      Change:    The UI_MSC_DISPLAY class was added to allow
                 display support for Microsoft C/C++.

--------------------------------------------------------------------
Error system:
      Change:    The UI_ERROR_WINDOW_SYSTEM class has been
                 removed and the UI_ERROR_SYSTEM class will
                 present error information in a modal dialog window.

      Purpose:   The two error system classes were not distinct enough
                 to warrant two separate classes.  Removing one of the
                 classes reduces the overall size of the library.

      Change:    The error system window will display the error text, an
                 ``Ok'' button, and a ``Cancel'' button.  Selecting the
                 ``Cancel'' button will restore the text that was on the
                 field before the current text was entered.  Selecting
                 ``Ok'' will keep the text as was entered, regardless of
                 the error message.

      Purpose:   This allows the error system to function as a dialog
                 window rather than simply reporting the error.  This
                 interaction is more standardized with other interface
                 environments.

--------------------------------------------------------------------
Event manager:
      Change:    There is a single UI_EVENT_MANAGER for both
                 DOS and Windows.  The UI_MSWINDOWS_MESSAGE class has
                 been deleted and is no longer required.  For an example
                 of the main( ) function format, see ``Starting an
                 application'' in this file.

      Purpose:   Consolidating the event managers for DOS and
                 Windows simplifies the code required to begin a Zinc
                 application.

--------------------------------------------------------------------
Header files:
      Change:    UI_MAP.HPP is no longer used, 

      Purpose:   Mapping information (color and event) is now contained
                 in UI_EVT.HPP.

--------------------------------------------------------------------
Help system:
      Change:    The class UI_HELP_WINDOW_SYSTEM has been
                 removed and the class UI_HELP_SYSTEM will now
                 implement a window-based help system.

      Purpose:   The previous classes were simple enough that two
                 separate classes were not warranted.

--------------------------------------------------------------------
Hotkeys:
      Change:    UI_WINDOW_OBJECT::hotkey is now private,  Use
                 UI_WINDOW_OBJECT::HotKey( ).

      Purpose:   Most member variables should not be changed at
                 random.  However, the Hotkey( ) function is provided
                 to allow a means of changing the hotkey.

--------------------------------------------------------------------
Icons:
      Change:    When an icon is passed in as the minimize object as
                 part of the UIW_WINDOW constructor, it will be
                 displayed when the window is minimized.  If the
                 WOS_MINIMIZED flag is set on the window before it
                 is added to the window manager, the window will
                 appear in a minimized state (i.e., as the icon).

      Purpose:   When an icon is used as a minimize object, it is
                 maintained by the window and is not considered to be
                 a separate object.

--------------------------------------------------------------------
Jump list:
      Change:    Zinc Designer 2.0 created a .CPP file with a
                 UI_JUMP_LIST object that was used to provide a jump
                 to the constructors of the objects created in the designer. 
                 Zinc Designer creates a similar table called
                 _objectTable.  _objectTable is an array of UI_ITEM
                 structures.  In addition to _objectTable, Zinc Designer
                 3.0 creates _userTable.  _userTable is a table of user
                 functions that were assigned to specific objects in the
                 designer.  For example, if a button was created (in the
                 designer), and ``Function1'' was entered for the user
                 function, _userTable will create an entry for
                 ``Function1.''  The following code should be added to
                 the file containing function main( ):

                      extern UI_ITEM _objectTable[];
                      extern UI_ITEM _userTable[];

                      main( )
                      {
                           .
                           .
                           .
                           UI_WINDOW_OBJECT::objectTable = _objectTable;
                           UI_WINDOW_OBJECT::userTable = _userTable;
                           .
                           .
                           .
                      }

      Purpose:   This change simplifies the process by which objects
                 (created using Zinc Designer) can be used in your code. 
                 User functions need only be implemented and they will
                 be called automatically.

--------------------------------------------------------------------
Matrix:
      Change:    The UIW_MATRIX class was divided into the
                 UIW_HZ_LIST (horizontal list) and the UIW_VT_LIST
                 (vertical list).  A vertical list will display a single
                 scrollable column of objects.  A horizontal list will
                 display multiple columns of objects that are scrollable
                 in the horizontal direction only.  For example, if the
                 horizontal list is 5 cell heights tall and 4 cell widths
                 wide, 4 columns of 5 objects each.  Any non-editable
                 (editable objects with the WOF_VIEW_ONLY or
                 WOF_NON_SELECTABLE flags set may be used)
                 object, including those with bitmaps, can be added to
                 the list.  (UIW_POP_UP_ITEM objects should only be
                 added to UIW_PULL_DOWN_ITEM or UIW_POP_-
                 UP_MENU objects.)

      Purpose:   These changes were made to provide more standard
                 objects across platforms.  This will take advantage of
                 the existing objects (e.g., MS Windows defined objects).

--------------------------------------------------------------------
Numbers:
      Change:    UIW_NUMBER has been replaced by UI_BIGNUM
                 and UIW_BIGNUM. 

      Purpose:   This change was to allow greater flexibility regarding
                 numbers.  The bignum classes can handle fixed-point
                 numbers that default to 30 digits to the left and 8 digits
                 to the right of the decimal point.  The number of
                 allowable digits can be changed by changing the values
                 of NUMBER_WHOLE and NUMBER_DECIMAL
                 which are #define values located UI_GEN.HPP.  For
                 example, changing NUMBER_WHOLE to a value of 60
                 will allow the existing code to support 60 digits to the
                 left of the decimal point.

      Change:    UI_BIGNUM supports the following operator overloads:
                 =, +, -, ++, --, +=, -=, ==, !=, >, >=, <=, <.

      Purpose:   The additional operators will allow greater flexibility in
                 manipulating numerical values.

      Change:    Number formatting (currency, percent, etc.) is supported
                 by the UIW_BIGNUM class only.  The
                 UIW_INTEGER class is used to handle integer values
                 only.  The UIW_REAL class is handles double values
                 and scientific notation.  Scientific notation is only used
                 if the length of the number is longer than the length of
                 the visible UIW_REAL field.

      Purpose:   Limiting the number formatting to the UIW_BIGNUM
                 class reduces the size of the library and the amount of
                 code duplicated in the other number classes.  This
                 allows for smaller executable programs.

--------------------------------------------------------------------
Path:
      Change:    The UI_PATH class has been changed.  It now
                 implements a linked-list of UI_PATH_ELEMENT
                 classes.  The actual path information is contained in
                 UI_PATH_ELEMENT.  

      Purpose:   This change allows new paths to be, more easily, added
                 and deleted from the complete search path (i.e.,
                 UI_PATH).

--------------------------------------------------------------------
Pop-up items:
      Change:    UIW_POP_UP_ITEMS should only be used within a
                 UIW_POP_UP_MENU or UIW_PULL_DOWN_ITEM
                 and should not be added directly to the screen.  Any
                 other window object can be used in conjunction with a
                 combo box, list, etc.

      Purpose:   The UIW_POP_UP_ITEM objects contain code that
                 allows them to function well when attached to a
                 UIW_PULL_DOWN_ITEM.  Other uses of this object
                 may yield uncertain results if used outside of their
                 documented purposes.

--------------------------------------------------------------------
Redisplay:
      Change:    In version 2.0, window objects were redisplayed by
                 calling DataSet(NULL).  Now objects should be
                 redisplayed using the + operator to re-add the object its
                 parent (window manager, window, list, etc.).  

      Purpose:   Since NULL is equivalent to 0, doing a DataSet(0) will
                 change the number field to 0 rather than re-displaying
                 the field.  Using the + operator will eliminate this
                 problem and make it easier to redisplay objects.

--------------------------------------------------------------------
Scroll bars:
      Change:    UIW_SCROLL_BAR objects should be added directly
                 to the object that they will control.  In version 2.0, if a
                 scroll bar was added to a parent window directly before
                 a list box, it would control the list box.  In version 3.0,
                 the scroll bar should be added to the list rather than
                 before it.

      Purpose:   This allows the controlling object to have better
                 communication with the scrollbar object.

--------------------------------------------------------------------
Storage:
      Change:    The data file structure has changed significantly.  For
                 details, see ``Chapter 31-UI_STORAGE'' of the
                 Programmers Reference.

      Purpose:   More objects can now be stored in the data files and can
                 be accessed within a quicker access time.  A data file
                 can contain up to 16,000 objects with the file size being
                 up to 16 megabytes.  A single object has a maximum
                 size of 4 megabytes.

      Change:    The class UI_STORAGE_ELEMENT has been replaced
                 by the class UI_STORAGE_OBJECT.

      Purpose:   The new name is more descriptive of the class' purpose.

--------------------------------------------------------------------
Starting an application:
      Change:    The compiler directive _WINDOWS is used to show the
                 code that is specific to Windows programming.  The
                 following code segment shows how a typical Zinc
                 application can be setup for either DOS or Windows
                 programming:

                 #ifdef _WINDOWS
                 int PASCAL WinMain(HANDLE hInstance, HANDLE
                 hPrevInstance,
                      LPSTR, int nCmdShow)
                 {
                      UI_DISPLAY *display = 
                           new UI_MSWINDOWS_DISPLAY(hInstance, hPrevInstance,
                                 nCmdShow);
                 #else
                 main(int argc, char *argv[])
                 {
                      UI_DISPLAY *display;
                      if (argc > 1 && !strcmp("+t", argv[1]))
                           display = new UI_TEXT_DISPLAY;
                      else
                      {
                           UI_BGI_DISPLAY::searchPath = new UI_PATH;
                           display = new UI_BGI_DISPLAY;
                      }
                 #endif
           
                      UI_EVENT_MANAGER *eventManager = 
                           new UI_EVENT_MANAGER(display);
                      *eventManager
                           + new UID_KEYBOARD
                           + new UID_MOUSE
                           + new UID_CURSOR;

                      UI_WINDOW_MANAGER *windowManager = 
                           new UI_WINDOW_MANAGER(display, eventManager);
                      .
                      .
                      .
                 }

      Purpose:   It is now simpler to initialize a Zinc application to run
                 in either DOS or Windows.

--------------------------------------------------------------------
Status flags:
      Change:    The window object advanced status (WOAS_) flags
                 have been changed to window object status (WOS_)
                 flags in order to consolidate the status flags.

      Purpose:   There were so few of these flags that they were
                 consolidated.

--------------------------------------------------------------------
Time:
      Change:    Packed integer time values are no longer used for the
                 constructor, Import( ), or Export( ).

      Purpose:   The packed integer is not portable across environments. 
                 Since Zinc is emphasizing portability, non-portable data
                 types are being avoided.

      Change:    The UI_TIME class is now derived from
                 UI_INTERNATIONAL.

      Purpose:   This will aid with the conversion between country-
                 specific time formats.

      Change:    The =, +, -, ++, --, >=, <=, !=, +=, -= operator
                 overloads have been added.

      Purpose:   The additional operators will allow for more ways to
                 manipulate times.

--------------------------------------------------------------------
User functions:
      Change:    In version 2.0, user functions were of the following
                 format:

                      void userFunction(void *object, int ccode);

                 In version 3.0, user functions use the following format:

                      EVENT_TYPE
                      userFunction(UI_WINDOW_OBJECT *object, 
                           UI_EVENT &event, EVENT_TYPE ccode);

      Purpose:   The user function declaration was changed to allow user
                 functions to receive the actual event that caused the
                 function to be called.  In version 3.0, user functions will
                 also be called when the associated window object
                 receives the L_SELECT (i.e., <ENTER> is pressed or
                 the object is clicked with the mouse), S_CURRENT (the
                 field becomes current), and S_NON_CURRENT (the
                 field becomes non-current) messages.  This will allow
                 user functions greater flexibility.  Additionally, user
                 functions are now used as validation routines (e.g., for
                 strings, dates, times, etc.).

                 NOTE:  Since existing user functions will now be called
                 three times (on select, current, non-current), it will be
                 necessary to put a check the ccode at the beginning of
                 each user function to see why it was called.  In order to
                 constrain the user function to only execute the body of
                 its code when an L_SELECT message is sent, the
                 following check should be made:

                      if (ccode != L_SELECT)
                           return ccode;

--------------------------------------------------------------------
ui_parse_range:
      Change:    The parse range function become a private member of
                 UIW_STRING. 

      Purpose:   This change was made since range parsing is only
                 handled by UIW_STRING.

--------------------------------------------------------------------
Validate functions:
      Change:    User functions are now used to validate input fields. 
                 The validate functions are no longer used.  Please see
                 the ``User function'' entry for details.

      Purpose:   Having a single function for both purposes eliminates
                 some of the confusion as to the purpose and usage of
                 each function.

      Change:    There is a new function Validate( ), that was added to
                 UIW_BIGNUM, UIW_DATE, and UIW_TIME.  If the
                 userFunction variable for the particular object is NULL,
                 Validate( ) will be called to validate the value when the
                 object receives the S_CURRENT or
                 S_NON_CURRENT messages.  Validate( ) will call
                 UI_ERROR_SYSTEM::ReportError( ) to report a
                 validation error.  If userFunction is not NULL, then the
                 userFunction MUST call Validate( ) directly.  Otherwise
                 no validation is performed.

      Purpose:   This provides the programmer with a pre-defined
                 validation routine.  If a user function is provided,
                 Validate( ) is not called to allow the programmer to
                 either do specialized validation or call the object's
                 Validate( ) function.

--------------------------------------------------------------------
