itclextendedclass man page on Slackware

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

extendedclass(n)		  [incr Tcl]		      extendedclass(n)

______________________________________________________________________________

NAME
       itcl::extendedclass - create a extendedclass of objects

WARNING!
       This  is	 new  functionality  in	 [incr	Tcl]  where  the API can still
       change!!

SYNOPSIS
       itcl::extendedclass extendedclassName {
	   inherit baseExtendedclass ?baseExtendedclass...?
	   constructor args ?init? body
	   destructor body
	   public method name ?args? ?body?
	   protected method name ?args? ?body?
	   private method name ?args? ?body?
	   public proc name ?args? ?body?
	   protected proc name ?args? ?body?
	   private proc name ?args? ?body?
	   public variable varName ?init? ?config?
	   protected variable varName ?init? ?config?
	   private variable varName ?init? ?config?
	   public common varName ?init?
	   protected common varName ?init?
	   private common varName ?init?

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

	   <delegation info> see delegation page

	   <option info> see option page

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

       extendedclassName objName ?arg arg ...?

       objName method ?arg arg ...?

       extendedclassName::proc ?arg arg ...?
_________________________________________________________________

DESCRIPTION
       The fundamental construct in [incr Tcl] is  the	extendedclass  defini‐
       tion.   Each  extendedclass  acts as a template for actual objects that
       can be created.	The extendedclass 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 extend‐
       edclass	definition.   Each  object  also has a built-in variable named
       "this", which contains the name of  the	object.	  Extendedclasses  can
       also  have  "common"  data  members that are shared by all objects in a
       extendedclass.

       Two types of functions can be included in the extendedclass definition.
       "Methods"  are functions which operate on a specific object, and there‐
       fore have  access  to  both  "variables"	 and  "common"	data  members.
       "Procs"	are  ordinary  procedures  in the extendedclass 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  extendedclass	 can  only  be	defined	 once,	although the bodies of
       extendedclass 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  extended‐
       classes.	  The list of extendedclasses available in the current context
       can be queried using the "itcl::find extendedclasses" command, and  the
       list of objects, with the "itcl::find objects" command.

       A  extendedclass	 can  be deleted using the "delete extendedclass" com‐
       mand.  Individual objects can be deleted using the "delete object" com‐
       mand.

CLASS DEFINITIONS
       extendedclass extendedclassName definition
	      Provides the definition for a extendedclass named extendedclass‐
	      Name.  If the extendedclass extendedclassName already exists, or
	      if  a  command  called  extendedclassName	 exists in the current
	      namespace context,  this	command	 returns  an  error.   If  the
	      extendedclass  definition is successfully parsed, extendedclass‐
	      Name becomes a command in the current context, handling the cre‐
	      ation of objects for this extendedclass.

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

	      inherit baseExtendedclass ?baseExtendedclass...?
		     Causes  the current extendedclass to inherit characteris‐
		     tics from one or more  base  extendedclasses.   Extended‐
		     classes  must  have  been defined by a previous extended‐
		     class command, or must be available to  the  auto-loading
		     facility  (see "AUTO-LOADING" below).  A single extended‐
		     class definition can contain no  more  than  one  inherit
		     command.

		     The  order of baseExtendedclass names in the inherit list
		     affects the name resolution  for  extendedclass  members.
		     When  the	same  member  name appears in two or more base
		     extendedclasses,  the  base  extendedclass	 that  appears
		     first in the inherit list takes precedence.  For example,
		     if extendedclasses "Foo" and "Bar" both contain the  mem‐
		     ber  "x",	and if another extendedclass has the "inherit"
		     statement:

			    inherit Foo Bar

		     then the name "x" means "Foo::x".	Other  inherited  mem‐
		     bers  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 extendedclass constructors
		     that require arguments.  Variables in the args specifica‐
		     tion  can	be  accessed  in  the  init code fragment, and
		     passed to base extendedclass constructors.	 After	evalu‐
		     ating  the	 init  statement,  any base extendedclass con‐
		     structors that have not been executed are	invoked	 auto‐
		     matically	without arguments.  This ensures that all base
		     extendedclasses are fully	constructed  before  the  con‐
		     structor  body  is	 executed.   By	 default,  this scheme
		     causes constructors to be invoked in order from least- to
		     most-specific.  This is exactly the opposite of the order
		     that extendedclasses 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  extended‐
	      class  hierarchy	are  invoked in order from most- to least-spe‐
	      cific.  This is the order that the extendedclasses 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  exe‐
	      cuted,  it  will	have automatic access to object-specific vari‐
	      ables and common data members.

	      If the args list is specified, it establishes the usage informa‐
	      tion  for this method.  The body command can be used to redefine
	      the method body, but the args list must  match  this  specifica‐
	      tion.

	      Within the body of another extendedclass method, a method can be
	      invoked like any other command-simply by using its  name.	  Out‐
	      side of the extendedclass context, the method name must be pref‐
	      aced an object name, which provides the  context	for  the  data
	      that  it	manipulates.  Methods in a base extendedclass that are
	      redefined in the current extendedclass,  or  hidden  by  another
	      base  extendedclass,  can be qualified using the "extendedclass‐
	      Name::method" syntax.

       proc name ?args? ?body?
	      Declares a proc called name.  A proc is  an  ordinary  procedure
	      within  the extendedclass 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 informa‐
	      tion  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 extendedclass 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 "extendedclassName::proc".  Procs in a base
	      extendedclass that are redefined in the  current	extendedclass,
	      or  hidden  by  another base extendedclass, 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 extendedclass
	      methods.	They need not  be  declared  with  anything  like  the
	      global command.

	      If the optional init string is specified, it is used as the ini‐
	      tial value of the variable when a new object is  created.	  Ini‐
	      tialization  forces  the	variable  to be a simple 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 specified outside of the extendedclass
	      definition using the configbody command.

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

	      If the optional init string is specified, it is used as the ini‐
	      tial  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 extendedclass definition.
	      This allows common data members to  be  initialized  as  arrays.
	      For example:

		     itcl::extendedclass 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 extend‐
	      edclass 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,  com‐
	      mand can also be a script containing many different member defi‐
	      nitions, and the protection level will apply to all of the  mem‐
	      bers that are created.

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

       extendedclassName objName ?args...?
	      Creates a new object in extendedclass extendedclassName with the
	      name objName.  Remaining arguments are passed to the constructor
	      of the most-specific extendedclass.  This in turn	 passes	 argu‐
	      ments to base extendedclass constructors before invoking its own
	      body of commands.	 If  construction  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 allo‐
	      cated, 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
	      extendedclassName<number>,  where	 the extendedclassName part is
	      modified to start with a	lowercase  letter.   In	 extendedclass
	      "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.fileselectiondia‐
	      log0".

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 extendedclass 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 extendedclass
	      where  it was defined.  If the "config" code generates an error,
	      the variable is set back to its previous value, and the  config‐
	      ure method returns an error.

       objName isa extendedclassName
	      Returns  non-zero if the given extendedclassName 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 extendedclass definition.  The option parameter
	      includes the following things, as well as the options recognized
	      by the usual Tcl "info" command:

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

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

	      objName info heritage
		     Returns the current extendedclass	name  and  the	entire
		     list  of  base extendedclasses 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
		     extendedclass methods and procs.  If  cmdName  is	speci‐
		     fied,  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 extendedclass has a method or proc that	 is  redefined
       with the same name in a derived extendedclass.  This is a way of making
       the derived extendedclass  handle  the  same  operations	 as  the  base
       extendedclass,  but  with  its  own specialized behavior.  For example,
       suppose we have a Toaster extendedclass that looks like this:

	      itcl::extendedclass 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 extendedclass like SmartToaster that  redefines
       the  "toast"  method.   If  we  want  to	 access the base extendedclass
       method, we can qualify it with the base extendedclass  name,  to	 avoid
       ambiguity:

	      itcl::extendedclass SmartToaster {
		  inherit Toaster
		  method toast {nslices} {
		      if {$crumbs > 40} {
			  clean
		      }
		      return [Toaster::toast $nslices]
		  }
	      }

       Instead	of  hard-coding	 the  base  extendedclass name, we can use the
       "chain" command like this:

	      itcl::extendedclass SmartToaster {
		  inherit Toaster
		  method toast {nslices} {
		      if {$crumbs > 40} {
			  clean
		      }
		      return [chain $nslices]
		  }
	      }

       The chain command searches through the extendedclass  hierarchy	for  a
       slightly	 more  generic (base extendedclass) implementation of a method
       or proc, and invokes it with the specified arguments.  It starts at the
       current extendedclass context and searches through base extendedclasses
       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
       Extendedclass definitions need not be loaded explicitly;	 they  can  be
       loaded  as  needed by the usual Tcl auto-loading facility.  Each direc‐
       tory containing extendedclass definition files should have an  accompa‐
       nying  "tclIndex" file.	Each line in this file identifies a Tcl proce‐
       dure or [incr Tcl] extendedclass definition and the file where the def‐
       inition can be found.

       For example, suppose a directory contains the definitions for extended‐
       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	appending  the
       directory  name	to  the	 "auto_path" variable.	When this is in place,
       extendedclasses will be auto-loaded as needed when used in an  applica‐
       tion.

C PROCEDURES
       C procedures can be integrated into an [incr Tcl] extendedclass defini‐
       tion 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,	 extendedclass
       data  members  can  be  accessed like ordinary variables using Tcl_Set‐
       Var(), Tcl_GetVar(), Tcl_TraceVar(), etc.   Extendedclass  methods  and
       procs   can  be	executed  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.
       Extendedclasses can be developed quickly using Tcl  code	 to  implement
       the  bodies.  An entire application can be built and tested.  When nec‐
       essary, individual bodies can be implemented with  C  code  to  improve
       performance.

KEYWORDS
       extendedclass, object, object-oriented

itcl				      4.0		      extendedclass(n)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server Slackware

List of man pages available for Slackware

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