class man page on SuSE

Man page or keyword search:  
man Server   14857 pages
apropos Keyword Search (all sections)
Output format
SuSE logo
[printable version]

class(n)			  [incr Tcl]			      class(n)

______________________________________________________________________________

NAME
       class - create a class of objects

SYNOPSIS
       itcl::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 definition.  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 definition.	"Meth‐
       ods"  are  functions  which operate on a specific object, and therefore
       have access to both "variables" 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.  Otherwise, it is treated as a Tcl
       code script.  See below for details on registering and using  C	proce‐
       dures.

       A  class can only be defined once, although the bodies of class methods
       and procs can be defined again and  again  for  interactive  debugging.
       See the body and configbody commands 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"  command,  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 className.	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,	class‐
	      Name becomes a command in the current context, handling the cre‐
	      ation 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 com‐
       mands are recognized:

	      inherit baseClass ?baseClass...?
		     Causes the current class to inherit characteristics  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 sin‐
		     gle class definition can contain 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 prece‐
		     dence.  For example, if classes "Foo" and "Bar" both con‐
		     tain the  member  "x",  and  if  another  class  has  the
		     "inherit" statement:
		     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".

	      constructor args ?init? body
		     Declares the args 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
		     executed 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-specific.  This is exactly the	 oppo‐
		     site  of  the order that classes are reported by the info
		     heritage command.

		     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 cur‐
		     rent  namespace context.  If construction fails, an error
		     message is returned.

	      destructor body
		     Declares the body used for the destructor, which is auto‐
		     matically	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-spe‐
		     cific.   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 automatic  access  to  object-spe‐
		     cific variables and common data members.

		     If	 the  args list is specified, it establishes 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 command-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  "class‐
		     Name::method" syntax.

	      proc name ?args? ?body?
		     Declares  a proc called name.  A proc is an ordinary pro‐
		     cedure within the class namespace.	 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 members.

		     If	 the  args list is specified, it establishes 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 "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.

	      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.  Initialization forces the variable to be a sim‐
		     ple scalar value; uninitialized variables, on  the	 other
		     hand,  can	 be  set  within  the  constructor 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
		     "configure" method.  The config script can also be speci‐
		     fied outside of the class definition using the configbody
		     command.

	      common varName ?init?
		     Declares  a  common variable named varName.  Common vari‐
		     ables reside in the class namespace 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 variable.	 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:
		     itcl::class Foo {
			 common boolean
			 set boolean(true) 1
			 set boolean(false) 0
		     }
	      Note that if common data members are initialized within the con‐
	      structor, 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 protection level for
		     class members that are created 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 script containing many
		     different member definitions, and	the  protection	 level
		     will apply to all of the members that are created.

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 operation.	 If an	error  is  encountered	during
	      construction,  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 lowercase 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.fileselectiondialog0".

OBJECT USAGE
       Once  an object has been created, the object name can be used as a com‐
       mand 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  configuration  options.
	      This  mimics  the	 behavior of the usual "cget" operation for Tk
	      widgets.	The option argument is a string	 of  the  form	"-var‐
	      Name",  and  this method returns the current value of the public
	      variable varName.

       objName configure ?option? ?value option value ...?
	      Provides access to public variables  as  configuration  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 specified, 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  associ‐
	      ated  with  it, it is executed in the context of the class where
	      it was defined.  If the "config" code generates  an  error,  the
	      variable	is  set	 back to its previous 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 obj‐
	      Name, 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.

	      objName  info  function  ?cmdName? ?-protection? ?-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 specified, it returns information for  a  spe‐
		     cific  data member.  If no flags are specified, this com‐
		     mand returns a list with  the  following  elements:   the
		     protection	 level, the type (variable/common), the quali‐
		     fied name, the initial value, and the current value.   If
		     varName  is  a  public  variable,	the  "config"  code is
		     included on this list.  Flags can be used to request spe‐
		     cific elements from this list.

CHAINING METHODS/PROCS
       Sometimes  a base class has a method or proc that is redefined 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:
	      itcl::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 redefines the
       "toast" method.	If we want to access the base  class  method,  we  can
       qualify it with the base class name, to avoid ambiguity:
	      itcl::class SmartToaster {
		  inherit Toaster
		  method toast {nslices} {
		      if {$crumbs > 40} {
			  clean
		      }
		      return [Toaster::toast $nslices]
		  }
	      }
       Instead of hard-coding the base class name, we can use the "chain" com‐
       mand like this:
	      itcl::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 arguments.	  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 facility.  Each directory contain‐
       ing 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 direc‐
       tory 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 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.

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_Reg‐
       isterC().   This	 is usually done in the Tcl_AppInit() procedure, which
       is automatically called when the interpreter starts up.	In the follow‐
       ing  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 commands.  See the
       CrtCommand man page for details.	 Within the procedure, class data mem‐
       bers  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 context 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  bod‐
       ies.   An  entire application can be built and tested.  When necessary,
       individual bodies can be implemented with C  code  to  improve  perfor‐
       mance.

KEYWORDS
       class, object, object-oriented

itcl								      class(n)
[top]

List of man pages available for SuSE

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net