NAME
class - create a class of objects
SYNOPSIS
ccllaassss className {{
iinnhheerriitt baseClass ?baseClass...? ccoonnssttrruuccttoorr args ?init? body ddeessttrruuccttoorr body mmeetthhoodd name ?args? ?body? pprroocc name ?args? ?body? vvaarriiaabbllee varName ?init? ?config? ccoommmmoonn varName ?init? ppuubblliicc command ?arg arg ...? pprrootteecctteedd command ?arg arg ...? pprriivvaattee command ?arg arg ...? sseett varName ?value? aarrrraayy option ?arg arg ...? }}className objName ?arg arg ...?
objName method ?arg arg ...?className::proc ?arg arg ...?
DESCRIPTION
The fundamental construct in [[iinnccrr TTccll]] 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 containsinstances 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 thatare 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" areordinary 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 Tclcode 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 bbooddyy and ccoonnffiiggbbooddyy 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 "iittccll::::ffiinndd ccllaasssseess" command, and the list of objects, with the "iittccll::::ffiinndd oobbjjeeccttss" command.A class can be deleted using the "ddeelleettee ccllaassss" command. Individual
objects can be deleted using the "ddeelleettee oobbjjeecctt" command. CCLLAASSSS DDEEFFIINNIITTIIOONNSSccllaassss 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 anerror. 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: iinnhheerriitt baseClass ?baseClass...?Causes the current class to inherit characteristics from
one or more base classes. Classes must have been defined
by a previous ccllaassss command, or must be available to theauto-loading facility (see "AUTO-LOADING" below). A sin-
gle class definition can contain no more than one iinnhheerriitt
command. The order of baseClass names in the iinnhheerriitt list affectsthe 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 iinnhheerriitt list takes prece-
dence. For example, if classes "Foo" and "Bar" both con-
tain the member "x", and if another class has the
"iinnhheerriitt" 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". ccoonnssttrruuccttoorr 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 statementis 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 tobase 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 orderfrom least- to most-specific. This is exactly the oppo-
site of the order that classes are reported by the iinnffoo
hheerriittaaggee command. If construction is successful, the constructor alwaysreturns 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. ddeessttrruuccttoorr bodyDeclares 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 "iinnffoo hheerriittaaggee" command, and it is exactly the opposite of the default constructor order. mmeetthhoodd name ?args? ?body? Declares a method called name. When the method body isexecuted, 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 bbooddyy 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 forthe 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. pprroocc 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 bbooddyy 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 isinvoked 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. vvaarriiaabbllee 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 gglloobbaall command. If the optional init string is specified, it is used as the initial value of the variable when a new object iscreated. 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 executedwhenever 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 ccoonnffiiggbbooddyy
command. ccoommmmoonn 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 gglloobbaall command. They are automaticallyvisible 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 sseett and aarrrraayy commands and used as arrays. Once a common data member has been defined, it can be setusing sseett and aarrrraayy commands within the class definition.
This allows common data members to be initialized asarrays. For example: class Foo {
common boolean set boolean(true) 1set boolean(false) 0 } Note that if common data mem-
bers are initialized within the constructor, they getinitialized again and again whenever new objects are cre-
ated. ppuubblliicc command ?arg arg ...? pprrootteecctteedd command ?arg arg ...? pprriivvaattee command ?arg arg ...? These commands are used to set the protection level forclass members that are created when command is evaluated.
The command is usually mmeetthhoodd, pprroocc, vvaarriiaabbllee orccoommmmoonn, 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. CCLLAASSSS UUSSAAGGEEOnce 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 "##aauuttoo", that string is replaced
with an automatically generated name. Names have the formclassName
, where the className part is modified to start with a lowercase letter. In class "Toaster", for example, the
"##aauuttoo" specification would produce names like toaster0,
toaster1, etc. Note that "##aauuttoo" can be also be buried within
an object name: fileselectiondialog .foo.bar.#auto -background
red This would generate an object named ".foo.bar.fileselection-
dialog0". OOBBJJEECCTT UUSSAAGGEEOnce 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", anymethod name appearing in the class definition, or any of the
following built-in methods.
BBUUIILLTT-IINN MMEETTHHOODDSS
objName ccggeett ooppttiioonn Provides access to public variables as configuration options. This mimics the behavior of the usual "cget" operation for Tkwidgets. The option argument is a string of the form "-var-
Name", and this method returns the current value of the public variable varName. objName ccoonnffiigguurree ?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 isassigned 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 ccoonnffiigguurree method returns an error.objName iissaa className
Returns non-zero if the given className can be found in the
object's heritage, and zero otherwise. objName iinnffoo 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 iinnffoo ccllaassssReturns the name of the most-specific class for object
objName. objName iinnffoo iinnhheerriittReturns the list of base classes as they were defined in
the "iinnhheerriitt" command, or an empty string if this class
has no base classes.
objName iinnffoo hheerriittaaggeeReturns 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 iinnffoo ffuunnccttiioonn ?cmdName? ?-pprrootteeccttiioonn? ?-ttyyppee? ?-nnaammee?
?-aarrggss? ?-bbooddyy?
With no arguments, this command returns a list of allclass 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 iinnffoo vvaarriiaabbllee ?varName? ?-pprrootteeccttiioonn? ?-ttyyppee? ?-nnaammee?
?-iinniitt? ?-vvaalluuee? ?-ccoonnffiigg?
With no arguments, this command returns a list of allobject-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: theprotection 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 isincluded on this list. Flags can be used to request spe-
cific elements from this list. CCHHAAIINNIINNGG MMEETTHHOODDSS//PPRROOCCSSSometimes 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: 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: class Smart-
Toaster { 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" 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 arguments. It starts at the currentclass 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.AAUUTTOO-LLOOAADDIINNGG
Class definitions need not be loaded explicitly; they can be loaded asneeded 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 [[iinnccrr TTccll]] 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 "automkindex" 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
autoindex array, where the # element name is the name of a command and
the value is # a script that loads the command.
set autoindex(::Toaster) "source $dir/Toaster.itcl" set
autoindex(::SmartToaster) "source $dir/SmartToaster.itcl"
The aauuttoommkkiinnddeexx 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 "autopath" variable. When this is inplace, classes will be auto-loaded as needed when used in an applica-
tion. CC PPRROOCCEEDDUURREESSC procedures can be integrated into an [[iinnccrr TTccll]] 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 IIttccllRReegg-
iisstteerrCC(()). This is usually done in the TTccllAAppppIInniitt(()) procedure, whichis automatically called when the interpreter starts up. In the follow-
ing example, the procedure MyFooCmd() is registered with the symbolic name "foo". This procedure can be referenced in the bbooddyy command as "@foo". int TclAppInit(interp) TclInterp *interp; /* Interpreter for application. */ {if (ItclInit(interp) == TCLERROR) {
return TCLERROR;
} if (ItclRegisterC(interp, "foo", MyFooCmd) != TCLOK) {return TCLERROR;
} } C procedures are implemented just like ordinary Tcl commands.See the CCrrttCCoommmmaanndd man page for details. Within the procedure, class
data members can be accessed like ordinary variables using TTccllSSeett-
VVaarr(()), TTccllGGeettVVaarr(()), TTccllTTrraacceeVVaarr(()), etc. Class methods and procs can be executed like ordinary commands using TTccllEEvvaall(()). [[iinnccrr TTccll]] 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. KKEEYYWWOORRDDSSclass, object, object-oriented
itcl class(n)