itcl User Commands - itcl_class






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  className.
          If  className  is  already  defined,  then this command
          returns an error.  If the class definition is  success-
          fully  parsed,  className  becomes  a  command  in  the
          current namespace context,  handling  the  creation  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 commands, the following class definition com-
          mands are recognized:

          inherit baseClass ?baseClass...?
               Declares one or more  base  classes,  causing  the
               current  class  to  inherit their characteristics.
               Classes must  have  been  defined  by  a  previous
               itcl_class  command,  or  must be available to the
               auto-loading facility (see "AUTO-LOADING"  below).
               A single class definition 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 when-
               ever 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 evaluat-  |
               ing the init statement, any base  class  construc-  |
               tors  that  have  not  been  executed  are invoked  |
               without arguments.  This  ensures  that  all  base  |
               classes are fully constructed before the construc-  |
               tor body is executed.  If construction is success-
               ful,  the  constructor  always  returns the object
               name-regardless 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  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  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  with  an  argument
               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 vari-  |
               ables, 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 pre-
               faced by an object name.  Methods in a base  class
               that  are redefined in the current class or hidden
               by another base class  can  be  explicitly  scoped
               using the "class::method" syntax.

          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 specific object, and there-
               fore has access only to common variables - not  to  |
               object-specific variables declared with the public  |
               and protected commands.  Within the class scope, a
               proc  can be invoked like any other command-simply
               by using its name.  In any  other  namespace  con-
               text,  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 qualified 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  addi-
               tion,  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  com-
               mand  returns  an  error,  the  public variable is
               reset to its value before configuration,  and  the
               method   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 outside 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; uninitial-
               ized variables, on the other hand, can be used  as
               arrays.   All  objects  have  a built-in protected
               variable named "this" which is initialized 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 ini-
               tial value of the variable.  Initialization forces
               the  variable  to be a simple scalar value; unini-
               tialized 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 initialization 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.

     className objName ?args...?
          Creates a new object in class className with  the  name
          objName.   Remaining  arguments  are passed to the con-
          structor.  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 #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"  specification  would  produce  |
          names toaster0, toaster1, etc.  Remaining arguments are
          passed to the constructor.  If construction is success-
          ful,  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 capability  |
          is  still  supported,  however,  to  provide  backward-  |
          compatibility with earlier versions.



OBJECT USAGE

     objName method ?args...?
          Invokes a method named method to operate on the  speci-
          fied  object.   Remaining  arguments  are passed to the
          method.  The method name can  be  "constructor",  "des-
          tructor", any method name appearing in the class defin-
          ition, 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 as  a  command
          from   the  interpreter.   Returns  the  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-compatibility  |
          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  destruc-
               tion.

          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  specific  method.   If
               neither  of  the  optional -args or -body flags is
               specified,  a  complete   method   definition   is
               returned as a list of three elements including the
               method name, argument list and  body.   Otherwise,
               the  requested information is returned without 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 specific proc.  If  nei-
               ther  of  the  optional  -args  or  -body flags is
               specified, a complete proc definition is  returned
               as  a  list  of  three elements including the proc
               name, argument  list  and  body.   Otherwise,  the
               requested information is returned without the proc
               name.  If the procName is not recognized, 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  specific  public  vari-
               able.   If  none  of the optional -init, -value or
               -config flags are specified, all available  infor-
               mation  is  returned  as  a  list of four elements
               including  the  variable  name,   initial   value,
               current value, and configuration commands.  Other-
               wise,  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 specified, all available  informa-
               tion  is  returned  as  a  list  of three elements
               including the variable  name,  initial  value  and
               current  value.  Otherwise, the requested informa-
               tion 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  specific  common  vari-
               able.   If neither of the optional -init or -value
               flags is specified, 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.


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 functionality.

     global varName ?varName...?
          Creates a link to one or more global variables  in  the
          current  namespace  context.  Global variables can also
          be accessed in other namespaces by including  namespace
          qualifiers in varName.  This is useful when communicat-
          ing 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 multiple 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 fragments 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 program-  |
          ming, 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 facility.
     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 "tclIn-
     dex" 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  append-
 ing  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