
 [incr Tcl] - CHANGE LOG
==========================================================================
 ----------------------- CHANGES FROM itcl-1.5 --------------------------
==========================================================================

 Release itcl-2.0 provides a new syntax for defining classes.  The
 new syntax is accessed using the new "itcl::class" command.  For the
 time being, the old syntax will be supported via the old "itcl_class"
 command, but support for this will be phased out over time.

 Because both syntaxes are supported, the new version is "backward
 compatible" with the previous itcl-1.5 release.  However, there are
 some semantic changes that may break existing scripts.  These are
 listed in detail in the section "INCOMPATIBLE CHANGES".


 CATALOG OF NEW COMMANDS
--------------------------------------------------------------------------
 Following is a brief catalog of new commands available in this release.

 == Tcl with Namespaces =================================================

    delete namespace name ?name...?

      Deletes one or more namespaces, destroying all commands, variables,
      and child namespaces within it.


    ensemble name {
        option optName arglist body
        option optName arglist body
        ...
        ensemble optName {
            option subOptName arglist body
            option subOptName arglist body
            ...
        }
    }

      Adds options to an ensemble called "name".  If the ensemble does
      not already exist, it is created automatically.  An "ensemble" is
      a toplevel command that groups a collection of sub-commands.  For
      example, the usual Tcl "info" command is an ensemble with options
      like "globals", "level", "tclversion", etc.

      Ensembles are good for two reasons.  First, new options can be
      integrated in without modifying any source code or "switch"
      statements.  For example, [incr Tcl] adds the "info classes"
      and "info objects" commands simply by adding options to the
      "info" ensemble.  Second, error messages are generated automatically
      by the ensemble mechanism.  Try invoking "info" with no options
      and see the result.

      Each option declaration is just like a Tcl proc declaration,
      with an option name, arglist and body.  Ensembles can also
      contain sub-ensembles with more options.


    import add name ?name...? ?-where pos...?
    import all ?name?
    import list ?importList?
    import remove name ?name...?

      Used to manipulate the "import" list for the current namespace.
      When one namespace imports another, it gains access to all of
      its public commands/variables as if they were part of the
      same namespace.  In other words, one namespace can be integrated
      seamlessly into another by adding it to the import list of the
      other namespace.  By default, each namespace imports its parent,
      so most namespaces import the global scope in some fashion.

      The form "import list" is used to query or set the import list
      for the current namespace.  The form "import all" returns the
      namespace search path that is consulted when commands/variables
      are accessed.


    info context

      Returns the current namespace context.  The global namespace
      context is reported here as "", so it is easy to build
      namespace paths like this:

          set path "[info context]::name"


    info namespace all ?pattern?

      Returns a list of namespaces found in the current namespace
      context, whose names match an optional string pattern.  This
      includes children of the current namespace, and children of
      all imported namespaces.


    info namespace children ?name?

      Returns a list of child namespaces for namespace "name",
      or for the current namespace if "name" is not specified.


    info namespace parent ?name?

      Returns the parent namespace for namespace "name", or
      for the current namespace if "name" is not specified.


    info namespace qualifiers string

      Parses a string of the form "namesp::namesp::name", and returns
      the leading "namesp::namesp" scope qualifiers.


    info namespace tail string

      Parses a string of the form "namesp::namesp::name", and returns
      the trailing "name" element.


    info protection ?-command? ?-variable? name

      Returns the protection level for an element.  By default, "name"
      is treated as a command name, but the "-command" or "-variable"
      flags can be used to request a specific treatment.


    info which ?-command? ?-variable? ?-namespace? name

      Reports the full namespace path (e.g., "::namesp::namesp::name")
      for an element.  By default, "name" is treated as a command name,
      but the "-command", "-variable" and "-namespace" flags can be
      used to request a specific treatment.


    namespace name ?-local? ?-enforced val? ?--? ?commands?

      This is the usual mechanism for creating a namespace and defining
      elements within it.

      If namespace "name" does not exist, it is created automatically.
      The namespace name may include a full namespace path (e.g.,
      "namesp::namesp::namesp").  During the search for this namespace,
      all imported namespaces are consulted.  If the "-local" flag is
      specified, then the search is restricted to the local namespace;
      this prevents against accidentally importing a namespace if the
      intent is to create a child namespace.

      If the "-enforced" flag is specified, then "val" is treated as a
      boolean value; if true, then command/variable enforcement is
      turned on for this namespace.  Each time a new command is
      referenced within the namespace, Tcl automatically calls a
      procedure:

          enforce_cmd <name>

      with the <name> of the command that is about to be executed.  The
      "enforce_cmd" proc can return an error, and access to that command
      will be denied.  It can return another command name, or a more
      specific namespace path, and that command will be used instead.
      Or it can return "", and command lookup will continue via the
      normal namespace rules (i.e., in local scope, imported namespaces,
      etc.).

      Each time a new variable is referenced within an enforced
      namespace, Tcl automatically calls a procedure:

          enforce_var <name>

      with the <name> of a global variable that is being referenced.
      The "enforce_var" proc can return an error, and access to that
      variable will be denied.  It can return another variable name,
      or a more specific namespace path, and that variable will be
      used instead.  Or it can return "", and variable lookup will
      continue via the normal namespace rules (i.e., in local scope,
      imported namespaces, etc.).

      Note that command/variable enforcement done at the Tcl language
      level can be slow.  There is also a C language interface for
      the same functionality, which offers much better performance.

      The namespace is first found and updated with whatever flags were
      specified.  After that, if a "commands" string was specified, it
      is executed in the context of the namespace.


    public command ?arg arg...?
    protected command ?arg arg...?
    private command ?arg arg...?

      These commands attach a particular protection level to whatever
      commands or variables are created while executing the specified
      command.  They are used in conjunction with commands like
      "proc" and "variable" to create public/protected/private elements.


    scope string
    code ?-namespace name? command ?arg arg ...?
    @scope namespace value

      The "scope" command takes a string and encodes it into an "@scope"
      declaration.  The "code" command performs a similar function,
      but accepts multiple arguments and is usually used to wrap up
      code fragments.  The "@scope" declaration keeps a value (like a
      variable name or code fragment) together with its context
      namespace.  It can be executed like an ordinary command:

        set cmd {@scope :: puts}
        $cmd "hello world!"

      or used as an ordinary variable name:

        set var {@scope :: auto_path}
        lappend $var /usr/local/mylib

      The difference, however, is that an "@scope" value bypasses the
      usual access protections and guarantees that values have the
      proper scope.

      Ordinary variable names refer to variables in the global
      namespace.  Ordinary code fragments are usually interpreted
      by extensions like Tk in the global namespace.  The "scope"
      and "code" commands are used to wrap up variable names and
      code fragments to preserve the namespace context.  For example:

        namespace foo {
            private variable state 0
            private proc show_state {mesg} {
                global state
                puts "$mesg: $state"
            }

            checkbutton .cb -text "Toggle" \
                -variable [scope state] \
                -command [code show_state "current state"]

            pack .cb
        }

      In this example, the checkbutton is tied to the variable
      "foo::state" and executes the command "foo::show_state"
      whenever it is pressed.

      When a Tk widget uses commands and variables within a
      namespace, these names should be wrapped up as scoped
      values, as shown above.


    variable name ?value?
      Creates a variable called "name" and initializes it to an optional
      value.  This is normally used in conjunction with public, protected
      and private commands to declare variables within a namespace:

          namespace foo {
              public variable x 0
              private variable y 1
          }

      If the variable "name" already exists, it updated to have
      the protection level that is currently active.


 == Tk with Namespaces ==================================================

    bind...

      Recognizes and expands the following fields within command
      strings:

        %q  =>  Replaced with the fully-qualified access command
                for the widget receiving the event.  For example,

                    namespace foo {
                        namespace bar {
                            button .b -text "Hello World!"
                        }
                    }

                The fully-qualified access command for this widget
                is "::foo::bar::.b".  The "%q" field should be used
                instead of "%W" as the widget access command:

                    bind Button <Key-Return> "%q flash; %q invoke"


        %M  =>  Replaced with the window path name of the mega-widget
                containing the window receiving the event.  For example,
                if an "entryfield" mega-widget ".x" contains an entry
                widget ".x.entry", bindings added to ".x.entry" will
                replace "%M" with ".x".  This allows generic bindings
                to be added to component widgets which affect the
                mega-widget as a whole.

                For this to work properly, mega-widget packages must
                register their component widgets using Itk_SetMegaWidget().


    winfo command window

      Returns the fully-qualified access command for the widget "window".
      This is equivalent to the "%q" field in bindings, and is useful
      in procedures where the only the window name is known:

        foreach kid [winfo children $win] {
            [winfo command $kid] configure -bg blue
        }


    winfo megawidget window

      Returns the window path name of the mega-widget containing "window"
      as a component.  This is equivalent to the "%M" field in bindings,
      and is useful in procedures where only the component window name
      is known.  For this to work properly, mega-widget packages must
      register their component widgets using Itk_SetMegaWidget().


 == [incr Tcl] ==========================================================

    delete class name ?name...?

      Deletes one or more object classes.  Deleting a class also
      causes all derived classes, and all objects belonging to the
      class, to be deleted as well.


    delete object name ?name...?

      Deletes one or more objects.  If the access command for an
      object resides in another namespace, then the full namespace
      path should be used:

          delete object foo::bar::x


    info classes ?pattern?

      Returns a list of all classes in the current namespace
      whose names match an optional string pattern.


    info objects ?-class className? ?-isa className? ?pattern?

      Returns a list of all objects whose names match an optional
      string pattern.  If the "-class" option is specified, then
      the list is further restricted to those objects whose
      most-specific class is "className".  If the "-isa" option
      is specified, then the list is further restricted to those
      objects who belong to class "className".


    itcl::class name { definition }

      Used to create define a new class "name".  The "definition"
      commands include:

          inherit baseClass ?baseClass...?

          constructor arglist ?init? body
          destructor body

          method name ?arglist? ?body?
          proc name ?arglist? ?body?
          variable name ?init? ?config?
          common name ?init?

          public command ?arg arg...?
          protected command ?arg arg...?
          private command ?arg arg...?

      Note that the constructor statement has changed to include an
      optional "init" argument.  This is an initialization statement
      that can be used to call out base class constructors.  If it
      is not included, base classes are constructors are invoked
      automatically without any arguments.

      The "variable" statement is now used to create object-specific
      data members.  The "common" statement is used to create "common"
      variables, which are global within the class namespace.  Both
      types of variables can be designated public, protected or
      private.


    itcl::body class::func arglist body

      Used to define the body of a class member function outside of
      the class definition.  If "body" declarations are kept in a
      separate file, they can be sourced again and again to test
      changes as bugs are fixed.  If an "arglist" is specified in
      the class definition, then the "arglist" for the body definition
      must have the same meaning.


    itcl::configbody  class::option body

      Similar to the "body" command, but used to define the configuration
      code for a public variable.


    itcl_class name { old-style-definition }   \__ backward compatibility
    itcl_info option ?arg arg...?              /


 == [incr Tk] ===========================================================

    itcl::class name {
        ...
        itk_option define -switch resName resClass initVal ?configCode?
    }

      The "itk_option define" command is recognized at the level of
      the class definition.  It defines a new mega-widget option with
      the given switch name and X11 resource database names.  The
      "initVal" is used as a last resort to initialize the option
      if no other value can be queried from the X11 resource database.
      If "configCode" is specified, it is executed whenever the option
      is modified via the "configure" method.  The "configCode" can
      also be specified outside of the class definition via the
      "itcl::configbody" command.


  Methods provided by itk::Archetype base class:

    component
    component name
    component name command ?arg arg...?

      Used to query or access components within a mega-widget.  With
      no arguments, this returns a list of component widgets that
      are accessible in the current scope.  Note that component
      widgets obey any public/protected/private access restriction
      that is in force when the component is created.

      With one argument, this returns the window path name for a
      component with the symbolic name "name".

      In any other case, the remaining arguments are invoked as a
      method on the component with the symbolic name "name".


    configure
    configure option
    configure option value ?-switch value...?

      Works just like the usual Tk configure method, but for mega-widgets.
      Here options are really composite widget options.  When set, they
      trigger changes to many different internal components, and may
      invoke many bits of "configCode" for options defined by "itk_option
      define".  However, there is only one value for the composite option.


    cget option

      Works just like the usual Tk cget method, but for mega-widgets.
      Returns the current value for a composite widget option.


    itk_component add name {create-commands} ?{option-commands}?

      Adds a new mega-widget component with the symbolic name "name".
      Invokes the "create-commands" to create the component, and
      invokes "option-commands" to integrate its options into the
      composite list.  By default, no options are integrated.  Options
      may be added using the following commands:

          keep option ?option...?
          ignore option ?option...?
          rename oldswitch newswitch resname resclass
          usual ?tag?


    itk_component delete name ?name...?

      Deletes an existing mega-widget component with the symbolic
      name "name".  The component will still exist as a widget,
      but it will no longer be accessible as a component for this
      mega-widget.  Any options associated with the component are
      removed from the composite list.

      Note that you can destroy a component like any ordinary widget:

          destroy .foo.bar.b

      Components automatically detach themselves from their mega-widget
      parent when destroyed, so "itk_component delete" is not used
      very often.


    itk_option add option ?option...?     \__ class::option
    itk_option remove option ?option...?  /   component.option

      Adds or removes an option from the composite option list for
      a mega-widget.  These commands cannot be used at the level of
      the class definition; they must be invoked for a particular
      mega-widget.  They usually appear in the constructor for a
      mega-widget class, to add or redefine options in components
      created by a base class.  For example, the base classes
      itk::Toplevel and itk::Widget keep only the bare minimum
      options for their "hull" component:  -background and -cursor.
      If you want your mega-widget to have a border around it, you
      can add the hull options back in:

          itcl::class MyWidget {
              inherit itk::Widget

              constructor {args} {
                  itk_option add hull.borderwidth hull.relief
              }
          }


    itk_initialize ?option value option value...?

      Initializes the composite option list for a mega-widget.
      This method should be invoked within the constructor for each
      mega-widget class.  It is usually included the end of the
      constructor, below the component creation code.  It integrates
      all "itk_option" options defined in the current class into
      the composite configuration list, and includes "-option value"
      settings usually received as arguments to the constructor.
      When this is executed in the most-specific class, it scans
      through the composite option list and makes sure that all
      options have been properly initialized.

    itk::usual tag ?commands?

      Used outside of a mega-widget class definition to declare
      the "usual" option-handling commands for the mega-widget.
      These commands suggest how the configuration options should
      be handled if the mega-widget becomes a component of an even
      larger mega-widget.  They include commands like "keep" and
      "rename".


 INCOMPATIBLE CHANGES
--------------------------------------------------------------------------

 >> Object construction/destruction now follows C++ model.

    In the previous release, object construction started at the
    most-specific constructor.  Base class constructors could
    be called out explicitly within the body of a constructor.
    If they were not, they were invoked implicitly when the
    constructor finished executing.  This led to a construction
    model that was backward from C++, and contrary to what most
    people expected.  Destructors were backwards in a similar
    manner.

    In the current release, object construction starts at the
    least-specific class in the hierarchy, and proceeds to the
    most-specific class.  Therefore, each base class is fully
    constructed before the derived class constructor is executed.

    Arguments are now passed to base class constructors through
    an optional "initialization" statement.  This statement is
    included between the argument list and the body of the
    constructor, so the syntax is reminiscent of C++:

        class Base {
            constructor {x y} {
                ...constructor body...
            }
        }
        class Derived {
            inherit Base
            constructor {x y z} {
                Base::constructor $x $y    << "initialization"
            } {
                ...constructor body...
            }
        }

    Note that variables from the argument list (e.g., $x and $y)
    can be referenced within the initialization statement.  With
    multiple inheritance, each of the base class constructors
    can be called out individually.

    Object destruction is the exact opposite of construction.
    It proceeds from most-specific to least-specific class.


 >> All class methods are now implicitly virtual

    In the previous release, all method names were interpreted
    with respect to the current class scope and its base classes.
    If you wanted a method to act virtual, you had to explicitly
    preface it with the "virtual" command each time you used it.
    This proved to be error prone.

    In the new release, all methods are virtual by default.  If
    you invoke a method with a simple name, the most-specific
    method with that name will be invoked, regardless of your
    class scope:

        class Base {
            constructor {} {show}
            method show {} {puts "Base::show"}
        }
        class Derived {
            inherit Base
            constructor {} {show}
            method show {} {puts "Derived::show"}
        }

    The method "show" called out in the constructors for both of
    these classes is virtual.  When Base::constructor is executed
    it finds the most-specific "show" method and prints
    "Derived::show".  When Derived::constructor is executed, it
    finds the most-specific "show" method and prints "Derived::show"
    again.

    If you want to invoke a particular method, you have to scope
    it explicity:

        class Base {
            constructor {} {Base::show}
            method show {} {puts "Base::show"}
        }
        class Derived {
            inherit Base
            constructor {} {Derived::show}
            method show {} {puts "Derived::show"}
        }


 >> Within class methods/procs the "global" command now refers to
    variables within the class namespace.

    In the previous release, the "global" command was used to
    access variables at the global scope.  The "global" command
    now refers to variables that are "global" within the current
    namespace context.  Within the scope of a class, this refers
    to "global" class variables.  Note that common data members
    are global variables, but they can be accessed transparently,
    without any special "global" declaration.  You can also create
    ordinary global variables within a class, but you will have to
    declare them each time they are used with a "global" statement.
    The new scheme will allow classes to have their own private
    global variables (e.g., for interacting with widgets) without
    flooding the global namespace.

    If you really want to access a variable at the "::" global
    scope, use its complete path name:

        itcl::class Foo {
            method getenv {name} {
                global ::env
                return $env($name)
            }
        }


 >> "this" variable used to be included in every class scope

    In the previous release, each class scope included a separate
    "this" variable containing the object name.  There is now only
    one "this" variable, kept in the most-specific class scope.
    It can still be referenced as if it belongs to all classes,
    e.g., "Base::this", "Derived::this".

    This change is probably not important to most applications.
    But it did break my test suite, which expected to find many
    different "this" variables coming back from the "info" command.


 >> "this" variable now contains complete namespace path for the
      object access command

    This change will break many scripts written for mega-widgets.
    In the previous release, mega-widgets had a window name and an
    access command name that were interchangeable.  For example,
    you would create a widget ".dialog" and configure it using
    the ".dialog" command.  Inside of this widget there was a
    "this" variable containing the name ".dialog".

    In the current release, an object can exist in any namespace,
    so the complete namespace path is a part of the object's
    identity.  Instead of just ".dialog", the "this" variable will
    now contain a name like "::.dialog" or "::foo::.dialog".  But
    the window name is still just ".dialog".

    Scripts that used to use "$this" as a window name:

        wm title $this "Dialog"

    must now use the [incr Tk] "hull" component instead:

        wm title $itk_component(hull) "Dialog"

    If for some other reason you need the simple object name at the
    end of the namespace path, you can get at it using the
    "info namespace tail" command:

        set oldthis [info namespace tail $this]


 >> "#auto" generated names now start with lower-case letter

    In the previous release, "#auto" could be used in place of
    an object name to produce an automatically generated name:

        Toaster #auto -heat light

    The names were generated by adding a unique number onto the
    class name:  "Toaster0", "Toaster1", etc.

    The current release supports the same functionality, except
    that the names generated are guaranteed to start with a
    lowercase letter:  "toaster0", "toaster1", etc.  This helps
    out in the mega-widget arena, where window names must start
    with lowercase letters.


 >> "config" argument used to allow multiple default values

    The magic "config" argument used to allow multiple default
    values, which were simply concatenated into a single value
    before processing.  For example, in the previous release
    you could say:

        itcl_class Foo {
            method test {x y {config -foo 0 -bar 0}} {
                ...
            }
        }

    and if the "test" method was used without extra configuration
    arguments, they would default to "-foo 0 -bar 0".

    In the current release, you must make the default value for
    a "config" argument a single string:

        itcl::class Foo {
            method test {x y {config "-foo 0 -bar 0"}} {
                ...
            }
        }

 >> "info class" now acts "virtual"

    In the previous release, the "info class" command would report
    the current class context.  In a base class method, it would
    report the base class name, and in a derived class method, it
    would report the derived class name.  If you wanted to know
    the most-specific class for an object, you would have to use
    the "virtual" command explicitly:

        itcl_class Base {
            method whatAmI {} {
                return [virtual info class]
            }
        }

    The "info" command is now virtual by default, as long as an
    object context is present.  This means that you can drop the
    "virtual" command:

        itcl::class Base {
            method whatAmI {} {
                return [info class]
            }
        }

    If you really want to know the current class scope, use the
    "info context" command instead to query the current namespace
    context.

    If an object context is not present (i.e., in the body of a
    common class "proc"), the "info class" command reverts to
    the current class context, the same as the "info context" command.


 >> Library procedures "itcl_unload" and "itcl_reload" have been removed

    In the previous release, the library procedure "itcl_unload"
    provided a way of deleting a class.  You can now do the same
    thing using the "delete class" command:

        delete class Toaster

    This deletes the specified class, all derived classes, and all
    objects belonging to this class.  If autoloading is set up,
    you can reload a deleted class just by invoking its name.
    The old "itcl_reload" function is now trivial:

        proc itcl_reload {class} {
            delete class $class
            $class
        }


 >> Class definition no longer recognizes ordinary Tcl commands.

    As an undocumented "feature" of the previous release, you could
    include ordinary Tcl commands in the body of your class definition.
    For example:

        itcl_class Foo {
            ...
            if {$somevar} {
                public foo
            }
        }

    In the new release, only class definition commands are allowed
    within the body of a class definition.  You can, however, use Tcl
    commands outside of the class definition to modify the class
    definition as a string, and then define the class:

        set defn {
            method test {} {return "test"}
        }
        if {$somevar} {
            append defn "public variable foo"
        }
        class Foo $defn


 IMPROVEMENTS
--------------------------------------------------------------------------

 >> an object can be renamed by renaming its access command

    In the previous release, an object's identity was fixed when
    it was created.  In the new release, the object is tied
    directly to its access command.  If you rename the access
    command, you have renamed the object.  The "this" variable
    automatically keeps in sync with name changes.  If you delete
    the access command, you automatically delete the object.

        Toaster new -heat light
        rename new fred          << rename Toaster
        fred toast 2
        fred toast 1
        rename fred ""           << delete Toaster


 >> Bodies of methods, procs and public variables can be defined
    outside of the class definition, and can be redefined on the fly.

    In the previous release, all of the code related to a class was
    defined within the class definition.  This kept everything
    together in one place, but it made it difficult to get an overview
    of the class interface.

    In the new release, bodies can be defined outside of the class
    definition, perhaps in a separate file.  When debugging, the
    implementations can be fixed and sourced again and again, without
    having to delete existing objects and classes.

    Use the "itcl::body" command to redefine the body of a class
    method or proc.  Use "itcl::configbody" to redefine the configuration
    code associated with a public variable.  For example:

        itcl::class Toaster {
            constructor {args} {
                eval configure $args
            }
            destructor {
                if {$crumbs > 0} {
                    error "cannot destroy dirty toaster: clean first"
                }
            }

            method toast {nslices}
            method clean {}

            public variable heat 3
            protected variable crumbs 0
        }

        itcl::body Toaster::toast {nslices} {
            if {$nslices < 1 || $nslices > 2} {
                error "bad number of slices: should be 1 or 2"
            }
            set crumbs [expr $crumbs+$heat*$nslices]
            if {$crumbs >= 50} {
                puts stderr "== FIRE! FIRE! =="
            }
        }

        itcl::body Toaster::clean {} {
            set crumbs 0
        }

        itcl::configbody Toaster::heat {
            if {$heat < 1 || $heat > 5} {
                error "invalid setting \"$heat\": should be 1-5"
            }
        }

    If an argument list is specified in the class definition, then
    the same argument list must be used when the implementation is
    redefined.  The variable names can change, but the meaning of
    the arguments must be the same.  If you leave the argument
    list out of the class definition, or if you include the "args"
    argument, the argument list can change.


 >> C procedures can be integrated into class definitions

    Any method body that is specified as "@symbol" is treated as a
    reference to a C procedure with the symbolic name "symbol".
    Symbolic names are established by registering C procedures
    via the Itcl_RegisterC() procedure.  This is usually done
    when the interpreter starts up in the Tcl_AppInit() procedure:

        if (Itcl_RegisterC(interp, "foo", My_FooCmd) != TCL_OK) {
            return TCL_ERROR;
        }

    This registers a procedure My_FooCmd() with the symbolic name
    "foo".  It can be used as the implementation for a class method,
    proc, or bit of configuration code simply by specifying "@foo"
    in place of the Tcl code body.

    These C procedures are just like ordinary Tcl command handlers.
    They take the usual arguments:

        int My_FooCmd(ClientData cdata, Tcl_Interp *interp,
            int argc, char** argv)
        {
            ...
            return TCL_OK;
        }

    including the (argc,argv) arguments from the command line.  But
    before these procedures are invoked, the proper class scope is
    established so that object data members can be accessed as if
    they were ordinary variables via Tcl_GetVar() and Tcl_SetVar().

    Look at the [incr Tk] base class itk::Archetype as an example
    for integrating C code.


 >> "#auto" can be buried within an object name:  ".x.y.z.#auto"

    In the previous release, "#auto" was a keyword that could be
    used in place of an object name.  It can now be used as a
    part of the object name, making it easier to generate automatic
    names for mega-widgets.


 >> Every object now has built-in "configure" and "cget" methods
    that follow the Tk paradigm.  For [incr Tk] widgets, they follow
    the paradigm exactly.  The ordinary [incr Tcl] objects, the
    X11 resource values are missing.


 >> There is no longer a built-in "delete" method, so classes can
    define their own "delete" operations.

    Instead of "objName delete", use the new "delete object" command:

        Toaster fred -heat dark
        delete object fred


 >> All data members can be declared public, protected or private.

    Private data members can only be accessed in the class where
    they are defined.  Protected data members can be accessed in
    the defining class and all derived classes.  Public data members
    can be accessed like protected data members, but are also
    recognized as configuration options by the built-in "configure"
    and "cget" methods.


 >> In [incr Tk], options are now defined outside of the constructor,
    at the level of the class definition.


 >> In [incr Tk], configuration options belonging to components
    created in a base class can be added or removed in derived
    classes.

    The base classes "itk::Toplevel" and "itk::Widget" are now stripped
    down to the bare minimum options.  For example, if you want to add
    "-width" and "-height" options for the hull component, do this using
    the "itk_option" command in the body of the constructor:

        class MyWidget {
            inherit itk::Widget

            constructor {args} {
                itk_option add hull.widget hull.height
                ...
            }
        }

    Options can be added and removed on-the-fly during normal operation,
    but this is not recommended, since it could lead to a confusing
    interface.


 >> In [incr Tk], components can now be added or removed on-the-fly.

    The "itk_component" method now supports "add" and "delete"
    operations that are used to add/delete components.


 >> All [incr Tk] widgets can be destroyed like normal Tk widgets.

    If you destroy a component widget, for example, it will automatically
    remove itself from its parent via "itk_component delete".  Likewise,
    when a parent widget is destroyed, it will automatically destroy
    all component widgets.


 >> In [incr Tk], the "itk::Archetype::component" method now provides
    access to mega-widget components.

    In the previous [incr Tk] prototype, the "component" method had
    a different syntax and only supported query operations.  You can
    now access an internal component via the "component" method using
    its symbolic name:

        .dialog component hull configure -width 450 -height 500

    This example accesses the "hull" component of the ".dialog"
    mega-widget, and sets the width and height options.

==========================================================================
 ---------------------- RELEASE 2.0beta - 9/6/95 ------------------------
==========================================================================

9/8/95 (bug fix)
  Fixed menus to work properly within namespaces.  Menu library code
  now recognizes the proper namespace context for all "-menu" options.

9/8/95 (new feature)
  Added "winfo command name" option to report the scoped access command
  for a given window.

9/8/95 (configuration changes)
  - fixed "sed" invocation in iwidgets Makefile
  - added configuration guesses for Tadpole Sparcbook
  - added George Howlett's test for "gcc", so that "-fwritable-strings"
    is added even if gcc is masquerading as "cc"
  - fixed tcl/tk configure scripts to have default prefix "/usr/local/itcl"
    or wherever itclsh/itkwish is installed
  - fixed makefiles to use $(MAKE) instead of "make"

9/9/95 (bug fix)
  Protected references to obj->accessCmd to avoid seg faults when
  an object is being destroyed.

9/9/95 (new features)
  Changed the syntax of the "namespace" command:

    namespace name ?-local? ?-hidden val? ?-enforced val? ?--? ?commands?

  Flags now follow the namespace name, and the "commands" body is
  optional.  The "-hidden" option allows a namespace to be hidden
  during "info namespace all" queries.  The "-enforced" option turns
  command/variable enforcement on or off.

  Update "info namespaces all" command to allow for display of hidden
  namespaces:  info namespaces all ?-hidden? ?pattern?

9/10/95 (bug fix)
  Fixed "auto_mkindex" to work properly for procs defined within
  namespaces.  Added support for itcl::class, itcl::body and
  itcl::configbody as well.  Added tests for tclIndex file generation.

9/11/95 (configuration changes)
  Fixed makefiles to reference sources and libraries properly, so
  it should be possible to build different object trees for
  different platforms with "gmake".

9/13/95 (configuration changes)
  Added "AC_C_CROSS" to configure files, so configuration should work
  properly on Solaris 2.4.

9/13/95 (bug fix)
  Changed option configuration to work synchronously, and added
  "itk_initialize" command to initialize the configuration options
  for each mega-widget class.  The original behavior of handling
  option changes via "do-when-idle" has been removed.

9/13/95 (bug fix)
  Changed all structure members called "namespace" to "namesp".
  This allows the code to compile correctly under C++.

9/13/95 (configuration changes)
  - added support for "i[34]86:BSD/OS" in "config/config.guess"
  - fixed "test" target for iwidgets

9/13/95 (bug fix)
  Fixed "global" command and other places where namespace paths
  are parsed to allow for a single ":" in command/variable names.

9/13/95 (bug fix)
  Fixed a problem which caused class-based options to be lost when
  a widget class was defined within a proc.

9/14/95 (bug fix)
  Fixed class access command so that when it is deleted, it
  automatically destroys the class.  This also fixed a seg fault
  that occurred when an object's access command stomped on the
  class access command.

9/14/95 (enhancement)
  Fixed "scope" command and the @scope facility so that null strings
  can be passed around without all of the extra scoping info.

==========================================================================
 ----------------------- RELEASE 2.0b2 - 9/14/95 ------------------------
==========================================================================

9/15/95 (enhancement)
  Changed error messages reported when a class method/proc gets the
  wrong number of arguments to report the usage information, like:
  {wrong # args: should be "obj foo x y ?arg arg...?"}

9/18/95 (bug fix)
  Fixed a seg fault that occurred when the "cget" method was called
  with no args.

9/18/95 (bug fix)
  Fixed a bug that caused private variables in a base class to be
  uninitialized, even if an initial value was specified in the
  class definition.

9/22/95 (configuration changes)
  Added the "SHELL=/bin/sh" statement to the main makefile.  This
  fixes build problems on SGI machines.

10/9/95 (paradigm shift)
  Removed the implicit scoping from any facility that takes a command
  or variable name.  Implicit scoping made it difficult to pass a
  command string or variable name into a wrapper proc and yet preserve
  the scope that it came from.  All scoping is now explicit.  All
  commands and variables are interpreted in the global "::" scope
  unless they are wrapped in an "@scope" declaration.  Commands can
  be wrapped up like this:

      button .b -text "Push Me" -command [code .b configure -bg red]

  Variable names can be wrapped up like this:

      radiobutton .rb1 -text "Choice #1" -variable [scope mode] -value 1

  The "code" and "scope" commands wrap up strings with an "@scope"
  specification which preserves the namespace context.

10/17/95 (paradigm shift)
  Changed the "%C" option of the "bind" command to return a scoped
  command of the form "@scope namespace widget" that can be used to
  access the widget.  "%C" should be used instead of the usual "%W"
  window name when attempting to access the widget.  Bindings should
  be written like this:

      bind Entry <FocusIn>  {%C configure -bg white}
      bind Entry <FocusOut> {%C configure -bg gray}

  The command "%C" can be used to access the widget regardless which
  namespace it belongs to.

10/31/95 (enhancement)
  Fixed "unknown" command to support a general facility for adding
  unknown command handlers.  The "unknown_handler" proc is used to
  register new handlers.  Each time an unknown command is encountered,
  each of the handlers is invoked to attempt to handle the command.
  If a handler returns "-code continue", control passes to the next
  handler on the list.  Handlers are invoked in the order opposite to
  the way they were registered.  Extensions can use this facility to
  add their own handlers into the "unknown" scheme.

11/7/95 (enhancement)
  Added a "backward-compatibility" mode to [incr Tcl].  By default,
  widget names can now be used as access commands in any namespace,
  even if the widget access command exists in another namespace.
  This emulates the normal Tk behavior that widgets are global resources
  in the application that can be accessed anywhere.  This behavior can
  be disabled by setting the global variable "itcl_purist" to "1".  When
  this variable is set non-zero, care must be used to use "%C" or
  "[winfo command %W]" as an access command when the widget is used
  outside of the namespace that contains it.  From the standpoint of
  the object-oriented paradigm, the "purist" mode is better since it
  supports encapsulation.  The "backward-compatible" mode, however,
  allows [incr Tcl] to work better with existing Tk applications and
  extensions.

11/22/95 (bug fix and enhancement)
  Fixed the built-in "info" command for classes to include the "info
  classes" and "info objects" queries.  These were initially overlooked
  in a hard-wired list of "info" queries.

  Fixed the ensemble facility in general to support unknown options
  via an "@error" handler.  Any option registered with the name "@error"
  is treated as an error handler for the ensemble.  Arguments passed
  to the option include the ensemble name, the unknown option, and all
  remaining arguments.  For the built-in "info" command, the "@error"
  handler passes any unknown options to the usual Tcl "info" command,
  so all of the standard options are automatically available.

11/23/95 (bug fix)
  Fixed usual tkerror dialog to truncate error messages at 5 lines.
  The usage information returned by an ensemble or itcl object can
  be much longer, causing the "Stack Trace" button to get lost in
  many cases.

11/27/95 (bug fix)
  Removed the constructor/destructor from the list of public methods
  returned as usage information when an unknown method is encountered
  on an object.

12/2/95 (bug fix)
  Fixed error reporting for object construction.  Used to say
  something like "object constructor x y z" which made it look
  like a method invocation.  Now says "class object x y z" which
  looks more like the call that the user made to trigger the error.

12/4/95 (bug fix)
  Fixed class creation and object creation to avoid clobbering
  existing commands with new class/object access commands.  This
  prevents all hell from breaking loose when a command like
  "class set {...}" is invoked.

12/6/95 (configuration changes)
  Fixed parsing of namespace paths to use local storage instead of
  assuming that strings are writable.  This means that the
  "-fwritable-strings" option is no longer necessary for GCC and
  other compilers that store static strings in the program text
  segment.  This option has been removed from all "configure.in"
  files.  Linux users will no longer see core dumps on start-up.

12/8/95 (bug fix)
  Fixed "upvar" so that class data members can be accessed from
  another calling procedure.  This fixed a problem with using
  "parray" from within class methods.

12/9/95 (bug fix)
  Fixed "@scope" variable references so that variables can be created
  using "@scope" in any context and referenced later.

12/9/95 (feature change)
  Removed "-hidden" option from namespaces.  It seemed to complicated
  and quirky to explain on the man page.  Instead, all parser
  namespaces like "scope-parser" and "mkindex-parser" are grouped
  into a "::tcl" namespace.  This keeps them somewhat hidden even
  without any special treatment.

12/9/95 (minor enhancement)
  Added "array" command to class definition parser, so it can be
  used along with "set" to initialize common arrays.

12/10/95 (paradigm shift)
  Removed the "%C" pattern from the expansions recognized by the
  "bind" command, in favor of the following scheme:
    %W ........ name of widget receiving event
    %M ........ name of mega-widget containing widget receiving event
    %q ........ fully-qualified command name of widget receiving event
    %Q ........ fully-qualified command name of mega-widget receiving event
  Fixed "winfo command" to return the fully-qualified command name of
  a widget (instead of a scoped access command) to be consistent with
  the "%q" bind pattern.

12/10/95 (bug fix)
  Fixed Tk library code to use "%q" and "winfo command", so that the
  default widget behaviors will work even in "itcl_purist" mode.

12/11/95 (minor enhancement)
  Added "winfo megawidget" query, which will return the name of the
  mega-widget containing a specified component widget.  In order for
  this to work, a mega-widget package must use the procedure
  Itcl_SetMegaWidget() to register each component as it is added
  to a mega-widget.

12/12/95 (bug fix)
  Fixed Archetype base class to keep all options sorted in alphabetical
  order.  This way they can be reported back by the "configure" method
  in alphabetical order.  Options are now initialized by "itk_initialize"
  in alphabetical order as well.

12/12/95 (bug fix)
  Fixed the Archetype base class to register each component widget with
  Tk via Itk_SetMegaWidget().  This means that "winfo megawidget" and
  "%Q" can be used to reference the containing mega-widget for any component.

12/12/95 (bug fix)
  Fixed the "configure" method in the Archetype base class so that when
  an error is encountered while setting a configuration option, the option
  is set back to its previous value.

12/12/95 (bug fix)
  Fixed the "itk_component add" method to find access commands for
  components even if they are created in the global scope.  Components
  that are meant to be shared can be created using "uplevel #0".  The
  access command for this component will be installed in the global scope,
  and therefore available to all other namespaces.

  Syntactic sugar like a "-global" option would be nice, but references
  like $itk_component(...) must be substituted in the calling scope, and
  it is not possible to get these properly substituted and still maintain
  the boundaries around arguments.

12/12/95 (bug fix)
  Fixed Archetype base class to handle public/protected/private components
  properly.  The usual public/protected/private commands can be used in
  conjunction with "itk_component add" to set the protection level of a
  component.  The protection level affects the action of the "component"
  method.  Public components are reported in any namespace, and are
  accessible from any namespace.  Protected components are accessible
  within a base class and derived classes.  Private components are
  accessible only within the class where they are defined.  This feature
  can be used to keep unimportant components (such as frames) off of the
  component list that a client would see.

12/13/95 (enhancement)
  Added "usual" and "ignore" commands for processing component widget
  configuration options.  The "usual" command finds the usual code fragment
  for the widget class of the component, and executes it.  The command
  "itk::usual" can be used to register option code for new widget classes.

  The "ignore" command can be used to override previous "keep" and "rename"
  commands.  This is useful for removing options that the "usual" code
  keeps or renames.

  Fixed the "itk_component add" command so that if the option handling code
  is not specified, the "usual" command is invoked automatically.

12/13/95 (bug fix)
  Fixed the Archetype base class to handle the immutable Tk options
  properly.  Options like -class, -colormap, -screen and -visual can only
  be set at creation time.  The itk_option array is now properly
  initialized to report their creation value.

12/14/95 (bug fix)
  Fixed "itk_option add" command to report errors properly for unknown
  options.

12/14/95 (bug fix)
  Fixed "body" command to report errors properly for unknown functions.

12/14/95 (bug fix)
  Fixed a bug in the handling of TCL_GLOBAL_ONLY flag when looking up
  class variables.  Previously, this was ignored, so object-specific
  variables could be accessed in a "global" context by Tk widgets.
  This caused some strange behavior when object-specific variables
  were used in conjunction with widget options like "-textvariable".
  Tk widgets now properly interact with classes via global variables.

12/14/95 (bug fix)
  Fixed "auto_mkindex" to recognize procs within class definitions and
  add them to the "tclIndex" file.

12/15/95 (bug fix)
  Fixed "body" command to find functions only in the specified class.
  The bug caused a base class method to be redefined whenever a "body"
  command was issued for a derived class if the method was not declared
  in the derived class.  Made a corresponding fix to the "configbody"
  command for public variables.

12/15/95 (enhancement)
  Added the following commands to the class definition parser:  bind,
  scope and code.  This allows generic class bindings to be included
  in the body of a class definition.

12/15/95 (enhancement)
  Added "-clientdata" option in itk::Archetype base class so that
  all widgets will have an extra field for client data.  For application
  developers, this may come in handy.

12/16/95 (bug fix)
  Fixed the itk::Archetype base class so that if "itk_option add" or
  "itk_option remove" is called for ordinary class-based options before
  "itk_initialize" (which normally integrates them in) it does not cause
  a problem.

12/17/95 (bug fix)
  Fixed namespace resolution so that a command/variable with a
  specific path like "itk::body" will not be found in another
  imported namespace.  For the import list to be followed, the
  command name must be generic like "body".

12/19/95 (configuration changes)
  Changed from generic directories like "tcl" and "tk" to directory
  names with version numbers like "tcl7.4" and "tk4.0".

12/19/95 (bug fix)
  Changed names like "itcl_library" and "itcl_purist" to "itcl::library"
  and "itcl::purist".  This makes more sense in the documentation, since
  the underbar stuff is no longer needed with namespaces, and extension
  writers are discouraged from using it.

12/21/95 (bug fix)
  Changed handling of argument lists for functions with Tcl or C
  implementations.  All argument lists are now treated as Tcl
  argument specifications.  For Tcl implementations, this determines
  what arguments are available in the body of the procedure; for C
  implementations, this merely gives the intended usage information
  for the function (the C implementation may choose to ignore this
  and do something else).  This fix makes it easier to override
  C implementations with Tcl procedure bodies.

12/25/95 (bug fix)
  Split the usual TCL_GLOBAL_ONLY flag into two meanings:  TCL_GLOBAL_ONLY
  now means "a global variable in the global namespace", and ITCL_GLOBAL_VAR
  means "a global variable in the current namespace".  This enhancement
  fixes Tk (and many other extensions) which request global variables.
  A plain variable name together with TCL_GLOBAL_ONLY is now interpreted
  as an ordinary Tcl global variable, so the behavior is backward-compatible.
  A scoped variable reference will work properly with namespaces.  If
  extension writers get more ambitious, they can start using the
  ITCL_GLOBAL_VAR flag, which will make their extensions namespace-friendly.

12/26/95 (bug fix)
  Fixed "@scope" command so that extra arguments added at the end are
  kept as proper list elements when added to the command string.  This
  makes sure that boundaries around Tcl words are not lost when the
  scoped command is interpreted.

12/28/95 (minor enhancement)
  Added "config" method to the Archetype base class as an alias for
  the usual "configure" method.  Many Tk applications use "config"
  as an abbreviation for "configure", so this fix improves compatibility
  with other packages.

12/28/95 (bug fix)
  Fixed Itcl_SaveInterpState() and Itcl_RestoreInterpState() to
  properly save/restore the interp state even for commands like
  Tcl_SetCmd(), which are sloppy about setting the interpreter
  result.  This fixed bad memory references that were encountered
  in enforced namespaces.

12/28/95 (bug fix)
  Fixed Itcl_DeleteNamesp() to allow variable traces to be fired
  off properly when a namespace is destroyed.

12/30/95 (bug fix)
  Fixed the Archetype base class to do the "ignore" operation
  properly for mega-widget options.  A bug was causing a single
  "ignore" request not only to eliminate the desired option, but
  to eliminate options that were renamed to the "ignore" name
  as well.

==========================================================================
 ------------------------ RELEASE 2.0 - 12/31/95 ------------------------
==========================================================================
