man/mann/itcl_class.n

'\"
'\" Copyright (c) 1993-1998  Lucent Technologies, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" RCS: $Id: itcl_class.n,v 1.1 1998/07/27 18:42:01 stanton Exp $
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
'\"	or "in/out" to describe whether procedure reads or modifies arg,
'\"	and indent is equivalent to second arg of .IP (shouldn't ever be
'\"	needed;  use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\"	Give maximum sizes of arguments for setting tab stops.  Type and
'\"	name are examples of largest possible arguments that will be passed
'\"	to .AP later.  If args are omitted, default tab stops are used.
'\"
'\" .BS
'\"	Start box enclosure.  From here until next .BE, everything will be
'\"	enclosed in one large box.
'\"
'\" .BE
'\"	End of box enclosure.
'\"
'\" .CS
'\"	Begin code excerpt.
'\"
'\" .CE
'\"	End code excerpt.
'\"
'\" .VS ?version? ?br?
'\"	Begin vertical sidebar, for use in marking newly-changed parts
'\"	of man pages.  The first argument is ignored and used for recording
'\"	the version when the .VS was added, so that the sidebars can be
'\"	found and removed when they reach a certain age.  If another argument
'\"	is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\"	End of vertical sidebar.
'\"
'\" .DS
'\"	Begin an indented unfilled display.
'\"
'\" .DE
'\"	End of indented unfilled display.
'\"
'\" .SO
'\"	Start of list of standard options for a Tk widget.  The
'\"	options follow on successive lines, in four columns separated
'\"	by tabs.
'\"
'\" .SE
'\"	End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\"	Start of description of a specific option.  cmdName gives the
'\"	option's name as specified in the class command, dbName gives
'\"	the option's name in the option database, and dbClass gives
'\"	the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\"	Print arg1 underlined, then print arg2 normally.
'\"
'\" SCCS: @(#) man.macros 1.9 97/08/22 18:50:59
'\"
'\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
'\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ie !"\\$3"" \{\
.ta \\n()Au \\n()Bu
\&\\$1	\\fI\\$2\\fP	(\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
'\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
'\"	# BS - start boxed text
'\"	# ^y = starting y location
'\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
'\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
.\"	box if the box started on an earlier page.
.ie !\\n(^b-1 \{\
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.el \}\
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
'\"	# VS - start vertical sidebar
'\"	# ^Y = starting y location
'\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
'\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
'\"	# Special macro to handle page bottom:  finish off current
'\"	# box/sidebar if in box/sidebar mode, then invoked standard
'\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
.\"	draw two sides but no top otherwise.
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.\}
.if \\n(^v \{\
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
.\}
.bp
'fi
.ev
.if \\n(^b \{\
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
'\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
'\"	# DE - end display
.de DE
.fi
.RE
.sp
..
'\"	# SO - start of list of standard options
.de SO
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 4c 8c 12c
.ft B
..
'\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\fBoptions\\fR manual entry for details on the standard options.
..
'\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
'\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
'\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH itcl_class n 3.0 itcl "[incr\ Tcl]"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
itcl_class \- create a class of objects (obsolete)
.SH SYNOPSIS
\fBitcl_class \fIclassName\fR \fB{
.br
    \fBinherit \fIbaseClass\fR ?\fIbaseClass\fR...?
.br
    \fBconstructor \fIargs\fR ?\fIinit\fR? \fIbody\fR
.br
    \fBdestructor \fIbody\fR
.br
    \fBmethod \fIname args body\fR
.br
    \fBproc \fIname args body\fR
.br
    \fBpublic \fIvarName\fR ?\fIinit\fR? ?\fIconfig\fR?
.br
    \fBprotected \fIvarName\fR ?\fIinit\fR?
.br
    \fBcommon \fIvarName\fR ?\fIinit\fR?
.br
\fB}\fR
.sp
\fIclassName objName\fR ?\fIargs...\fR?
.br
\fIclassName\fR \fB#auto\fR ?\fIargs...\fR?
.br
\fIclassName\fR \fB::\fR \fIproc\fR ?\fIargs...\fR?
.sp
\fIobjName method\fR ?\fIargs...\fR?
.sp
\fICommands available within class methods/procs:\fR
.br
\fBglobal \fIvarName\fR ?\fIvarName...\fR?
.br
\fBprevious \fIcommand\fR ?\fIargs...\fR?
.br
\fBvirtual \fIcommand\fR ?\fIargs...\fR?
.BE

.SH DESCRIPTION
.PP
This command is considered obsolete, but is retained for
backward-compatibility with earlier versions of \fB[incr\ Tcl]\fR.
It has been replaced by the \fBclass\fR command, which should
be used for any new development.

.TP
\fBitcl_class \fIclassName definition\fR
Provides the definition for a class named \fIclassName\fR.  If
\fIclassName\fR is already defined, then this command returns
an error.  If the class definition is successfully parsed,
\fIclassName\fR becomes a command in the current namespace
context, handling the
creation of objects and providing access to class scope.
The class \fIdefinition\fR
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:
.RS
.TP
\fBinherit \fIbaseClass\fR ?\fIbaseClass\fR...?
Declares one or more base classes, causing the current class to
inherit their characteristics.  Classes must have been defined by
a previous \fBitcl_class\fR command, or must be available to the
auto-loading facility (see "AUTO-LOADING" below).  A single class
definition can contain no more than one \fBinherit\fR command.
.RS
.LP
When the same member name appears in two or more base classes,
the base class that appears first in the \fBinherit\fR list takes
precedence.  For example, if classes "Foo" and "Bar" both contain
the member "x", then the "\fBinherit\fR" statement:
.CS
inherit Foo Bar
.CE
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 "\fIclass\fR::\fImember\fR" name.
.RE
.TP
\fBconstructor \fIargs\fR ?\fIinit\fR? \fIbody\fR
Declares the argument list and body used for the constructor, which
is automatically invoked whenever an object is created.  Before
.VS
the \fIbody\fR is executed, the optional \fIinit\fR statement is
used to invoke any base class constructors that require arguments.
Variables in the \fIargs\fR specification can be accessed in the
\fIinit\fR code fragment, and passed to base class constructors.
After evaluating the \fIinit\fR 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 \fIbody\fR is executed.
.VE
If construction is successful, the constructor always returns
the object name\-regardless of how the \fIbody\fR is defined\-and
the object name becomes a command in the current namespace context.
If construction fails, an error message is returned.
.TP
\fBdestructor \fIbody\fR
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.
.RS
.LP
.VS
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 "\fBinfo heritage\fR"
command, and it is exactly the opposite of the default constructor
order.
.VE
.RE
.TP
\fBmethod \fIname args body\fR
Declares a method called \fIname\fR with an argument list \fIargs\fR
and a \fIbody\fR of Tcl statements.  A method is just like the usual
Tcl "proc" except that it has transparent access to
.VS
object-specific variables, as well as
.VE
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
"\fIclass\fR::\fImethod\fR" syntax.
.TP
\fBproc \fIname args body\fR
Declares a proc called \fIname\fR with an argument list \fIargs\fR
and a \fIbody\fR 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
.VS
to object-specific variables declared with the \fBpublic\fR
and \fBprotected\fR commands.
.VE
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 "\fIclassName\fB::\fIproc\fR".
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.
.TP
\fBpublic \fIvarName\fR ?\fIinit\fR? ?\fIconfig\fR?
Declares a public variable named \fIvarName\fR.  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
\fIinit\fR is specified, it is used as the initial value of the variable
when a new object is created.  If the optional \fIconfig\fR command
is specified,
it is invoked whenever a public variable is modified via the "config"
formal argument; if the \fIconfig\fR command returns an error, the
public variable is reset to its value before configuration, and the
method handling the configuration returns an error.
.TP
\fBprotected \fIvarName\fR ?\fIinit\fR?
Declares a protected variable named \fIvarName\fR.  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 \fIinit\fR
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.
.TP
\fBcommon \fIvarName\fR ?\fIinit\fR?
Declares a common variable named \fIvarName\fR.  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 \fIinit\fR 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.
.RS
.LP
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:
.CS
itcl_class Foo {
     .
     .
    common boolean
    set boolean(true) 1
    set boolean(false) 0
}
.CE
.RE
.RE

.SH CLASS USAGE
.PP
When a class definition has been loaded (or made available to the
auto-loader), the class name can be used as a command.
.TP
\fIclassName objName\fR ?\fIargs...\fR?
Creates a new object in class \fIclassName\fR with the name \fIobjName\fR.
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.
.TP
\fIclassName\fR #auto ?\fIargs...\fR?
Creates a new object in class \fIclassName\fR with an automatically
generated name.  Names are of the form \fIclassName<number>\fR,
.VS
where the \fIclassName\fR part is modified to start with a lowercase
letter.  In class "Toaster", for example, the "\fB#auto\fR" specification
would produce names toaster0, toaster1, etc.  Remaining arguments are
.VE
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.
.TP
\fIclassName\fR  ::  \fIproc\fR ?\fIargs...\fR?
Used outside of the class scope to invoke a class proc named \fIproc\fR.
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.
.RS
.LP
.VS
Notice that, unlike any other scope qualifier in \fB[incr\ Tcl]\fR, 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.
.VE
.RE

.SH OBJECT USAGE
.TP
\fIobjName method\fR ?\fIargs...\fR?
Invokes a method named \fImethod\fR 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.
.SH BUILT-IN METHODS
.TP
\fIobjName\fR \fBisa \fIclassName\fR
Returns non-zero if the given \fIclassName\fR can be found in the
object's heritage, and zero otherwise.
.TP
\fIobjName\fR \fBdelete\fR
Invokes the destructor associated with an object.
If the destructor is successful, data associated with the object is
deleted and \fIobjName\fR is removed as a command from the
interpreter.  Returns the empty string, regardless of the destructor
body.
.RS
.LP
.VS
The built-in \fBdelete\fR method has been replaced by the
"\fBdelete object\fR" command in the global namespace, and
is considered obsolete.  The capability is still supported,
however, to provide backward-compatibility with earlier versions.
.VE
.RE
.TP
\fIobjName\fR \fBinfo \fIoption\fR ?\fIargs...\fR?
Returns information related to the class definition or to
a particular object named \fIobjName\fR.
The \fIoption\fR parameter includes the following things, as well as
the options recognized by the usual Tcl "info" command:
.RS
.TP
\fIobjName\fR \fBinfo class\fR
.VS
Returns the name of the most-specific class for object \fIobjName\fR.
.VE
.TP
\fIobjName\fR \fBinfo inherit\fR
Returns the list of base classes as they were defined in the
"\fBinherit\fR" command, or an empty string if this class
has no base classes.
.TP
\fIobjName\fR \fBinfo heritage\fR
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.
.TP
\fIobjName\fR \fBinfo method\fR ?\fImethodName\fR? ?\fB-args\fR? ?\fB-body\fR?
With no arguments, this command returns a list of all class methods.
If \fImethodName\fR is specified, it returns information for a specific method.
If neither of the optional \fB-args\fR or \fB-body\fR 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 \fImethodName\fR is not recognized, an empty string is returned.
.TP
\fIobjName\fR \fBinfo proc\fR ?\fIprocName\fR? ?\fB-args\fR? ?\fB-body\fR?
With no arguments, this command returns a list of all class procs.
If \fIprocName\fR is specified, it returns information for a specific proc.
If neither of the optional \fB-args\fR or \fB-body\fR 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 \fIprocName\fR is not recognized, an empty string is returned.
.TP
\fIobjName\fR \fBinfo public\fR ?\fIvarName\fR? ?\fB-init\fR? ?\fB-value\fR? ?\fB-config\fR?
With no arguments, this command returns a list of all public variables.
If \fIvarName\fR is specified, it returns information for a specific public
variable.
If none of the optional \fB-init\fR, \fB-value\fR or \fB-config\fR 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 \fIvarName\fR is not recognized, an empty string is returned.
.TP
\fIobjName\fR \fBinfo protected\fR ?\fIvarName\fR? ?\fB-init\fR? ?\fB-value\fR?
With no arguments, this command returns a list of all protected variables.
If \fIvarName\fR is specified, it returns information for a specific protected
variable.
If neither of the optional \fB-init\fR or \fB-value\fR 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 \fIvarName\fR is not recognized, an empty string is returned.
.TP
\fIobjName\fR \fBinfo common\fR ?\fIvarName\fR? ?\fB-init\fR? ?\fB-value\fR?
With no arguments, this command returns a list of all common variables.
If \fIvarName\fR is specified, it returns information for a specific common
variable.
If neither of the optional \fB-init\fR or \fB-value\fR 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 \fIvarName\fR is not recognized, an empty string is returned.
.RE
.SH 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.
.TP
\fBglobal \fIvarName\fR ?\fIvarName...\fR?
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 \fIvarName\fR.
This is useful when communicating with Tk widgets that rely on global
variables.
.TP
\fBprevious \fIcommand\fR ?\fIargs...\fR?
Invokes \fIcommand\fR in the scope of the most immediate base class
.VS
(i.e., the "previous" class) for the object.  For classes using single
.VE
inheritance, this facility can be used to avoid hard-wired base class
references of the form "\fIclass\fR::\fIcommand\fR", 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.
.TP
\fBvirtual \fIcommand\fR ?\fIargs...\fR?
.VS
Invokes \fIcommand\fR 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.
.VE

.SH AUTO-LOADING
.PP
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 \fB[incr\ Tcl]\fR
class definition and the file where the definition can be found.
.PP
For example, suppose a directory contains the definitions for classes
"Toaster" and "SmartToaster".  Then the "tclIndex" file for this
directory would look like:
.CS
# 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"
.PP
The \fBauto_mkindex\fR command is used to automatically
generate "tclIndex" files.
.CE
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.

.SH KEYWORDS
class, object, object-oriented