itcl_class

NAME

SYNOPSIS

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 successfully 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 commands 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 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 without arguments. This ensures that all base classes are fully constructed before the constructor body is executed. 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 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 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 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 therefore 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 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.

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 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; uninitialized 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 initial value of the variable. Initialization 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 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 command.

className objName ?args...?

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. 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 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 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 specified object. Remaining arguments are passed to 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 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 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 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 neither 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 variable. If none of the optional -init, -value or -config flags are specified, all available information is returned as a list of four elements including the variable name, initial value, current 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 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.

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 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 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

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 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 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 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 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 "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.

KEYWORDS

Index

NAME

SYNOPSIS

DESCRIPTION

CLASS USAGE

OBJECT USAGE

BUILT-IN METHODS

OTHER BUILT-IN COMMANDS

AUTO-LOADING

KEYWORDS