NAME

       class - create a class of objects


SYNOPSIS

       class className {
           inherit baseClass ?baseClass...?
           constructor args ?init? body
           destructor body
           method name ?args? ?body?
           proc name ?args? ?body?
           variable varName ?init? ?config?
           common varName ?init?

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

           set varName ?value?
           array option ?arg arg ...?
       }

       className objName ?arg arg ...?

       objName method ?arg arg ...?

       className::proc ?arg arg ...?
_________________________________________________________________


DESCRIPTION

       The fundamental construct in [incr Tcl] is the class defi­
       nition.  Each class acts as a template for actual  objects
       that  can  be  created.   The  class itself is a namespace
       which contains things common to all objects.  Each  object
       has its own unique bundle of data which contains instances
       of the "variables" defined in the class definition.   Each
       object  also  has  a built-in variable named "this", which
       contains the name of the object.  Classes  can  also  have
       "common"  data members that are shared by all objects in a
       class.

       Two types of functions can be included in the class  defi­
       nition.   "Methods"  are functions which operate on a spe­
       cific object, and therefore have  access  to  both  "vari­
       ables"  and  "common"  data members.  "Procs" are ordinary
       procedures in the class namespace, and only have access to
       "common" data members.

       If  the  body of any method or proc starts with "@", it is
       treated as the symbolic name for a  C  procedure.   Other­
       wise,  it  is treated as a Tcl code script.  See below for
       details on registering and using C procedures.

       class methods and procs can be defined again and again for
       interactive debugging.  See the body and  configbody  com­
       mands for details.

       Each  namespace can have its own collection of objects and
       classes.  The list of classes  available  in  the  current
       context can be queried using the "itcl::find classes" com­
       mand, and  the  list  of  objects,  with  the  "itcl::find
       objects" command.

       A  class  can be deleted using the "delete class" command.
       Individual  objects  can  be  deleted  using  the  "delete
       object" command.


CLASS DEFINITIONS

       class className definition
              Provides  the  definition  for a class named class­
              Name.  If the class className already exists, or if
              a  command  called  className exists in the current
              namespace context, this command returns  an  error.
              If  the  class  definition  is successfully parsed,
              className becomes a command in the current context,
              handling the creation of objects for this class.

       The  class  definition  is  evaluated  as  a series of Tcl
       statements that define elements  within  the  class.   The
       following class definition commands are recognized:

              inherit baseClass ?baseClass...?
                     Causes  the current class to inherit charac­
                     teristics from one  or  more  base  classes.
                     Classes must have been defined by a previous
                     class command, or must be available  to  the
                     auto-loading  facility  (see  "AUTO-LOADING"
                     below).  A single class definition can  con­
                     tain no more than one inherit command.

                     The  order of baseClass names in the inherit
                     list affects the name resolution  for  class
                     members.   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", and
                     if another class has  the  "inherit"  state­
                     ment:
                     inherit Foo Bar
              then  the name "x" means "Foo::x".  Other inherited
              members named "x" must  be  referenced  with  their
              explicit name, like "Bar::x".

                     Declares  the  args  argument  list and body
                     used for the constructor, which is automati­
                     cally 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  automatically   without
                     arguments.    This  ensures  that  all  base
                     classes are  fully  constructed  before  the
                     constructor  body  is executed.  By default,
                     this  scheme  causes  constructors   to   be
                     invoked  in  order  from least- to most-spe­
                     cific.  This is exactly the opposite of  the
                     order  that classes are reported by the info
                     heritage command.

                     If construction is successful, the construc­
                     tor  always  returns the object name-regard­
                     less of how  the  body  is  defined-and  the
                     object name becomes a command 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  when   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  its class hierarchy are invoked in order
                     from most- to least-specific.  This  is  the
                     order  that  the classes are reported by the
                     "info heritage" command, and it  is  exactly
                     the  opposite  of  the  default  constructor
                     order.

              method name ?args? ?body?
                     Declares a method  called  name.   When  the
                     method  body is executed, it will have auto­
                     matic access  to  object-specific  variables
                     and common data members.

                     lishes  the  usage  information   for   this
                     method.   The  body  command  can be used to
                     redefine the method body, but the args  list
                     must match this specification.

                     Within  the  body of another class method, a
                     method can be invoked like  any  other  com­
                     mand-simply  by  using its name.  Outside of
                     the class context, the method name  must  be
                     prefaced  an object name, which provides the
                     context for the data  that  it  manipulates.
                     Methods  in  a base class that are redefined
                     in the current class, or hidden  by  another
                     base  class,  can  be  qualified  using  the
                     "className::method" syntax.

              proc name ?args? ?body?
                     Declares a proc called name.  A proc  is  an
                     ordinary  procedure  within the class names­
                     pace.  Unlike a method, a  proc  is  invoked
                     without  referring  to  a  specific  object.
                     When the proc body is executed, it will have
                     automatic  access  only  to common data mem­
                     bers.

                     If the args list  is  specified,  it  estab­
                     lishes  the usage information for this proc.
                     The body command can be used to redefine the
                     proc body, but the args list must match this
                     specification.

                     Within the body of another class  method  or
                     proc,  a  proc can be invoked like any other
                     command-simply by using its  name.   In  any
                     other namespace context, the proc is invoked
                     using  a   qualified   name   like   "class­
                     Name::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 qualified name.

              variable varName ?init? ?config?
                     Defines an  object-specific  variable  named
                     varName.   All object-specific variables are
                     automatically available  in  class  methods.
                     They need not be declared with anything like
                     the global command.

                     If the optional init string is specified, it
                     is used as the initial value of the variable
                     when a new object is  created.   Initializa­
                     tion  forces  the  variable  to  be a simple
                     scalar value;  uninitialized  variables,  on

                     structor and used as arrays.

                     The optional config script is  only  allowed
                     for  public  variables.   If specified, this
                     code fragment is executed whenever a  public
                     variable  is  modified by the built-in "con­
                     figure" method.  The config script can  also
                     be specified outside of the class definition
                     using the configbody command.

              common varName ?init?
                     Declares a common  variable  named  varName.
                     Common  variables reside in the class names­
                     pace and are shared by all objects belonging
                     to  the  class.   They  are just like global
                     variables, except  that  they  need  not  be
                     declared  with  the  usual  global  command.
                     They are automatically visible in all  class
                     methods and procs.

                     If the optional init string is specified, it
                     is used as the initial value  of  the  vari­
                     able.  Initialization forces the variable to
                     be  a  simple  scalar  value;  uninitialized
                     variables,  on  the  other  hand, can be set
                     with subsequent set and array  commands  and
                     used as arrays.

                     Once  a common data member has been defined,
                     it can be set using set and  array  commands
                     within  the  class  definition.  This allows
                     common data members  to  be  initialized  as
                     arrays.  For example:
                     class Foo {
                         common boolean
                         set boolean(true) 1
                         set boolean(false) 0
                     }
              Note  that  if  common data members are initialized
              within the constructor, they get initialized  again
              and again whenever new objects are created.

              public command ?arg arg ...?

              protected command ?arg arg ...?

              private command ?arg arg ...?
                     These  commands  are used to set the protec­
                     tion level for class members that  are  cre­
                     ated when command is evaluated.  The command
                     is usually method, proc, variable  orcommon,
                     and  the remaining arg's complete the member
                     definition.  However, command can also be  a

                     initions,  and  the  protection  level  will
                     apply  to  all  of the members that are cre­
                     ated.


CLASS USAGE

       Once a class has been defined, the class name can be  used
       as a command to create new objects belonging to the class.

       className objName ?args...?
              Creates a new object in class  className  with  the
              name  objName.   Remaining  arguments are passed to
              the constructor of the most-specific  class.   This
              in turn passes arguments to base class constructors
              before invoking its own body of commands.  If  con­
              struction  is  successful, a command called objName
              is created in the current  namespace  context,  and
              objName  is  returned  as the result of this opera­
              tion.  If an error is encountered during  construc­
              tion,  the destructors are automatically invoked to
              free any resources that have  been  allocated,  the
              object is deleted, and an error is returned.

              If objName contains the string "#auto", that string
              is replaced with an automatically  generated  name.
              Names  have  the  form className<number>, where the
              className part is modified to start with  a  lower­
              case  letter.  In class "Toaster", for example, the
              "#auto"  specification  would  produce  names  like
              toaster0,  toaster1, etc.  Note that "#auto" can be
              also be buried within an object name:
              fileselectiondialog .foo.bar.#auto -background red
       This would generate an object  named  ".foo.bar.fileselec­
       tiondialog0".


OBJECT USAGE

       Once  an  object  has been created, the object name can be
       used as a command to invoke methods that  operate  on  the
       object.

       objName method ?args...?
              Invokes  a  method  named method on an object named
              objName.  Remaining arguments  are  passed  to  the
              argument  list for the method.  The method name can
              be "constructor",  "destructor",  any  method  name
              appearing  in  the  class definition, or any of the
              following built-in methods.


BUILT-IN METHODS

       objName cget option
              Provides access to public variables  as  configura­
              tion  options.   This  mimics  the  behavior of the

              argument  is  a  string of the form "-varName", and
              this method returns the current value of the public
              variable varName.

       objName configure ?option? ?value option value ...?
              Provides  access  to public variables as configura­
              tion options.  This  mimics  the  behavior  of  the
              usual  "configure"  operation for Tk widgets.  With
              no arguments, this method returns a list  of  lists
              describing  all of the public variables.  Each list
              has three elements:  the variable name, its initial
              value and its current value.

              If a single option of the form "-varName" is speci­
              fied, then this method returns the information  for
              that one variable.

              Otherwise,    the    arguments   are   treated   as
              option/value pairs assigning new values  to  public
              variables.   Each  variable  is  assigned  its  new
              value, and if it has any "config"  code  associated
              with it, it is executed in the context of the class
              where it was defined.  If the "config" code  gener­
              ates an error, the variable is set back to its pre­
              vious value, and the configure  method  returns  an
              error.

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

       objName info option ?args...?
              Returns  information related to a particular object
              named objName, or to  its  class  definition.   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.

                     ?-type?  ?-name? ?-args? ?-body?
                     With no arguments, this  command  returns  a
                     list  of  all  class  methods and procs.  If
                     cmdName is specified, it returns information
                     for  a specific method or proc.  If no flags
                     are specified, this command returns  a  list
                     with the following elements:  the protection
                     level, the type (method/proc), the qualified
                     name, the argument list and the body.  Flags
                     can be used  to  request  specific  elements
                     from this list.

              objName  info  variable  ?varName?  ?-protection?
                     ?-type? ?-name? ?-init? ?-value? ?-config?
                     With  no  arguments,  this command returns a
                     list of all  object-specific  variables  and
                     common  data  members.  If varName is speci­
                     fied, it returns information for a  specific
                     data  member.   If  no  flags are specified,
                     this command returns a list with the follow­
                     ing  elements:   the  protection  level, the
                     type (variable/common), the qualified  name,
                     the  initial  value,  and the current value.
                     If varName is a public variable,  the  "con­
                     fig"  code  is included on this list.  Flags
                     can be used  to  request  specific  elements
                     from this list.


CHAINING METHODS/PROCS

       Sometimes  a base class has a method or proc that is rede­
       fined with the same name in a derived class.   This  is  a
       way of making the derived class handle the same operations
       as the base class, but with its own specialized  behavior.
       For  example,  suppose  we have a Toaster class that looks
       like this:
              class Toaster {
                  variable crumbs 0
                  method toast {nslices} {
                      if {$crumbs > 50} {
                          error "== FIRE! FIRE! =="
                      }
                      set crumbs [expr $crumbs+4*$nslices]
                  }
                  method clean {} {
                      set crumbs 0
                  }
              }
       We might create another class like SmartToaster that rede­
       fines  the  "toast" method.  If we want to access the base
       class method, we can qualify it with the base class  name,
       to avoid ambiguity:
              class SmartToaster {

                  method toast {nslices} {
                      if {$crumbs > 40} {
                          clean
                      }
                      return [Toaster::toast $nslices]
                  }
              }
       Instead of hard-coding the base class name, we can use the
       "chain" command like this:
              class SmartToaster {
                  inherit Toaster
                  method toast {nslices} {
                      if {$crumbs > 40} {
                          clean
                      }
                      return [chain $nslices]
                  }
              }
       The chain command searches through the class hierarchy for
       a  slightly  more generic (base class) implementation of a
       method or proc, and invokes it with  the  specified  argu­
       ments.   It  starts  at  the  current  class  context  and
       searches through base classes in the order that  they  are
       reported  by  the  "info  heritage"  command.   If another
       implementation is not found, this command does nothing and
       returns the null string.


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"
              set auto_index(::SmartToaster) "source $dir/SmartToaster.itcl"

              The auto_mkindex command is used to automatically
              generate "tclIndex" files.
       The  auto-loader  must  be made aware of this directory by

       When  this  is  in  place,  classes will be auto-loaded as
       needed when used in an application.


C PROCEDURES

       C procedures can be integrated into  an  [incr Tcl]  class
       definition  to  implement methods, procs, and the "config"
       code for public variables.  Any body that starts with  "@"
       is treated as the symbolic name for a C procedure.

       Symbolic  names  are established by registering procedures
       via  Itcl_RegisterC().   This  is  usually  done  in   the
       Tcl_AppInit()  procedure,  which  is  automatically called
       when the interpreter starts up.  In the following example,
       the  procedure My_FooCmd() is registered with the symbolic
       name "foo".  This procedure can be referenced in the  body
       command as "@foo".
              int
              Tcl_AppInit(interp)
                  Tcl_Interp *interp;     /* Interpreter for application. */
              {
                  if (Itcl_Init(interp) == TCL_ERROR) {
                      return TCL_ERROR;
                  }

                  if (Itcl_RegisterC(interp, "foo", My_FooCmd) != TCL_OK) {
                      return TCL_ERROR;
                  }
              }
       C  procedures  are implemented just like ordinary Tcl com­
       mands.  See the CrtCommand man page for  details.   Within
       the  procedure,  class  data  members can be accessed like
       ordinary  variables  using   Tcl_SetVar(),   Tcl_GetVar(),
       Tcl_TraceVar(),  etc.  Class methods and procs can be exe­
       cuted like ordinary commands using Tcl_Eval().  [incr Tcl]
       makes  this  possible by automatically setting up the con­
       text before executing the C procedure.

       This scheme provides a natural  migration  path  for  code
       development.   Classes  can be developed quickly using Tcl
       code to implement the bodies.  An entire  application  can
       be  built  and  tested.  When necessary, individual bodies
       can be implemented with C code to improve performance.


KEYWORDS

       class, object, object-oriented


Man(1) output converted with man2html