itcl User Commands - itcl_class
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 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, handling the creation 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 commands, the following class definition com-
mands 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 automatically invoked when-
ever 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 evaluat- |
ing the init statement, any base class construc- |
tors that have not been executed are invoked |
without arguments. This ensures that all base |
classes are fully constructed before the construc- |
tor body is executed. If construction is success-
ful, 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 vari- |
ables, 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 pre-
faced by an object name. Methods in a base class
that are redefined 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 there-
fore 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 con-
text, 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 addi-
tion, 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 com-
mand 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 visible 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; uninitial-
ized 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 ini-
tial value of the variable. Initialization forces
the variable to be a simple scalar value; unini-
tialized 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 initialization 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.
className objName ?args...?
Creates a new object in class className with the name
objName. Remaining arguments are passed to the con-
structor. 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 #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" specification would produce |
names toaster0, toaster1, etc. Remaining arguments are
passed to the constructor. If construction is success-
ful, 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 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 speci-
fied object. Remaining arguments are passed to the
method. The method name can be "constructor", "des-
tructor", any method name appearing in the class defin-
ition, 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" 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 destruc-
tion.
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 procName is specified, it
returns information for a specific proc. If nei-
ther of the optional -args or -body flags is
specified, a complete proc definition is returned
as a list of three elements including the proc
name, argument list and body. Otherwise, the
requested information is returned without 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 vari-
able. If none of the optional -init, -value or
-config flags are specified, all available infor-
mation is returned as a list of four elements
including the variable name, initial value,
current value, and configuration commands. Other-
wise, 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 informa-
tion is returned as a list of three elements
including the variable name, initial value and
current value. Otherwise, the requested informa-
tion 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 vari-
able. 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 communicat-
ing 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 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 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 program- |
ming, 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 "tclIn-
dex" 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 append-
ing 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