------------------------------------------------------------------------
                      [incr Tcl] - version 2.2
------------------------------------------------------------------------
  This version includes tcl7.6 / tk4.2 upgraded to support
  namespaces, along with [incr Tk] and [incr Widgets].

  Binary distributions for Windows95 and Macintosh platforms
  are available on our web site:

      http://www.tcltk.com/itcl/

  Many different people have contributed code for this release,
  and I thank them for their contributions.  Please read the
  acknowledgements section below.

  Send comments or suggestions to the [incr Tcl] mailing list
  (itcl@tcltk.com) or directly to me (mmclennan@lucent.com).
  If you want to subscribe to the mailing list, send a message
  with the subject "subscribe" to "itcl-request@tcltk.com".

========================================================================
             Copyright (c) 1993-1996   Lucent Technologies
========================================================================
 Permission to use, copy, modify, and distribute this software and its
 documentation for any purpose and without fee is hereby granted,
 provided that the above copyright notice appear in all copies and that
 both that the copyright notice and warranty disclaimer appear in
 supporting documentation, and that the names of Lucent Technologies
 any of their entities not be used in advertising or publicity
 pertaining to distribution of the software without specific, written
 prior permission.

 Lucent Technologies disclaims all warranties with regard to this
 software, including all implied warranties of merchantability and
 fitness.  In no event shall Lucent be liable for any special, indirect
 or consequential damages or any damages whatsoever resulting from loss
 of use, data or profits, whether in an action of contract, negligence
 or other tortuous action, arising out of or in connection with the use
 or performance of this software.
========================================================================

 OVERVIEW
------------------------------------------------------------------------
 - What is [incr Tcl]?
 - Getting started
 - Installation
 - Integrating [incr Tcl] with other extensions
 - Acknowledgements
------------------------------------------------------------------------


 What is [incr Tcl]?
------------------------------------------------------------------------
 [incr Tcl] is an object-oriented extension of the Tcl language.  It
 was created to support more structured programming in Tcl.  Tcl scripts
 that grow beyond a few thousand lines become extremely difficult to
 maintain.  This is because the building blocks of vanilla Tcl are
 procedures and global variables, and all of these building blocks
 must reside in a single global namespace.  There is no support for
 protection or encapsulation.

 [incr Tcl] introduces the notion of objects.  Each object is a bag
 of data with a set of procedures or "methods" that are used to
 manipulate it.  Objects are organized into "classes" with identical
 characteristics, and classes can inherit functionality from one
 another.  This object-oriented paradigm adds another level of
 organization on top of the basic variable/procedure elements, and
 the resulting code is easier to understand and maintain.

 Among other things, [incr Tcl] can be used to create new widgets that
 look and work like the usual Tk widgets, but are written entirely at
 the Tcl language level (C code is optional).  These "mega-widgets"
 can be created using [incr Tk], a set of base classes which provide
 the core mega-widget functionality.  [incr Widgets] is a set of
 high-level mega-widgets built using [incr Tk].  It has more than
 35 widget classes, and can be used right out of the box to create:

   - fileselectiondialog
   - tabnotebook
   - panedwindow
   - scrolledhtml
   - combobox
   - optionmenu
   - scrolledlistbox
   - scrolledframe
   - messagedialog
   - and many others...
 
 Classes and/or related procedures can also be encapsulated in their
 own "namespace".  A namespace is a collection of commands, variables,
 classes and other namespaces that is set apart from the usual global
 scope.  Elements within a namespace can be "private" or "protected",
 so that access to them is restricted.  An "import" command allows all
 of the elements from one namespace to be integrated into another.

 Extension writers will immediately see the benefit of namespaces.
 With vanilla Tcl, each extension must add its commands and variables
 at the global scope.  Extension writers are encouraged to add a unique
 prefix to all of the names in their package, to avoid naming collisions.
 Extensions can now sit in their own namespace of commands and variables,
 and sensitive elements can be protected from accidental access.  For
 example, the current release of [incr Tcl] has a namespace "itcl"
 for object-oriented support, a namespace "itk" for mega-widget
 support, and a namespace "iwidgets" for the [incr Widgets] package.
 Each of these namespaces has its own collection of commands and
 variables.  Developers can then pick and choose among the extensions,
 and integrate the parts that they need for their application by
 importing various namespaces at the global scope.


 Getting started
------------------------------------------------------------------------
 Read the first part of the CHANGES file for a brief overview of
 new commands, and a summary of important changes.  Consult the
 man pages for detailed information on particular commands.

 Check out our web site on WebNet for the latest news:

     http://www.tcltk.com/itcl/

 >> NOTE <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
 >>                                                             <<
 >>   If you are just getting started with [incr Tcl], be sure  <<
 >>   to download the TUTORIAL on our web site.  This has over  <<
 >>   100 pages of introductory text and code examples.         <<
 >>                                                             <<
 >>   Also, run the "catalog" demo to get an overview of the    <<
 >>   [incr Widgets] package.  On Windows and Macintosh         <<
 >>   systems, this is installed as one of the executables.     <<
 >>   On Unix systems, this is installed in the                 <<
 >>   "lib/itcl/iwidgets2.2.0" library directory.               <<
 >>                                                             <<
 >><<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

 The file "iwidgets2.2.0/doc/iwidgets.ps" contains a tutorial
 introduction to the [incr Widgets] package.  The mega-widget
 classes in this package show off most of the functionality in
 this release.  You can use them as a pattern to create your
 own widget classes.


 Installation on Unix Systems
------------------------------------------------------------------------
  1)  Obtain this distribution from an archive site like this:

        ftp ftp.tcltk.com
        cd pub/itcl
        binary
        get itcl2.2.tar.gz
        quit


  2)  Uncompress and untar the distribution:

        gunzip itcl2.2.tar.gz
        tar xvf itcl2.2.tar


  3)  Run the configuration script:

        cd itcl2.2
        ./configure

      or, for systems that don't recognize "#!" in shell scripts:

        cd itcl2.2
        /bin/sh ./configure

      The "configure" script finds the appropriate compiler flags and
      generates new Makefiles from template files (Makefile.in).

      By default, the configuration script will set things up so
      that everything is installed in "/usr/local".  You can change
      this by specifying a different "prefix" in the "configure" command:

        ./configure --prefix=/your/install/path

      By default, everything will be build with non-shared libraries.
      You can request shared libraries and dynamic loading like this:

        ./configure --enable-shared


  4)  Build the libraries and the executables.  From the toplevel
      directory type:

        make all


  5)  Install the libraries, executables, man pages and script files.
      From the toplevel directory type:

        make install


  6)  Use the final product.  This distribution creates and installs
      four executables:
      
        ish7.6 ........... [incr Tcl] sh  (tclsh + namespaces)
        iwish4.2 ......... [incr Tcl] wish  (wish + namespaces)
        itclsh2.2 ........ tclsh + namespaces + classes
        itkwish2.2 ....... wish + namespaces + classes + megawidgets

      If you configured this distribution with "--enabled-shared" to
      request dynamic loading, you can use "ish" or "iwish" as the
      core program and load everything else as needed.  For example,
      you can start up "iwish" and load the [incr Widgets] package
      like this:

        unix$ iwish4.2
        % package require Iwidgets

      This single command is enough to load Itcl2.2, Itk2.2 and
      Iwidgets2.2.0 dynamically.  The interpreter will have all the
      commands needed to use the [incr Widgets] package.

      On some systems, you may get an error like:

          iwish4.2: can't load library 'libtcl7.6i.so'

      If you get this, it means that you need to include the "lib"
      directory containing the [incr Tcl] libraries in your
      LD_LIBRARY_PATH environment variable.  You might add some
      lines like this to your ".cshrc" or ".profile" file:

          csh users: add something this to .cshrc
            setenv LD_LIBRARY_PATH "/usr/local/lib/itcl:$LD_LIBRARY_PATH"

          ksh users: add something this to .profile
            LD_LIBRARY_PATH="/usr/local/lib/itcl:$LD_LIBRARY_PATH"
            export LD_LIBRARY_PATH

      This assumes that the libraries were installed in the
      directory "/usr/local/lib/itcl".


      If you did not configure for dynamic loading, you will probably
      want to use the "itkwish2.2" program instead.  This includes
      everything you need to use [incr Widgets], and you won't have
      to worry about LD_LIBRARY_PATH at all.


 Installation on Macintosh Systems
------------------------------------------------------------------------
 The easiest way to use [incr Tcl] for Macintosh is to obtain the
 binary distribution at our website:

    http://www.tcltk.com/itcl
 or
    ftp://ftp.tcltk.com/pub/itcl/itcl2.2-68k.sit.hqx  (68000 series)
    ftp://ftp.tcltk.com/pub/itcl/itcl2.2-ppc.sit.hqx  (PowerPC)

 This solution will save you from having to compile [incr Tcl] and
 is recommended unless you need to alter the source code.

 But if you must build [incr Tcl] under MacOS, you can do so as
 follows.  First, download the project files from our web site:

    http://www.tcltk.com/itcl
 or
    ftp://ftp.tcltk.com/pub/itcl/itcl2.2-macProjects.sit.hqx

 Store this file in the "itcl2.2" folder that contains the entire
 source distribution, at the same level as the "README" and "CHANGES"
 files.  Then use the Stuffit expander to unpack it.  Look for a
 folder called "Mac Projects", find the file called "README" within
 it, and follow the instructions in that file.

 Please report questions or problems you may have with the Macintosh
 version to:

      Jim Ingham
      Bell Labs Innovations for Lucent Technologies
      <mailto:jingham@lucent.com>


 Installation on Windows 95 and Windows NT
------------------------------------------------------------------------
 The easiest way to use [incr Tcl] for Windows is to obtain the
 binary distribution at our website:

    http://www.tcltk.com/itcl
 or
    ftp://ftp.tcltk.com/pub/itcl/itcl22.exe

 The file "itcl22.exe" is a self-extracting archive that will install 
 the  components necessary to run [incr Tcl] scripts.  This solution 
 will save you from having to compile [incr Tcl] and is recommended
 unless you need to alter the source code.

 But if you must build [incr Tcl] under Windows, you can do so as
 follows.  First, you will need one of the following compilers:

     Borland C++ 4.52 or later
 or 
     Microsoft Visual C++ 4.0 or later..  

 Makefiles are provided for either of these compilers.  Other compilers
 may work, but these are tested.  

  1)  Obtain this distribution from an archive site like this:

        ftp ftp.tcltk.com
        cd pub/itcl
        binary
        get itcl2.2.tar.gz
        quit

  2)  Uncompress and untar the distribution:

        gzip -d itcl2.2.tar.gz
        tar xvf itcl2.2.tar

  3)  Set the Source and Target directories in the Makefile

        Makefiles are available for both the Borland and Microsoft
        compilers:

        makefile.bc -- Borland C++ makefile
        makefile.vc -- Microsoft Visual C++ makefile

        Edit the corresponding makefile in this directory to set these
        variables to their appropriate paths:

        e.g.:
        TARGET_ROOT   = c:\Program Files\Itcl
        SOURCE_ROOT   = c:\itcl2.2

        TARGET_ROOT is the pathname to the directory where you
        would like the distribution installed.  Several directories
        will be created here.

        SOURCE_ROOT is the absolute pathname of this directory.

  3)  Build the distribution

        The target 'dist' will build the entire distribution.  
        In this directory, or one of the 'win' directories, type:

        Borland:
          make -fmakefile.bc dist

        Microsoft:
          nmake -fmakefile.vc dist

  5)  Install the distribution

        The target 'dist-all' will install the distribution to the
        TARGET_ROOT directory set in #2 above.  In this directory,
        or one of the 'win' directories, type:

        Borland:
          make -fmakefile.bc dist-install

        Microsoft:
          nmake -fmakefile.vc dist-install

  6)  Use the final product.  This distribution creates and installs
      four executables:
      
        ish.exe ........... [incr Tcl] sh  (tclsh + namespaces)
        iwish.exe ......... [incr Tcl] wish  (wish + namespaces)
        itclsh.exe ........ tclsh + namespaces + classes
        itkwish.exe ....... wish + namespaces + classes + megawidgets

  Please report questions or problems you may have with the Windows
  version to:

      Lee Bernhard
      Bell Labs Innovations for Lucent Technologies
      <mailto: lfb@lucent.com>


 Integrating [incr Tcl] with other extensions
------------------------------------------------------------------------
 [incr Tcl] now requires its own version of Tcl/Tk with support for
 namespaces.  Therefore, you must use the version of Tcl/Tk that
 comes in this distribution as a basis for other applications.
 Hopefully, the namespace support will become a part of the standard
 distribution some day.

 You can add other extensions into the [incr Tcl] package by
 following the usual instructions for Tcl/Tk:

  1) Put the source code for the extension in the directory
     "itcl2.2", at the same level as the directories "tcl7.6"
     and "tk4.2".

  2) Copy "tclAppInit.c" or "tkAppInit.c" from the standard
     distribution.  Choose the appropriate version according to
     your needs:

       tcl7.6/tclAppInit.c .... Tcl with namespaces
       tk4.2/tkAppInit.c ...... Tcl/Tk with namespaces
       itcl/tclAppInit.c ...... Tcl with namespaces and [incr Tcl]
       itk/tkAppInit.c ........ Tcl/Tk with namespaces and [incr Tcl]/[incr Tk]

  3) Each extension should have an initialization function with a
     name like "XXX_Init()".  The BLT package, for example, has a
     function "Blt_Init()".

     a) Include the declarations for any initialization routines
        at the top of the tclAppInit.c or tkAppInit.c file.

     b) Within the body of Tcl_AppInit(), add a call to the
        initialization routine.  It should look something like this:

          if (Itcl_Init(interp) == TCL_ERROR) {
              return TCL_ERROR;
          }
          if (Itk_Init(interp) == TCL_ERROR) {
              return TCL_ERROR;
          }
          if (Blt_Init(interp) == TCL_ERROR) {
              return TCL_ERROR;
          }

        In this example we have integrated BLT in with [incr Tcl] and
        [incr Tk].

  4) Link your application with the appropriate libraries.
     For example, with non-shared libraries, you would link
     against:

       libtcl7.6i.a ............ Tcl with namespaces
       libtk4.2i.a ............. Tk with namespaces
       libitcl2.2.a ............ [incr Tcl]
       libitk2.2.a ............. [incr Tk]

     and on Unix systems, you will also need:

       -lX11 ................... X11 library


 Acknowledgements
------------------------------------------------------------------------
 Thanks to Jim Ingham and Lee Bernhard for pushing the Windows95
 and Macintosh ports forward.

 Thanks to Christopher Hylands and Steve Johnson for helping to test
 this release.

 Thanks to Karel Zuiderveld, Jan Nijtmans and Vince Darley for helping
 to keep up with Tcl/Tk releases, and for supporting the "plus" and
 "dash" patches under [incr Tcl].

 Thanks to Mark Ulferts, Sue Yockey, John Sigler, Bill Scott, Alfredo
 Jahn, Tako Schotanus and Kris Raney for building the [incr Widgets]
 package.  With a sketchy overview and a crappy prototype of [incr Tk],
 they managed to build a nice set of mega-widgets.  Their initial
 designs helped me smooth out the rough spots in [incr Tk].

 Thanks to Forest Rouse and ICEM CFD Engineering for integrating
 [incr Tcl] into their Tcl/Tk compiler.  This is a large undertaking,
 and they have done an excellent job.

 Thanks to Alfredo Jahn and Bret Schuhmacher at WebNet for helping
 to create the [incr Tcl] web site, and for maintaining the
 [incr Tcl] mailing list.

 Thanks to extension writers like Mark Diekhans (tclX) and Ioi Lam (Tix)
 for making their packages compatible with [incr Tcl].

 Thanks to George Howlett for teaching me how namespaces should really
 work.  He has been a constant source of inspiration, and has kept
 a careful watch against many bad ideas.  Jim Ingham fleshed out the
 notion of explicit scoping, and added many nice features to [incr Tk].
 Bill Scott, with a steady stream of bug reports, helped me understand
 the questions that a typical user might have.  He forced me to reinvent
 the paradigm on more than one occasion.

 Thanks to more than 100 beta-testers that helped me polish the itcl2.0
 release.

 Thanks to Mark Harrison for his enthusiasm and support.  Due in
 large part to his evangelism, I have been able to make [incr Tcl]
 development a mainstream activity.

 And many thanks to my wife Maria and my son Maxwell for putting up
 with all of this.

--Michael
                                                              ...
---------------------------------------------------------  ':'...''. ---
  Michael J. McLennan 2C-226      mmclennan@lucent.com   '::.''''':;:
  Lucent Technologies                                   '::;       ;;:
  1247 S Cedar Crest Blvd                               :::,,       :;;
  Allentown, PA  18103             Lucent Technologies  ;:;'        ;:;
  phone: 610-712-2842            Bell Labs Innovations   ;;:       .;:
    fax: 610-712-2773                                     :;:,   ,:;:
                                                           ':;;;:;:'
