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 class
Name. If className is already defined, then this
command returns an error. If the class definition
is successfully parsed, className becomes a command
in the current namespace context, handling the cre
ation 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 com
mands, the following class definition commands are
recognized:
inherit baseClass ?baseClass...?
Declares one or more base classes, causing
the current class to inherit their charac
teristics. Classes must have been defined
available to the auto-loading facility (see
"AUTO-LOADING" below). A single class defi
nition 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 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 exe |
cuted are invoked without arguments. This |
ensures that all base classes are fully con |
structed before the constructor body is exe |
cuted. If construction is successful, the
constructor always returns the object
name-regardless of how the body is
defined-and the object name becomes a com
mand 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 |
"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 argu
ment 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
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 prefaced by
an object name. Methods in a base class
that are redefined in the current class or
hidden by another base class can be explic
itly scoped using the "class::method" syn
tax.
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 spe
cific object, and therefore has access only
to common variables-not to object-specific |
variables declared with the public and pro |
tected commands. Within the class scope, a
proc can be invoked like any other com
mand-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 quali
fied 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 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 command returns an
error, the public variable is reset to its
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 out
side 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 pro
tected variable named "this" which is ini
tialized 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. Initial
ization 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 ordinary Tcl code
within the class definition. This facility
is particularly useful when the initializa
tion 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.
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" specifi |
cation 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. 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 capabil |
ity is still supported, however, to provide back |
ward-compatibility with earlier versions.
OBJECT USAGE
objName method ?args...?
Invokes a method named method to operate on the
specified object. Remaining arguments are passed
to the method. The method name can be "construc
tor", "destructor", 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
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-com |
patibility 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 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 spe
cific method. If neither of the optional
-args or -body flags is specified, a com
plete method definition is returned as a
list of three elements including the method
name, argument list and body. Otherwise,
the requested information is returned with
out 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 spe
cific proc. If neither of the optional
-args or -body flags is specified, a com
plete proc definition is returned as a list
of three elements including the proc name,
argument list and body. Otherwise, the
the proc name. If the procName is not rec
ognized, 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 spe
cific 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 includ
ing the variable name, initial value, cur
rent 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 speci
fied, 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 spe
cific 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 vari
able 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 functional
ity.
Creates a link to one or more global variables in
the current namespace context. Global variables
can also be accessed in other namespaces by includ
ing namespace qualifiers in varName. This is use
ful 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 multi
ple 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 frag |
ments 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 facil
ity. 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 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"
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
Man(1) output converted with
man2html