NAME

       itcl_class - create a class of objects (obsolete)


SYNOPSIS

       itcl_class className {
           inherit baseClass ?baseClass...?
           constructor args ?init? body
           destructor body
           method name args body
           proc name args body
           public varName ?init? ?config?
           protected varName ?init?
           common varName ?init?
       }

       className objName ?args...?
       className #auto ?args...?
       className :: proc ?args...?

       objName method ?args...?

       Commands available within class methods/procs:
       global varName ?varName...?
       previous command ?args...?
       virtual command ?args...?
_________________________________________________________________


DESCRIPTION

       This  command  is considered obsolete, but is retained for
       backward-compatibility   with    earlier    versions    of
       [incr Tcl].   It  has  been replaced by the class command,
       which should be used for any new development.

       itcl_class className definition
              Provides the definition for a  class  named  class­
              Name.   If  className is already defined, then this
              command returns an error.  If the class  definition
              is successfully parsed, className becomes a command
              in the current namespace context, handling the cre­
              ation  of  objects  and  providing  access to class
              scope.  The class  definition  is  evaluated  as  a
              series  of  Tcl  statements  that  define  elements
              within the class.  In addition to  the  usual  com­
              mands,  the following class definition commands are
              recognized:

              inherit baseClass ?baseClass...?
                     Declares one or more base  classes,  causing
                     the  current  class to inherit their charac­
                     teristics.  Classes must have  been  defined

                     available to the auto-loading facility  (see
                     "AUTO-LOADING" below).  A single class defi­
                     nition can contain no more than one  inherit
                     command.

                     When  the same member name appears in two or
                     more  base  classes,  the  base  class  that
                     appears  first  in  the  inherit  list takes
                     precedence.  For example, if  classes  "Foo"
                     and  "Bar" both contain the member "x", then
                     the "inherit" statement:
                             inherit Foo Bar
                     allows "Foo::x" to be accessed simply as "x"
                     but forces "Bar::x" (and all other inherited
                     members named "x")  to  be  referenced  with
                     their explicit "class::member" name.

              constructor args ?init? body
                     Declares the argument list and body used for
                     the  constructor,  which  is   automatically
                     invoked   whenever  an  object  is  created.
                     Before the body is  executed,  the  optional |
                     init  statement  is  used to invoke any base |
                     class constructors that  require  arguments. |
                     Variables  in  the args specification can be |
                     accessed in  the  init  code  fragment,  and |
                     passed  to  base  class constructors.  After |
                     evaluating  the  init  statement,  any  base |
                     class  constructors  that have not been exe­ |
                     cuted are invoked without  arguments.   This |
                     ensures that all base classes are fully con­ |
                     structed before the constructor body is exe­ |
                     cuted.   If  construction is successful, the
                     constructor  always   returns   the   object
                     name-regardless   of   how   the   body   is
                     defined-and the object name becomes  a  com­
                     mand  in  the current namespace context.  If
                     construction  fails,  an  error  message  is
                     returned.

              destructor body
                     Declares  the  body used for the destructor,
                     which is automatically invoked  whenever  an
                     object  is  deleted.   If  the destructor is
                     successful, the object data is destroyed and
                     the object name is removed as a command from
                     the interpreter.  If destruction  fails,  an
                     error  message  is  returned  and the object
                     remains.

                     When an object is destroyed, all destructors |
                     in  a  class  hierarchy are invoked in order |
                     from most- to least-specific.  This  is  the |

                     "info heritage" command, and it  is  exactly |
                     the  opposite  of  the  default  constructor |
                     order.

              method name args body
                     Declares a method called name with an  argu­
                     ment list args and a body of Tcl statements.
                     A method is just like the usual  Tcl  "proc"
                     except  that  it  has  transparent access to |
                     object-specific variables, as well as common
                     variables.  Within the class scope, a method
                     can be invoked like any other command-simply
                     by  using  its  name.   Outside of the class
                     scope, the method name must be  prefaced  by
                     an  object  name.   Methods  in a base class
                     that are redefined in the current  class  or
                     hidden  by another base class can be explic­
                     itly scoped using the  "class::method"  syn­
                     tax.

              proc name args body
                     Declares a proc called name with an argument
                     list args and a body of Tcl  statements.   A
                     proc  is similar to a method, except that it
                     can be invoked without referring to  a  spe­
                     cific  object, and therefore has access only
                     to common variables-not  to  object-specific |
                     variables  declared with the public and pro­ |
                     tected commands.  Within the class scope,  a
                     proc  can  be  invoked  like  any other com­
                     mand-simply by using its name.  In any other
                     namespace context, the proc is invoked using
                     a  qualified  name  like  "className::proc".
                     Procs  in a base class that are redefined in
                     the current class, or hidden by another base
                     class, can also be accessed via their quali­
                     fied name.

              public varName ?init? ?config?
                     Declares a public  variable  named  varName.
                     Public  variables  are  visible  in  methods
                     within the scope  of  their  class  and  any
                     derived  class.   In  addition,  they can be
                     modified outside of the  class  scope  using
                     the  special  "config"  formal argument (see
                     "ARGUMENT LISTS" above).   If  the  optional
                     init is specified, it is used as the initial
                     value of the variable when a new  object  is
                     created.   If the optional config command is
                     specified, it is invoked whenever  a  public
                     variable is modified via the "config" formal
                     argument; if the config command  returns  an
                     error,  the  public variable is reset to its

                     handling the configuration returns an error.

              protected varName ?init?
                     Declares a protected variable named varName.
                     Protected  variables  are visible in methods
                     within the scope  of  their  class  and  any
                     derived  class,  but cannot be modified out­
                     side of the class scope.   If  the  optional
                     init is specified, it is used as the initial
                     value of the variable when a new  object  is
                     created.  Initialization forces the variable
                     to be a simple scalar  value;  uninitialized
                     variables, on the other hand, can be used as
                     arrays.  All objects have  a  built-in  pro­
                     tected  variable  named "this" which is ini­
                     tialized  to  the  instance  name  for   the
                     object.

              common varName ?init?
                     Declares  a  common  variable named varName.
                     Common  variables  are  shared   among   all
                     objects  in  a  class.   They are visible in
                     methods and procs  in  the  scope  of  their
                     class  and  any derived class, but cannot be
                     modified outside of the class scope.  If the
                     optional  init  is  specified, it is used as
                     the initial value of the variable.  Initial­
                     ization  forces  the variable to be a simple
                     scalar value;  uninitialized  variables,  on
                     the other hand, can be used as arrays.

                     Once a common variable has been declared, it
                     can be configured using  ordinary  Tcl  code
                     within  the class definition.  This facility
                     is particularly useful when the  initializa­
                     tion of the variable is non-trivial-when the
                     variable contains an array  of  values,  for
                     example:
                             itcl_class Foo {
                                  .
                                  .
                                 common boolean
                                 set boolean(true) 1
                                 set boolean(false) 0
                             }


CLASS USAGE

       When a class definition has been loaded (or made available
       to the auto-loader), the class name can be used as a  com­
       mand.

              Creates  a  new  object in class className with the
              name objName.  Remaining arguments  are  passed  to
              the  constructor.   If  construction is successful,
              the object name is returned and this name becomes a
              command  in  the current namespace context.  Other­
              wise, an error is returned.

       className #auto ?args...?
              Creates a new object in  class  className  with  an
              automatically  generated  name.   Names  are of the
              form className<number>, where the className part is |
              modified  to  start  with  a  lowercase letter.  In |
              class "Toaster", for example, the "#auto"  specifi­ |
              cation would produce names toaster0, toaster1, etc. |
              Remaining arguments are passed to the  constructor.
              If  construction  is successful, the object name is
              returned and this name becomes  a  command  in  the
              current  namespace context.  Otherwise, an error is
              returned.

       className  ::  proc ?args...?
              Used outside of the class scope to invoke  a  class
              proc named proc.  Class procs are like ordinary Tcl
              procs, except that they are executed in  the  scope
              of  the class and therefore have transparent access
              to common data members.

              Notice that, unlike any other  scope  qualifier  in |
              [incr Tcl],  the  "::" shown above is surrounded by |
              spaces.  This is unnecessary with the new namespace |
              facility, and is considered obsolete.  The capabil­ |
              ity is still supported, however, to  provide  back­ |
              ward-compatibility with earlier versions.


OBJECT USAGE

       objName method ?args...?
              Invokes  a  method  named  method to operate on the
              specified object.  Remaining arguments  are  passed
              to  the  method.  The method name can be "construc­
              tor", "destructor", any method  name  appearing  in
              the  class  definition,  or  any  of  the following
              built-in methods.


BUILT-IN METHODS

       objName isa className
              Returns non-zero if  the  given  className  can  be
              found in the object's heritage, and zero otherwise.

       objName delete
              Invokes the destructor associated with  an  object.
              If  the  destructor  is successful, data associated
              with the object is deleted and objName  is  removed

              empty string, regardless of the destructor body.

              The built-in delete method has been replaced by the |
              "delete  object"  command  in the global namespace, |
              and is  considered  obsolete.   The  capability  is |
              still  supported, however, to provide backward-com­ |
              patibility with earlier versions.

       objName info option ?args...?
              Returns information related to the class definition
              or  to  a  particular  object  named  objName.  The
              option parameter includes the following things,  as
              well  as  the  options  recognized by the usual Tcl
              "info" command:

              objName info class
                     Returns the name of the most-specific  class |
                     for object objName.

              objName info inherit
                     Returns  the  list  of  base classes as they
                     were defined in the "inherit" command, or an
                     empty  string  if  this  class  has  no base
                     classes.

              objName info heritage
                     Returns  the  current  class  name  and  the
                     entire  list  of  base  classes in the order
                     that they are traversed  for  member  lookup
                     and object destruction.

              objName info method ?methodName? ?-args? ?-body?
                     With  no  arguments,  this command returns a
                     list of all class methods.  If methodName is
                     specified, it returns information for a spe­
                     cific method.  If neither  of  the  optional
                     -args  or  -body  flags is specified, a com­
                     plete method definition  is  returned  as  a
                     list  of three elements including the method
                     name, argument list  and  body.   Otherwise,
                     the  requested information is returned with­
                     out the method name.  If the  methodName  is
                     not recognized, an empty string is returned.

              objName info proc ?procName? ?-args? ?-body?
                     With no arguments, this  command  returns  a
                     list  of  all  class  procs.  If procName is
                     specified, it returns information for a spe­
                     cific  proc.   If  neither  of  the optional
                     -args or -body flags is  specified,  a  com­
                     plete  proc definition is returned as a list
                     of three elements including the  proc  name,
                     argument  list  and  body.   Otherwise,  the

                     the  proc name.  If the procName is not rec­
                     ognized, an empty string is returned.

              objName info public ?varName? ?-init? ?-value?
                     ?-config?
                     With  no  arguments,  this command returns a
                     list of all public variables.  If varName is
                     specified, it returns information for a spe­
                     cific  public  variable.   If  none  of  the
                     optional  -init, -value or -config flags are
                     specified,  all  available  information   is
                     returned  as a list of four elements includ­
                     ing the variable name, initial  value,  cur­
                     rent   value,  and  configuration  commands.
                     Otherwise,  the  requested  information   is
                     returned  without the variable name.  If the
                     varName is not recognized, an  empty  string
                     is returned.

              objName info protected ?varName? ?-init? ?-value?
                     With  no  arguments,  this command returns a
                     list of all protected variables.  If varName
                     is  specified,  it returns information for a
                     specific protected variable.  If neither  of
                     the optional -init or -value flags is speci­
                     fied, all available information is  returned
                     as  a  list  of three elements including the
                     variable name,  initial  value  and  current
                     value.  Otherwise, the requested information
                     is returned without the variable  name.   If
                     the  varName  is  not  recognized,  an empty
                     string is returned.

              objName info common ?varName? ?-init? ?-value?
                     With no arguments, this  command  returns  a
                     list of all common variables.  If varName is
                     specified, it returns information for a spe­
                     cific  common  variable.   If neither of the
                     optional -init or -value flags is specified,
                     all  available  information is returned as a
                     list of three elements including  the  vari­
                     able  name, initial value and current value.
                     Otherwise,  the  requested  information   is
                     returned  without the variable name.  If the
                     varName is not recognized, an  empty  string
                     is returned.


OTHER BUILT-IN COMMANDS

       The following commands are also available within the scope
       of each class.  They cannot be accessed  from  outside  of
       the  class  as  proper  methods or procs; rather, they are
       useful inside the class when implementing its  functional­
       ity.

              Creates  a  link to one or more global variables in
              the current namespace  context.   Global  variables
              can also be accessed in other namespaces by includ­
              ing namespace qualifiers in varName.  This is  use­
              ful when communicating with Tk widgets that rely on
              global variables.

       previous command ?args...?
              Invokes command in the scope of the most  immediate
              base  class  (i.e.,  the  "previous" class) for the |
              object.  For classes using single inheritance, this
              facility can be used to avoid hard-wired base class
              references of  the  form  "class::command",  making
              code  easier to maintain.  For classes using multi­
              ple inheritance, the utility of  this  function  is
              dubious.  If the class at the relevant scope has no
              base class, an error is returned.

       virtual command ?args...?
              Invokes command in the scope of  the  most-specific |
              class  for  the object.  The methods within a class |
              are automatically virtual; whenever an  unqualified |
              method  name is used, it always refers to the most- |
              specific  implementation  for  that  method.   This |
              function  provides  a  way of evaluating code frag­ |
              ments in a base class that have access to the most- |
              specific  object  information.   It  is useful, for |
              example, for creating base classes that can capture |
              and  save  an object's state.  It inverts the usual |
              notions of  object-oriented  programming,  however, |
              and should therefore be used sparingly.


AUTO-LOADING

       Class  definitions need not be loaded explicitly; they can
       be loaded as needed by the usual Tcl  auto-loading  facil­
       ity.   Each  directory  containing  class definition files
       should have an accompanying "tclIndex" file.  Each line in
       this  file  identifies a Tcl procedure or [incr Tcl] class
       definition and the file where the definition can be found.

       For  example, suppose a directory contains the definitions
       for  classes  "Toaster"  and  "SmartToaster".   Then   the
       "tclIndex" file for this directory would look like:
              # Tcl autoload index file, version 2.0 for [incr Tcl]
              # This file is generated by the "auto_mkindex" command
              # and sourced to set up indexing information for one or
              # more commands.  Typically each line is a command that
              # sets an element in the auto_index array, where the
              # element name is the name of a command and the value is
              # a script that loads the command.

              set auto_index(::Toaster) "source $dir/Toaster.itcl"


              The auto_mkindex command is used to automatically
              generate "tclIndex" files.
       The  auto-loader  must  be made aware of this directory by
       appending the directory name to the "auto_path"  variable.
       When  this  is  in  place,  classes will be auto-loaded as
       needed when used in an application.


KEYWORDS

       class, object, object-oriented


Man(1) output converted with man2html