Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

RedHat 9 (Linux i386) - man page for itcl_class (redhat section n)

itcl_class(n)				    [incr Tcl]				    itcl_class(n)

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 ear-
       lier 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, han-
	      dling the creation of objects and providing access to class scope.  The class defi-
	      nition  is  evaluated as a series of Tcl statements that define elements within the
	      class.  In addition to the usual commands, the following class definition  commands
	      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 auto-
		     matically	invoked  whenever  an object is created.  Before the body is exe-
		     cuted, the optional init statement is used to invoke  any	base  class  con-
		     structors	that  require arguments.  Variables in the args specification can
		     be accessed in the init code fragment, and passed to  base  class	construc-
		     tors.  After evaluating the init statement, any base class constructors that
		     have not been executed are invoked without arguments.  This ensures that all
		     base  classes are fully constructed before the constructor body is executed.
		     If construction is successful, 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 variables, as  well	as  common  vari-
		     ables.   Within the class scope, a method can be invoked like any other com-
		     mand-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 rede-
		     fined 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 therefore 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 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 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 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 spec-
		     ified,  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  when-
		     ever  a public variable is modified via the "config" formal argument; if the
		     config command 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  visi-
		     ble  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;
		     uninitialized  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  initial
		     value  of	the  variable.	Initialization 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 ordi-
		     nary Tcl code within the class definition.  This  facility  is  particularly
		     useful when the initialization of the variable is non-trivial-when the vari-
		     able 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 command.

       className objName ?args...?
	      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" speci-
	      fication	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.  Other-
	      wise, 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 specified object.  Remaining argu-
	      ments are passed to the method.  The method name can  be	"constructor",	"destruc-
	      tor",  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 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" com-
		     mand, 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 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 proc-
		     Name is specified, it returns information for a specific proc.   If  neither
		     of  the  optional -args or -body flags is specified, a complete proc defini-
		     tion is returned as a list of three elements including the proc name,  argu-
		     ment  list and body.  Otherwise, the requested information is returned with-
		     out 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 variable.
		     If  none  of  the optional -init, -value or -config flags are specified, all
		     available information is returned as a list of four elements  including  the
		     variable  name,  initial  value,  current 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 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.

	      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 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  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 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 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 meth-
	      ods 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 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  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 "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 com-
       mands.	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 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

itcl					       3.0				    itcl_class(n)


All times are GMT -4. The time now is 08:49 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password