ag/cpython-source-deps
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Import Tcl 8.6.12

Browse Source
This commit is contained in:
Steve Dower
2021-11-08 17:30:58 +00:00
parent 1aadb2455c
commit 674867e7e6
608 changed files with 78089 additions and 60360 deletions
Download Patch File Download Diff File Expand all files Collapse all files

55
pkgs/itcl4.2.2/doc/Class.3 Normal file
View File

@@ -0,0 +1,55 @@
'\"
'\" 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.
'\"
.TH Itcl_CreateClass 3 3.0 itcl "[incr\ Tcl] Library Procedures"
.so man.macros
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
Itcl_CreateClass, Itcl_DeleteClass, Itcl_FindClass, Itcl_IsClass, Itcl_IsClassNamespace \- Manipulate classes.
.SH SYNOPSIS
.nf
\fB#include <itclInt.h>\fR
int
\fBItcl_CreateClass\fR(\fIinterp, path, info, rPtr\fR)
int
\fBItcl_DeleteClass\fR(\fIinterp, cdefnPtr\fR)
ItclClass *
\fBItcl_FindClass\fR(\fIinterp, path, autoload\fR)
int
\fBItcl_IsClass\fR(\fIcmd\fR)
int
\fBItcl_IsClassNamespace\fR(\fInamesp\fR)
.fi
.SH ARGUMENTS
.AP Tcl_Interp *interp in
Interpreter to modify.
.AP "CONST char" *path in
Path of the class.
.AP ItclObjectInfo *info in
TODO.
.AP ItclClass **rPtr in/out
The address of the pointer to modify.
.AP ItclClass *cdefnPtr in
Pointer to class info struct.
.AP int autoload in
Flag value for if the class should be autoloaded
.AP Tcl_Command cmd in
Command to check.
.AP Tcl_Namespace *namesp in
Namespace to check.
.BE
.SH DESCRIPTION
.PP
.SH KEYWORDS
class, find

58
pkgs/itcl4.2.2/doc/List.3 Normal file
View File

@@ -0,0 +1,58 @@
'\"
'\" 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.
'\"
.TH Itcl_InitList 3 3.0 itcl "[incr\ Tcl] Library Procedures"
.so man.macros
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
Itcl_InitList, Itcl_DeleteList, Itcl_CreateListElem, Itcl_DeleteListElem, Itcl_InsertList, Itcl_InsertListElem, Itcl_AppendList, Itcl_AppendListElem, Itcl_SetListValue \- Manipulate an Itcl list object.
.SH SYNOPSIS
.nf
\fB#include <itcl.h>\fR
void
\fBItcl_InitList\fR(\fIlist\fR)
void
\fBItcl_DeleteList\fR(\fIlist\fR)
Itcl_ListElem *
\fBItcl_CreateListElem\fR(\fIlist\fR)
Itcl_ListElem *
\fBItcl_DeleteListElem\fR(\fIelem\fR)
Itcl_ListElem *
\fBItcl_InsertList\fR(\fIlist, clientData\fR)
Itcl_ListElem *
\fBItcl_InsertListElem\fR(\fIelem, clientData\fR)
Itcl_ListElem *
\fBItcl_AppendList\fR(\fIlist, clientData\fR)
Itcl_ListElem *
\fBItcl_AppendListElem\fR(\fIelem, clientData\fR)
void
\fBItcl_SetListValue\fR(\fIelem, clientData\fR)
.fi
.SH ARGUMENTS
.AP Itcl_List *list in
List info structure.
.AP Itcl_ListElem *elem in
List element info structure.
.AP ClientData clientData in
Arbitrary one-word value to save in the list.
.BE
.SH DESCRIPTION
.PP
.SH KEYWORDS
list

38
pkgs/itcl4.2.2/doc/Object.3 Normal file
View File

@@ -0,0 +1,38 @@
'\"
'\" 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.
'\"
.TH Itcl_CreateObject 3 3.0 itcl "[incr\ Tcl] Library Procedures"
.so man.macros
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
Itcl_CreateObject, Itcl_DeleteObject, Itcl_FindObject, Itcl_IsObject, Itcl_IsObjectIsa \- Manipulate an class instance.
.SH SYNOPSIS
.nf
\fB#include <itclInt.h>\fR
void
\fBItcl_PreserveData\fR(\fIcdata\fR)
void
\fBItcl_ReleaseData\fR(\fIcdata\fR)
void
\fBItcl_EventuallyFree\fR(\fIcdata, fproc\fR)
.fi
.SH ARGUMENTS
.AP Tcl_FreeProc *fproc in
Address of function to call when the block is to be freed.
.AP ClientData clientData in
Arbitrary one-word value.
.BE
.SH DESCRIPTION
.PP
.SH KEYWORDS
free, memory

83
pkgs/itcl4.2.2/doc/Preserve.3 Normal file
View File

@@ -0,0 +1,83 @@
'\"
'\" 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.
'\"
.TH Itcl_PreserveData 3 3.0 itcl "[incr\ Tcl] Library Procedures"
.so man.macros
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
Itcl_Alloc, Itcl_Free, Itcl_PreserveData, Itcl_ReleaseData, Itcl_EventuallyFree \- Manipulate an Itcl list object.
.SH SYNOPSIS
.nf
\fB#include <itcl.h>\fR
void *
\fBItcl_Alloc\fR(\fIsize\fR)
void
\fBItcl_PreserveData\fR(\fIptr\fR)
void
\fBItcl_ReleaseData\fR(\fIptr\fR)
void
\fBItcl_EventuallyFree\fR(\fIptr, fproc\fR)
void
\fBItcl_Free\fR(\fIptr\fR)
.fi
.SH ARGUMENTS
.AP size_t size in
Number of bytes to allocate.
.AP void *ptr in
Pointer value allocated by \fBItcl_Alloc\fR.
.AP Tcl_FreeProc *fproc in
Address of function to call when the block is to be freed.
.BE
.SH DESCRIPTION
.PP
These procedures are used to allocate and release memory, especially blocks
of memory that will be used by multiple independent modules. They are similar
in function to the routines in the public Tcl interface, \fBTcl_Alloc\fR,
\fBTcl_Free\fR, \fBTcl_Preserve\fR, \fBTcl_Release\fR, and
\fBTcl_EventuallyFree\fR. The Tcl routines suffer from issues with
performance scaling as the number of blocks managed grows large. The facilities
of Itcl encounter these performance scaling issues and require an
alternative that does not suffer from them.
.PP
\fBItcl_Alloc\fR returns an untyped pointer to an allocated block
of memory of at least \fIsize\fR bytes. All \fIsize\fR bytes are
initialized to zero.
.PP
A module calls \fBItcl_PreserveData\fR on a pointer \fIptr\fR
allocated by \fBItcl_Alloc\fR to prevent deallocation of that memory while
the module remains interested in it.
.PP
A module calls \fBItcl_ReleaseData\fR on a pointer \fIptr\fR previously
preserved by \fBItcl_PreserveData\fR to indicate the module no longer has
an interest in the block of memory, and will not be disturbed by its
deallocation.
.PP
\fBItcl_EventuallyFree\fR is called on a pointer \fIptr\fR allocated by
\fBItcl_Alloc\fR to register a deallocation routine \fIfproc\fR to be
called when the number of calls to \fBItcl_ReleaseData\fR on \fIptr\fR
matches the number of calls to \fBItcl_PreserveData\fR on \fIptr\fR. This
condition indicates all modules have ended their interest in the block
of memory and a call to \fIfproc\fR with argument \fIptr\fR will deallocate
the memory that no module needs anymore.
.PP
\fBItcl_Free\fR is a deallocation routine for a \fIptr\fR value allocated
by \fBItcl_Alloc\fR. It may be called on any \fIptr\fR with no history of
an \fBItcl_PreserveData\fR call unmatched by an \fBItcl_ReleaseData\fR
call. It is best used as an \fIfproc\fR argument to \fBItcl_EventuallyFree\fR
or as a routine called from within such an \fIfproc\fR routine. It can also
be used to deallocate a \fIptr\fR value when it can be assured that value
has never been passed to \fBItcl_PreserveData\fR or \fBItcl_EventuallyFree\fR.
.SH KEYWORDS
free, memory

123
pkgs/itcl4.2.2/doc/RegisterC.3 Normal file
View File

@@ -0,0 +1,123 @@
'\"
'\" 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.
'\"
.TH Itcl_RegisterC 3 3.0 itcl "[incr\ Tcl] Library Procedures"
.so man.macros
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
Itcl_RegisterC, Itcl_RegisterObjC, Itcl_FindC \- Associate a symbolic name with a C procedure.
.SH SYNOPSIS
.nf
\fB#include <itcl.h>\fR
int
\fBItcl_RegisterC\fR(\fIinterp, cmdName, argProc, clientData, deleteProc\fR)
int
\fBItcl_RegisterObjC\fR(\fIinterp, cmdName, objProc, clientData, deleteProc\fR)
int
\fBItcl_FindC\fR(\fIinterp, cmdName, argProcPtr, objProcPtr, cDataPtr\fR)
.fi
.SH ARGUMENTS
.AP Tcl_Interp *interp in
Interpreter in which to create new command.
.VS 8.4
.AP "CONST char" *cmdName in
.VE
Name of command.
.AP Tcl_CmdProc *argProc in
Implementation of new command: \fIargProc\fR will be called whenever
.AP Tcl_CmdProc **argProcPtr in/out
The Tcl_CmdProc * to receive the pointer.
.AP Tcl_ObjCmdProc *objProc in
Implementation of the new command: \fIobjProc\fR will be called whenever
.AP Tcl_ObjCmdProc **objProcPtr in/out
The Tcl_ObjCmdProc * to receive the pointer.
.AP ClientData clientData in
Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR.
.AP ClientData *cDataPtr in/out
The ClientData to receive the pointer.
.AP Tcl_CmdDeleteProc *deleteProc in
Procedure to call before \fIcmdName\fR is deleted from the interpreter;
allows for command-specific cleanup. If NULL, then no procedure is
called before the command is deleted.
.BE
.SH DESCRIPTION
.PP
Used to associate a symbolic name with an (argc,argv) C procedure
that handles a Tcl command. Procedures that are registered in this
manner can be referenced in the body of an [incr Tcl] class
definition to specify C procedures to acting as methods/procs.
Usually invoked in an initialization routine for an extension,
called out in Tcl_AppInit() at the start of an application.
.PP
Each symbolic procedure can have an arbitrary client data value
associated with it. This value is passed into the command
handler whenever it is invoked.
.PP
A symbolic procedure name can be used only once for a given style
(arg/obj) handler. If the name is defined with an arg-style
handler, it can be redefined with an obj-style handler; or if
the name is defined with an obj-style handler, it can be redefined
with an arg-style handler. In either case, any previous client
data is discarded and the new client data is remembered. However,
if a name is redefined to a different handler of the same style,
this procedure returns an error.
.PP
Returns TCL_OK on success, or TCL_ERROR (along with an error message
in interp->result) if anything goes wrong.
.PP
C procedures can be integrated into an \fB[incr\ Tcl]\fR class
definition to implement methods, procs, and the "config" code
for public variables. Any body that starts with "\fB@\fR"
is treated as the symbolic name for a C procedure.
.PP
Symbolic names are established by registering procedures via
\fBItcl_RegisterC()\fR. This is usually done in the \fBTcl_AppInit()\fR
procedure, which is automatically called when the interpreter starts up.
In the following example, the procedure \fCMy_FooCmd()\fR is registered
with the symbolic name "foo". This procedure can be referenced in
the \fBbody\fR command as "\fC@foo\fR".
.CS
int
Tcl_AppInit(interp)
Tcl_Interp *interp; /* Interpreter for application. */
{
if (Itcl_Init(interp) == TCL_ERROR) {
return TCL_ERROR;
}
if (Itcl_RegisterC(interp, "foo", My_FooCmd) != TCL_OK) {
return TCL_ERROR;
}
}
.CE
C procedures are implemented just like ordinary Tcl commands.
See the \fBCrtCommand\fR man page for details. Within the procedure,
class data members can be accessed like ordinary variables
using \fBTcl_SetVar()\fR, \fBTcl_GetVar()\fR, \fBTcl_TraceVar()\fR,
etc. Class methods and procs can be executed like ordinary commands
using \fBTcl_Eval()\fR. \fB[incr\ Tcl]\fR makes this possible by
automatically setting up the context before executing the C procedure.
.PP
This scheme provides a natural migration path for code development.
Classes can be developed quickly using Tcl code to implement the
bodies. An entire application can be built and tested. When
necessary, individual bodies can be implemented with C code to
improve performance.
.PP
See the Archetype class in \fB[incr\ Tk]\fR for an example of how this
C linking method is used.
.SH "SEE ALSO"
Tcl_CreateCommand, Tcl_CreateObjCommand
.SH KEYWORDS
class, object

59
pkgs/itcl4.2.2/doc/Stack.3 Normal file
View File

@@ -0,0 +1,59 @@
'\"
'\" 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.
'\"
.TH Itcl_InitStack 3 3.0 itcl "[incr\ Tcl] Library Procedures"
.so man.macros
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
Itcl_InitStack, Itcl_DeleteStack, Itcl_PushStack, Itcl_PopStack, Itcl_PeekStack, Itcl_GetStackValue, Itcl_GetStackSize \- Manipulate an Itcl stack object.
.SH SYNOPSIS
.nf
\fB#include <itcl.h>\fR
int
\fBItcl_InitStack\fR(\fIstack\fR)
int
\fBItcl_DeleteStack\fR(\fIstack\fR)
int
\fBItcl_PushStack\fR(\fIcdata, stack\fR)
ClientData
\fBItcl_PopStack\fR(\fIstack\fR)
ClientData
\fBItcl_PeekStack\fR(\fIstack\fR)
ClientData
\fBItcl_GetStackValue\fR(\fIstack, pos\fR)
int
\fBItcl_GetStackSize\fR(\fIstack\fR)
.fi
.SH ARGUMENTS
.AP Itcl_Stack *stack in
Stack info structure.
.AP int pos in
position in stack order from the top.
.AP ClientData clientData in
Arbitrary one-word value to save in the stack.
.BE
.SH DESCRIPTION
.PP
\fBItcl_InitStack\fR initializes a stack structure and \fBItcl_DeleteStack\fR
deletes it. \fBItcl_PushStack\fR pushes the \fIcdata\fR value onto the stack.
\fBItcl_PopStack\fR removes and returns the top most \fIcdata\fR value.
\fBItcl_PeekStack\fR returns the top most value, but does not remove it.
\fBItcl_GetStackValue\fR gets a value at some index within the stack. Index
"0" is the first value pushed onto the stack. \fBItcl_GetStackSize\fR
returns the count of entries on the stack.
.SH KEYWORDS
stack

122
pkgs/itcl4.2.2/doc/body.n Normal file
View File

@@ -0,0 +1,122 @@
'\"
'\" 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.
'\"
.TH body n 3.0 itcl "[incr\ Tcl]"
.so man.macros
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
itcl::body \- change the body for a class method/proc
.SH SYNOPSIS
\fBitcl::body \fIclassName\fB::\fIfunction args body\fR
.BE
.SH DESCRIPTION
.PP
The \fBbody\fR command is used outside of an \fB[incr\ Tcl]\fR
class definition to define or redefine the body of a class
method or proc. This facility allows a class definition
to have separate "interface" and "implementation" parts.
The "interface" part is a \fBclass\fR command with declarations
for methods, procs, instance variables and common variables.
The "implementation" part is a series of \fBbody\fR and
\fBconfigbody\fR commands. If the "implementation" part
is kept in a separate file, it can be sourced again and
again as bugs are fixed, to support interactive development.
When using the "tcl" mode in the \fBemacs\fR editor, the
"interface" and "implementation" parts can be kept in the
same file; as bugs are fixed, individual bodies can be
highlighted and sent to the test application.
.PP
The name "\fIclassName\fB::\fIfunction\fR"
identifies the method/proc being changed.
.PP
If an \fIargs\fR list was specified when the \fIfunction\fR was
defined in the class definition, the \fIargs\fR list for the
\fBbody\fR command must match in meaning. Variable names
can change, but the argument lists must have the same required
arguments and the same default values for optional arguments.
The special \fBargs\fR argument acts as a wildcard when included
in the \fIargs\fR list in the class definition; it will match
zero or more arguments of any type when the body is redefined.
.PP
If the \fIbody\fR string starts with "\fB@\fR", it is treated
as the symbolic name for a C procedure. The \fIargs\fR list
has little meaning for the C procedure, except to document
the expected usage. (The C procedure is not guaranteed to
use arguments in this manner.) If \fIbody\fR does not start
with "\fB@\fR", it is treated as a Tcl command script. When
the function is invoked, command line arguments are matched
against the \fIargs\fR list, and local variables are created
to represent each argument. This is the usual behavior for
a Tcl-style proc.
.PP
Symbolic names for C procedures are established by registering
procedures via \fBItcl_RegisterC()\fR. This is usually done
in the \fBTcl_AppInit()\fR procedure, which is automatically called
when the interpreter starts up. In the following example,
the procedure \fCMy_FooCmd()\fR is registered with the
symbolic name "foo". This procedure can be referenced in
the \fBbody\fR command as "\fC@foo\fR".
.CS
int
Tcl_AppInit(interp)
Tcl_Interp *interp; /* Interpreter for application. */
{
if (Itcl_Init(interp) == TCL_ERROR) {
return TCL_ERROR;
}
if (Itcl_RegisterC(interp, "foo", My_FooCmd) != TCL_OK) {
return TCL_ERROR;
}
}
.CE
.SH EXAMPLE
In the following example, a "File" class is defined to represent
open files. The method bodies are included below the class
definition via the \fBbody\fR command. Note that the bodies
of the constructor/destructor must be included in the class
definition, but they can be redefined via the \fBbody\fR command
as well.
.CS
itcl::class File {
private variable fid ""
constructor {name access} {
set fid [open $name $access]
}
destructor {
close $fid
}
method get {}
method put {line}
method eof {}
}
itcl::body File::get {} {
return [gets $fid]
}
itcl::body File::put {line} {
puts $fid $line
}
itcl::body File::eof {} {
return [::eof $fid]
}
#
# See the File class in action:
#
File x /etc/passwd "r"
while {![x eof]} {
puts "=> [x get]"
}
itcl::delete object x
.CE
.SH KEYWORDS
class, object, procedure

542
pkgs/itcl4.2.2/doc/class.n Normal file
View File

@@ -0,0 +1,542 @@
'\"
'\" 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.
'\"
.TH class n "" itcl "[incr\ Tcl]"
.so man.macros
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
itcl::class \- create a class of objects
.SH SYNOPSIS
.nf
\fBitcl::class \fIclassName \fB{\fR
\fBinherit \fIbaseClass\fR ?\fIbaseClass\fR...?
\fBconstructor \fIargs\fR ?\fIinit\fR? \fIbody\fR
\fBdestructor \fIbody\fR
\fBmethod \fIname\fR ?\fIargs\fR? ?\fIbody\fR?
\fBproc \fIname\fR ?\fIargs\fR? ?\fIbody\fR?
\fBvariable \fIvarName\fR ?\fIinit\fR? ?\fIconfig\fR?
\fBcommon \fIvarName\fR ?\fIinit\fR?
\fBpublic \fIcommand\fR ?\fIarg arg ...\fR?
\fBprotected \fIcommand\fR ?\fIarg arg ...\fR?
\fBprivate \fIcommand\fR ?\fIarg arg ...\fR?
\fBset \fIvarName\fR ?\fIvalue\fR?
\fBarray \fIoption\fR ?\fIarg arg ...\fR?
\fB}\fR
\fIclassName objName\fR ?\fIarg arg ...\fR?
\fIobjName method\fR ?\fIarg arg ...\fR?
\fIclassName::proc\fR ?\fIarg arg ...\fR?
.fi
.BE
.SH DESCRIPTION
.PP
The fundamental construct in \fB[incr\ Tcl]\fR 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 contains
instances 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 that
are shared by all objects in a class.
.PP
Two types of functions can be included in the class definition.
"Methods" are functions which operate on a specific object, and
therefore have access to both "variables" and "common" data members.
"Procs" are ordinary procedures in the class namespace, and only
have access to "common" data members.
.PP
If the body of any method or proc starts with "\fB@\fR", it is treated
as the symbolic name for a C procedure. Otherwise, it is treated as
a Tcl code script. See below for details on registering and using
C procedures.
.PP
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 \fBbody\fR and \fBconfigbody\fR commands for
details.
.PP
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 "\fBitcl::find classes\fR" command, and the list of objects,
with the "\fBitcl::find objects\fR" command.
.PP
A class can be deleted using the "\fBdelete class\fR" command.
Individual objects can be deleted using the "\fBdelete object\fR"
command.
.SH "CLASS DEFINITIONS"
.TP
\fBclass \fIclassName definition\fR
.
Provides the definition for a class named \fIclassName\fR. If
the class \fIclassName\fR already exists, or if a command called
\fIclassName\fR exists in the current namespace context, this
command returns an error. If the class definition is successfully
parsed, \fIclassName\fR becomes a command in the current context,
handling the creation of objects for this class.
.PP
The class \fIdefinition\fR is evaluated as a series of Tcl
statements that define elements within the class. The following
class definition commands are recognized:
.RS
.TP
\fBinherit \fIbaseClass\fR ?\fIbaseClass\fR...?
.
Causes the current class to inherit characteristics from one or
more base classes. Classes must have been defined by a previous
\fBclass\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
.PP
The order of \fIbaseClass\fR names in the \fBinherit\fR list
affects the 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 \fBinherit\fR list takes precedence.
For example, if classes "Foo" and "Bar" both contain the member
"x", and if another class has the "\fBinherit\fR" statement:
.PP
.CS
inherit Foo Bar
.CE
.PP
then the name "x" means "Foo::x". Other inherited members named
"x" must be referenced with their explicit name, like "Bar::x".
.RE
.TP
\fBconstructor \fIargs\fR ?\fIinit\fR? \fIbody\fR
.
Declares the \fIargs\fR argument list and \fIbody\fR used for
the constructor, which is automatically invoked whenever an
object is created.
.RS
.PP
Before 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 automatically without arguments.
This ensures that all base classes are fully constructed before
the constructor \fIbody\fR is executed. By default, this
scheme causes constructors to be invoked in order from least-
to most-specific. This is exactly the opposite of the order
that classes are reported by the \fBinfo heritage\fR command.
.PP
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.
.RE
.TP
\fBdestructor \fIbody\fR
.
Declares the \fIbody\fR used for the destructor, which is automatically
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.
.RS
.PP
When an object is destroyed, all destructors in its 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.
.RE
.TP
\fBmethod \fIname\fR ?\fIargs\fR? ?\fIbody\fR?
.
Declares a method called \fIname\fR. When the method \fIbody\fR is
executed, it will have automatic access to object-specific variables
and common data members.
.RS
.PP
If the \fIargs\fR list is specified, it establishes the usage
information for this method. The \fBbody\fR command can be used
to redefine the method body, but the \fIargs\fR list must match
this specification.
.PP
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 for the 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
"\fIclassName\fR::\fImethod\fR" syntax.
.RE
.TP
\fBproc \fIname\fR ?\fIargs\fR? ?\fIbody\fR?
.
Declares a proc called \fIname\fR. A proc is an ordinary procedure
within the class namespace. Unlike a method, a proc is invoked
without referring to a specific object. When the proc \fIbody\fR is
executed, it will have automatic access only to common data members.
.RS
.PP
If the \fIargs\fR list is specified, it establishes the usage
information for this proc. The \fBbody\fR command can be used
to redefine the proc body, but the \fIargs\fR list must match
this specification.
.PP
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 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.
.RE
.TP
\fBvariable \fIvarName\fR ?\fIinit\fR? ?\fIconfig\fR?
.
Defines an object-specific variable named \fIvarName\fR. All
object-specific variables are automatically available in class
methods. They need not be declared with anything like the
\fBglobal\fR command.
.RS
.PP
If the optional \fIinit\fR string 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 set
within the constructor and used as arrays.
.PP
The optional \fIconfig\fR script is only allowed for public variables.
If specified, this code fragment is executed whenever a public
variable is modified by the built-in "configure" method. The
\fIconfig\fR script can also be specified outside of the class
definition using the \fBconfigbody\fR command.
.RE
.TP
\fBcommon \fIvarName\fR ?\fIinit\fR?
.
Declares a common variable named \fIvarName\fR. Common variables
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 \fBglobal\fR command.
They are automatically visible in all class methods and procs.
.RS
.PP
If the optional \fIinit\fR 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 \fBset\fR and \fBarray\fR commands
and used as arrays.
.PP
Once a common data member has been defined, it can be set using
\fBset\fR and \fBarray\fR commands within the class definition.
This allows common data members to be initialized as arrays.
For example:
.PP
.CS
itcl::class Foo {
common boolean
set boolean(true) 1
set boolean(false) 0
}
.CE
.PP
Note that if common data members are initialized within the
constructor, they get initialized again and again whenever new
objects are created.
.RE
.TP
\fBpublic \fIcommand\fR ?\fIarg arg ...\fR?
.TP
\fBprotected \fIcommand\fR ?\fIarg arg ...\fR?
.TP
\fBprivate \fIcommand\fR ?\fIarg arg ...\fR?
.
These commands are used to set the protection level for class
members that are created when \fIcommand\fR is evaluated.
The \fIcommand\fR is usually \fBmethod\fR, \fBproc\fR,
\fBvariable\fR or\fBcommon\fR, and the remaining \fIarg\fR's
complete the member definition. However, \fIcommand\fR can
also be a script containing many different member definitions,
and the protection level will apply to all of the members
that are created.
.RE
.SH "CLASS USAGE"
.PP
Once a class has been defined, the class name can be used as a
command to create new objects belonging to the class.
.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 of the most-specific
class. This in turn passes arguments to base class constructors before
invoking its own body of commands. If construction is successful, a
command called \fIobjName\fR is created in the current namespace context,
and \fIobjName\fR 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.
.RS
.PP
If \fIobjName\fR contains the string "\fB#auto\fR", that string is
replaced with an automatically generated name. Names have the
form \fIclassName<number>\fR, 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
like toaster0, toaster1, etc. Note that "\fB#auto\fR" can be
also be buried within an object name:
.PP
.CS
fileselectiondialog .foo.bar.#auto -background red
.CE
.PP
This would generate an object named ".foo.bar.fileselectiondialog0".
.RE
.SH "OBJECT USAGE"
.PP
Once an object has been created, the object name can be used
as a command to invoke methods that operate on the object.
.TP
\fIobjName method\fR ?\fIargs...\fR?
.
Invokes a method named \fImethod\fR on an object named \fIobjName\fR.
Remaining arguments are passed to the argument list for 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 \fBcget option\fR
.
Provides access to public variables as configuration options. This
mimics the behavior of the usual "cget" operation for Tk widgets.
The \fIoption\fR argument is a string of the form "\fB-\fIvarName\fR",
and this method returns the current value of the public variable
\fIvarName\fR.
.TP
\fIobjName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
.
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.
.RS
.PP
If a single \fIoption\fR of the form "\fB-\fIvarName\fR" is specified,
then this method returns the information for that one variable.
.PP
Otherwise, the arguments are treated as \fIoption\fR/\fIvalue\fR
pairs assigning new values to public variables. Each variable
is assigned its new value, and if it has any "config" code associated
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 \fBconfigure\fR method
returns an error.
.RE
.TP
\fIobjName \fBisa \fIclassName\fR
.
Returns non-zero if the given \fIclassName\fR can be found in the
object's heritage, and zero otherwise.
.TP
\fIobjName \fBinfo \fIoption\fR ?\fIargs...\fR?
.
Returns information related to a particular object named
\fIobjName\fR, or to its class definition. The \fIoption\fR
parameter includes the following things, as well as the options
recognized by the usual Tcl "info" command:
.RS
.TP
\fIobjName \fBinfo class\fR
.
Returns the name of the most-specific class for object \fIobjName\fR.
.TP
\fIobjName \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 \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 \fBinfo function\fR ?\fIcmdName\fR? ?\fB-protection\fR? ?\fB-type\fR? ?\fB-name\fR? ?\fB-args\fR? ?\fB-body\fR?
.
With no arguments, this command returns a list of all class methods
and procs. If \fIcmdName\fR 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.
.TP
\fIobjName \fBinfo variable\fR ?\fIvarName\fR? ?\fB-protection\fR? ?\fB-type\fR? ?\fB-name\fR? ?\fB-init\fR? ?\fB-value\fR? ?\fB-config\fR? ?\fB-scope\fR?
.
With no arguments, this command returns a list of all object-specific
variables and common data members. If \fIvarName\fR is specified, it
returns information for a specific data member.
Flags can be specified with \fIvarName\fR in an arbitrary order.
The result is a list of the specific information in exactly the
same order as the flags are specified.
If no flags are given, this command returns a list
as if the followings flags have been specified:
.IP
\fB-protection\fR \fB-type\fR \fB-name\fR \fB-init\fR \fB-value\fR ?\fB-config\fR?
The \fB-config\fR result is only present if \fIvarName\fR is a public
variable. It contains the code that is executed at initialization
of \fIvarName\fR. The \fB-scope\fR flag gives the namespace context
of \fIvarName\fR. Herewith the variable can be accessed from outside
the object like any other variable. It is similar to the result of
the \fBitcl::scope\fR command.
.RE
.SH "CHAINING METHODS/PROCS"
.PP
Sometimes 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:
.PP
.CS
itcl::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
}
}
.CE
.PP
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:
.PP
.CS
itcl::class SmartToaster {
inherit Toaster
method toast {nslices} {
if {$crumbs > 40} {
clean
}
return [Toaster::toast $nslices]
}
}
.CE
.PP
Instead of hard-coding the base class name, we can use the
"chain" command like this:
.PP
.CS
itcl::class SmartToaster {
inherit Toaster
method toast {nslices} {
if {$crumbs > 40} {
clean
}
return [chain $nslices]
}
}
.CE
.PP
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 current class 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.
.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:
.PP
.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"
.CE
.PP
The \fBauto_mkindex\fR command is used to automatically
generate "tclIndex" files.
.PP
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 "C PROCEDURES"
.PP
C procedures can be integrated into an \fB[incr\ Tcl]\fR class
definition to implement methods, procs, and the "config" code
for public variables. Any body that starts with "\fB@\fR"
is treated as the symbolic name for a C procedure.
.PP
Symbolic names are established by registering procedures via
\fBItcl_RegisterC()\fR. This is usually done in the \fBTcl_AppInit()\fR
procedure, which is automatically called when the interpreter starts up.
In the following example, the procedure \fCMy_FooCmd()\fR is registered
with the symbolic name "foo". This procedure can be referenced in
the \fBbody\fR command as "\fC@foo\fR".
.PP
.CS
int
Tcl_AppInit(interp)
Tcl_Interp *interp; /* Interpreter for application. */
{
if (Itcl_Init(interp) == TCL_ERROR) {
return TCL_ERROR;
}
if (Itcl_RegisterC(interp, "foo", My_FooCmd) != TCL_OK) {
return TCL_ERROR;
}
}
.CE
.PP
C procedures are implemented just like ordinary Tcl commands.
See the \fBCrtCommand\fR man page for details. Within the procedure,
class data members can be accessed like ordinary variables
using \fBTcl_SetVar()\fR, \fBTcl_GetVar()\fR, \fBTcl_TraceVar()\fR,
etc. Class methods and procs can be executed like ordinary commands
using \fBTcl_Eval()\fR. \fB[incr\ Tcl]\fR makes this possible by
automatically setting up the context before executing the C procedure.
.PP
This scheme provides a natural migration path for code development.
Classes can be developed quickly using Tcl code to implement the
bodies. An entire application can be built and tested. When
necessary, individual bodies can be implemented with C code to
improve performance.
.SH KEYWORDS
class, object, object-oriented

94
pkgs/itcl4.2.2/doc/code.n Normal file
View File

@@ -0,0 +1,94 @@
'\"
'\" 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.
'\"
.TH code n 3.0 itcl "[incr\ Tcl]"
.so man.macros
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
itcl::code \- capture the namespace context for a code fragment
.SH SYNOPSIS
\fBitcl::code \fR?\fB-namespace \fIname\fR? \fIcommand \fR?\fIarg arg ...\fR?
.BE
.SH DESCRIPTION
.PP
Creates a scoped value for the specified \fIcommand\fR and its
associated \fIarg\fR arguments. A scoped value is a list with three
elements: the "\fC@scope\fR" keyword, a namespace context,
and a value string. For example, the command
.CS
namespace foo {
code puts "Hello World!"
}
.CE
produces the scoped value:
.CS
@scope ::foo {puts {Hello World!}}
.CE
Note that the \fBcode\fR command captures the current namespace
context. If the \fB-namespace\fR flag is specified, then the
current context is ignored, and the \fIname\fR string is used
as the namespace context.
.PP
Extensions like Tk execute ordinary code fragments in the global
namespace. A scoped value captures a code fragment together with
its namespace context in a way that allows it to be executed
properly later. It is needed, for example, to wrap up code fragments
when a Tk widget is used within a namespace:
.CS
namespace foo {
private proc report {mesg} {
puts "click: $mesg"
}
button .b1 -text "Push Me" \
-command [code report "Hello World!"]
pack .b1
}
.CE
The code fragment associated with button \fC.b1\fR only makes
sense in the context of namespace "foo". Furthermore, the
"report" procedure is private, and can only be accessed within
that namespace. The \fBcode\fR command wraps up the code
fragment in a way that allows it to be executed properly
when the button is pressed.
.PP
Also, note that the \fBcode\fR command preserves the integrity
of arguments on the command line. This makes it a natural replacement
for the \fBlist\fR command, which is often used to format Tcl code
fragments. In other words, instead of using the \fBlist\fR command
like this:
.CS
after 1000 [list puts "Hello $name!"]
.CE
use the \fBcode\fR command like this:
.CS
after 1000 [code puts "Hello $name!"]
.CE
This not only formats the command correctly, but also captures
its namespace context.
.PP
Scoped commands can be invoked like ordinary code fragments, with
or without the \fBeval\fR command. For example, the following
statements work properly:
.CS
set cmd {@scope ::foo .b1}
$cmd configure -background red
set opts {-bg blue -fg white}
eval $cmd configure $opts
.CE
Note that scoped commands by-pass the usual protection mechanisms;
the command:
.CS
@scope ::foo {report {Hello World!}}
.CE
can be used to access the "foo::report" proc from any namespace
context, even though it is private.
.SH KEYWORDS
scope, callback, namespace, public, protected, private

127
pkgs/itcl4.2.2/doc/configbody.n Normal file
View File

@@ -0,0 +1,127 @@
'\"
'\" 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.
'\"
.TH configbody n 3.0 itcl "[incr\ Tcl]"
.so man.macros
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
itcl::configbody \- change the "config" code for a public variable
.SH SYNOPSIS
\fBitcl::configbody \fIclassName\fB::\fIvarName body\fR
.BE
.SH DESCRIPTION
.PP
The \fBconfigbody\fR command is used outside of an \fB[incr\ Tcl]\fR
class definition to define or redefine the configuration code
associated with a public variable. Public variables act like
configuration options for an object. They can be modified
outside the class scope using the built-in \fBconfigure\fR method.
Each variable can have a bit of "config" code associate with it
that is automatically executed when the variable is configured.
The \fBconfigbody\fR command can be used to define or redefine
this body of code.
.PP
Like the \fBbody\fR command, this facility allows a class definition
to have separate "interface" and "implementation" parts.
The "interface" part is a \fBclass\fR command with declarations
for methods, procs, instance variables and common variables.
The "implementation" part is a series of \fBbody\fR and
\fBconfigbody\fR commands. If the "implementation" part
is kept in a separate file, it can be sourced again and
again as bugs are fixed, to support interactive development.
When using the "tcl" mode in the \fBemacs\fR editor, the
"interface" and "implementation" parts can be kept in the
same file; as bugs are fixed, individual bodies can be
highlighted and sent to the test application.
.PP
The name "\fIclassName\fB::\fIvarName\fR"
identifies the public variable being updated.
If the \fIbody\fR string starts with "\fB@\fR", it is treated
as the symbolic name for a C procedure. Otherwise, it is
treated as a Tcl command script.
.PP
Symbolic names for C procedures are established by registering
procedures via \fBItcl_RegisterC()\fR. This is usually done
in the \fBTcl_AppInit()\fR procedure, which is automatically called
when the interpreter starts up. In the following example,
the procedure \fCMy_FooCmd()\fR is registered with the
symbolic name "foo". This procedure can be referenced in
the \fBconfigbody\fR command as "\fC@foo\fR".
.CS
int
Tcl_AppInit(interp)
Tcl_Interp *interp; /* Interpreter for application. */
{
if (Itcl_Init(interp) == TCL_ERROR) {
return TCL_ERROR;
}
if (Itcl_RegisterC(interp, "foo", My_FooCmd) != TCL_OK) {
return TCL_ERROR;
}
}
.CE
.SH EXAMPLE
In the following example, a "File" class is defined to represent
open files. Whenever the "-name" option is configured, the
existing file is closed, and a new file is opened. Note that
the "config" code for a public variable is optional. The "-access"
option, for example, does not have it.
.CS
itcl::class File {
private variable fid ""
public variable name ""
public variable access "r"
constructor {args} {
eval configure $args
}
destructor {
if {$fid != ""} {
close $fid
}
}
method get {}
method put {line}
method eof {}
}
itcl::body File::get {} {
return [gets $fid]
}
itcl::body File::put {line} {
puts $fid $line
}
itcl::body File::eof {} {
return [::eof $fid]
}
itcl::configbody File::name {
if {$fid != ""} {
close $fid
}
set fid [open $name $access]
}
#
# See the File class in action:
#
File x
x configure -name /etc/passwd
while {![x eof]} {
puts "=> [x get]"
}
itcl::delete object x
.CE
.SH KEYWORDS
class, object, variable, configure

71
pkgs/itcl4.2.2/doc/delete.n Normal file
View File

@@ -0,0 +1,71 @@
'\"
'\" 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.
'\"
.TH delete n 3.0 itcl "[incr\ Tcl]"
.so man.macros
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
itcl::delete \- delete things in the interpreter
.SH SYNOPSIS
\fBitcl::delete \fIoption\fR ?\fIarg arg ...\fR?
.BE
.SH DESCRIPTION
.PP
The \fBdelete\fR command is used to delete things in the interpreter.
It is implemented as an ensemble, so extensions can add their own
options and extend the behavior of this command. By default, the
\fBdelete\fR command handles the destruction of namespaces.
.PP
The \fIoption\fR argument determines what action is carried out
by the command. The legal \fIoptions\fR (which may be abbreviated)
are:
.TP
\fBdelete class \fIname\fR ?\fIname...\fR?
.
Deletes one or more \fB[incr\ Tcl]\fR classes called \fIname\fR.
This deletes all objects in the class, and all derived classes
as well.
.RS
.PP
If an error is encountered while destructing an object, it will
prevent the destruction of the class and any remaining objects.
To destroy the entire class without regard for errors, use the
"\fBdelete namespace\fR" command.
.RE
.TP
\fBdelete object \fIname\fR ?\fIname...\fR?
.
Deletes one or more \fB[incr\ Tcl]\fR objects called \fIname\fR.
An object is deleted by invoking all destructors in its class
hierarchy, in order from most- to least-specific. If all destructors
are successful, data associated with the object is deleted and
the \fIname\fR is removed as a command from the interpreter.
.RS
.PP
If the access command for an object resides in another namespace,
then its qualified name can be used:
.PP
.CS
itcl::delete object foo::bar::x
.CE
.PP
If an error is encountered while destructing an object, the
\fBdelete\fR command is aborted and the object remains alive.
To destroy an object without regard for errors, use the
"\fBrename\fR" command to destroy the object access command.
.RE
.TP
\fBdelete namespace \fIname\fR ?\fIname...\fR?
.
Deletes one or more namespaces called \fIname\fR. This deletes
all commands and variables in the namespace, and deletes all
child namespaces as well. When a namespace is deleted, it is
automatically removed from the import lists of all other namespaces.
.SH KEYWORDS
namespace, proc, variable, ensemble

178
pkgs/itcl4.2.2/doc/ensemble.n Normal file
View File

@@ -0,0 +1,178 @@
'\"
'\" 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.
'\"
.TH ensemble n 3.0 itcl "[incr\ Tcl]"
.so man.macros
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
itcl::ensemble \- create or modify a composite command
.SH SYNOPSIS
.nf
\fBitcl::ensemble \fIensName\fR ?\fIcommand arg arg...\fR?
.fi
or
.nf
\fBensemble \fIensName\fR {
\fBpart \fIpartName args body\fR
\fI...\fR
\fBensemble \fIpartName\fR {
\fBpart \fIsubPartName args body\fR
\fBpart \fIsubPartName args body\fR
\fI...\fR
}
}
.fi
.BE
.SH DESCRIPTION
.PP
The \fBensemble\fR command is used to create or modify a composite
command. See the section \fBWHAT IS AN ENSEMBLE?\fR below for a
brief overview of ensembles.
.PP
If the \fBensemble\fR command finds an existing ensemble called
\fIensName\fR, it updates that ensemble. Otherwise, it creates an
ensemble called \fIensName\fR. If the \fIensName\fR is a simple name
like "foo", then an ensemble command named "foo" is added to the
current namespace context. If a command named "foo" already exists
in that context, then it is deleted. If the \fIensName\fR contains
namespace qualifiers like "a::b::foo", then the namespace path is
resolved, and the ensemble command is added that namespace context.
Parent namespaces like "a" and "b" are created automatically, as needed.
.PP
If the \fIensName\fR contains spaces like "a::b::foo bar baz", then
additional words like "bar" and "baz" are treated as sub-ensembles.
Sub-ensembles are merely parts within an ensemble; they do not have
a Tcl command associated with them. An ensemble like "foo" can
have a sub-ensemble called "foo bar", which in turn can have a
sub-ensemble called "foo bar baz". In this case, the sub-ensemble
"foo bar" must be created before the sub-ensemble "foo bar baz"
that resides within it.
.PP
If there are any arguments following \fIensName\fR, then they are
treated as commands, and they are executed to update the ensemble.
The following commands are recognized in this context: \fBpart\fR
and \fBensemble\fR.
.PP
The \fBpart\fR command defines a new part for the ensemble.
Its syntax is identical to the usual \fBproc\fR command, but
it defines a part within an ensemble, instead of a Tcl command.
If a part called \fIpartName\fR already exists within the ensemble,
then the \fBpart\fR command returns an error.
.PP
The \fBensemble\fR command can be nested inside another \fBensemble\fR
command to define a sub-ensemble.
.SH "WHAT IS AN ENSEMBLE?"
.PP
The usual "info" command is a composite command--the command name
\fBinfo\fR must be followed by a sub-command like \fBbody\fR or \fBglobals\fR.
We will refer to a command like \fBinfo\fR as an \fIensemble\fR, and to
sub-commands like \fBbody\fR or \fBglobals\fR as its \fIparts\fR.
.PP
Ensembles can be nested. For example, the \fBinfo\fR command has
an ensemble \fBinfo namespace\fR within it. This ensemble has parts
like \fBinfo namespace all\fR and \fBinfo namespace children\fR.
.PP
With ensembles, composite commands can be created and extended
in an automatic way. Any package can find an existing ensemble
and add new parts to it. So extension writers can add their
own parts, for example, to the \fBinfo\fR command.
.PP
The ensemble facility manages all of the part names and keeps
track of unique abbreviations. Normally, you can abbreviate
\fBinfo complete\fR to \fBinfo comp\fR. But if an extension adds the
part \fBinfo complexity\fR, the minimum abbreviation for \fBinfo complete\fR
becomes \fBinfo complet\fR.
.PP
The ensemble facility not only automates the construction of
composite commands, but it automates the error handling as well.
If you invoke an ensemble command without specifying a part name,
you get an automatically generated error message that summarizes
the usage information. For example, when the \fBinfo\fR command
is invoked without any arguments, it produces the following error
message:
.PP
.CS
wrong # args: should be one of...
info args procname
info body procname
info cmdcount
info commands ?pattern?
info complete command
info context
info default procname arg varname
info exists varName
info globals ?pattern?
info level ?number?
info library
info locals ?pattern?
info namespace option ?arg arg ...?
info patchlevel
info procs ?pattern?
info protection ?-command? ?-variable? name
info script
info tclversion
info vars ?pattern?
info which ?-command? ?-variable? ?-namespace? name
.CE
.PP
You can also customize the way an ensemble responds to errors.
When an ensemble encounters an unspecified or ambiguous part
name, it looks for a part called \fB@error\fR. If it exists,
then it is used to handle the error. This part will receive all
of the arguments on the command line starting with the offending
part name. It can find another way of resolving the command,
or generate its own error message.
.SH EXAMPLE
.PP
We could use an ensemble to clean up the syntax of the various
"wait" commands in Tcl/Tk. Instead of using a series of
strange commands like this:
.PP
.CS
vwait x
tkwait visibility .top
tkwait window .
.CE
.PP
we could use commands with a uniform syntax, like this:
.PP
.CS
wait variable x
wait visibility .top
wait window .
.CE
.PP
The Tcl package could define the following ensemble:
.PP
.CS
itcl::ensemble wait part variable {name} {
uplevel vwait $name
}
.CE
.PP
The Tk package could add some options to this ensemble, with a
command like this:
.PP
.CS
itcl::ensemble wait {
part visibility {name} {
tkwait visibility $name
}
part window {name} {
tkwait window $name
}
}
.CE
.PP
Other extensions could add their own parts to the \fBwait\fR command
too.
.SH KEYWORDS
ensemble, part, info

77
pkgs/itcl4.2.2/doc/find.n Normal file
View File

@@ -0,0 +1,77 @@
'\"
'\" 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.
'\"
.TH find n 3.0 itcl "[incr\ Tcl]"
.so man.macros
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
itcl::find \- search for classes and objects
.SH SYNOPSIS
\fBitcl::find \fIoption\fR ?\fIarg arg ...\fR?
.BE
.SH DESCRIPTION
.PP
The \fBfind\fR command is used to find classes and objects
that are available in the current interpreter. Classes and objects
are reported first in the active namespace, then in all other
namespaces in the interpreter.
.PP
The \fIoption\fR argument determines what action is carried out
by the command. The legal \fIoptions\fR (which may be abbreviated)
are:
.TP
\fBfind classes ?\fIpattern\fR?
.
Returns a list of [incr Tcl] classes. Classes in the current
namespace are listed first, followed by classes in all other
namespaces in the interpreter. If the optional \fIpattern\fR
is specified, then the reported names are compared using the rules
of the "\fBstring match\fR" command, and only matching names are
reported.
.RS
.PP
If a class resides in the current namespace context, this command
reports its simple name--without any qualifiers. However, if the
\fIpattern\fR contains \fB::\fR qualifiers, or if the class resides
in another context, this command reports its fully-qualified name.
Therefore, you can use the following command to obtain a list where
all names are fully-qualified:
.PP
.CS
itcl::find classes ::*
.CE
.RE
.TP
\fBfind objects ?\fIpattern\fR? ?\fB-class \fIclassName\fR? ?\fB-isa \fIclassName\fR?
.
Returns a list of [incr Tcl] objects. Objects in the current
namespace are listed first, followed by objects in all other
namespaces in the interpreter. If the optional \fIpattern\fR is
specified, then the reported names are compared using the rules
of the "\fBstring match\fR" command, and only matching names are
reported.
If the optional "\fB-class\fR" parameter is specified, this list is
restricted to objects whose most-specific class is \fIclassName\fR.
If the optional "\fB-isa\fR" parameter is specified, this list is
further restricted to objects having the given \fIclassName\fR
anywhere in their heritage.
.RS
.PP
If an object resides in the current namespace context, this command
reports its simple name--without any qualifiers. However, if the
\fIpattern\fR contains \fB::\fR qualifiers, or if the object resides
in another context, this command reports its fully-qualified name.
Therefore, you can use the following command to obtain a list where
all names are fully-qualified:
.PP
.CS
itcl::find objects ::*
.CE
.RE
.SH KEYWORDS
class, object, search, import

71
pkgs/itcl4.2.2/doc/is.n Normal file
View File

@@ -0,0 +1,71 @@
'\"
'\" 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.
'\"
.TH is n 3.3 itcl "[incr\ Tcl]"
.so man.macros
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
itcl::is \- test argument to see if it is a class or an object
.SH SYNOPSIS
\fBitcl::is \fIoption\fR ?\fIarg arg ...\fR?
.BE
.SH DESCRIPTION
.PP
The \fBis\fR command is used to check if the argument given is
a class or an object; depending on the option given. If the argument
if a class or object, then 1 is returned. Otherwise, 0 is returned.
The \fBis\fR command also recognizes the commands wrapped in the
itcl \fBcode\fR command.
.PP
The \fIoption\fR argument determines what action is carried out
by the command. The legal \fIoptions\fR (which may be abbreviated)
are:
.TP
\fBis class \fIcommand\fR
.
Returns 1 if command is a class, and returns 0 otherwise.
.RS
.PP
The fully qualified name of the class needs to be given as the \fIcommand\fR
argument. So, if a class resides in a namespace, then the namespace needs to
be specified as well. So, if a class \fBC\fR resides in a namespace \fBN\fR, then
the command should be called like:
.PP
.CS
\fBis N::C\fR
or
\fBis ::N::C\fR
.CE
.RE
.TP
\fBis\fR object ?\fB-class \fIclassName\fR? \fIcommand\fR
.
Returns 1 if \fIcommand\fR is an object, and returns 0 otherwise.
.RS
.PP
If the optional "\fB-class\fR" parameter is specified, then the
\fIcommand\fR will be checked within the context of the class
given. Note that \fIclassName\fR has to exist. If not, then an
error will be given. So, if \fIclassName\fR is uncertain to be
a class, then the programmer will need to check it's existance
beforehand, or wrap it in a catch statement.
.PP
So, if \fBc\fR is an object in the class \fBC\fR, in namespace N then
these are the possibilities (all return 1):
.PP
.CS
set obj [N::C c]
itcl::is object N::c
itcl::is object c
itcl::is object $obj
itcl::is object [itcl::code c]
.CE
.RE
.SH KEYWORDS
class, object

145
pkgs/itcl4.2.2/doc/itcl.n Normal file
View File

@@ -0,0 +1,145 @@
'\"
'\" 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.
'\"
.TH itcl n 3.0 itcl "[incr\ Tcl]"
.so man.macros
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
itcl \- object-oriented extensions to Tcl
.BE
.SH DESCRIPTION
.PP
\fB[incr\ Tcl]\fR provides object-oriented extensions to Tcl, much as
C++ provides object-oriented extensions to C. The emphasis of this
work, however, is not to create a whiz-bang object-oriented
programming environment. Rather, it is to support more structured
programming practices in Tcl without changing the flavor of the language.
More than anything else, \fB[incr\ Tcl]\fR provides a means of
encapsulating related procedures together with their shared data
in a namespace that is hidden from the outside world.
It encourages better programming by promoting the object-oriented
"library" mindset. It also allows for code re-use through inheritance.
.SH CLASSES
.PP
The fundamental construct in \fB[incr\ Tcl]\fR is the class definition.
Each class acts as a template for actual objects that can be created.
Each object has its own unique bundle of data, which contains instances
of the "variables" defined in the class. Special procedures called
"methods" are used to manipulate individual objects. Methods are just
like the operations that are used to manipulate Tk widgets. The
"\fBbutton\fR" widget, for example, has methods such as "flash" and
"invoke" that cause a particular button to blink and invoke its command.
.PP
Within the body of a method, the "variables" defined in the class
are automatically available. They need not be declared with anything
like the \fBglobal\fR command. Within another class method, a method
can be invoked like any other command\-simply by using its name.
From any other context, the method name must be prefaced by an object
name, which provides a context for the data that the method can access.
.PP
Each class has its own namespace containing things that are common
to all objects which belong to the class. For example, "common" data
members are shared by all objects in the class. They are global
variables that exist in the class namespace, but since they are
included in the class definition, they need not be declared using
the \fBglobal\fR command; they are automatically available to any
code executing in the class context. A class can also create
ordinary global variables, but these must be declared using the
\fBglobal\fR command each time they are used.
.PP
Classes can also have ordinary procedures declared as "procs".
Within another class method or proc, a proc can be invoked like
any other command\-simply by using its name. From any other context,
the procedure name should be qualified with the class namespace
like "\fIclassName\fB::\fIproc\fR". Class procs execute in the
class context, and therefore have automatic access to all "common"
data members. However, they cannot access object-specific "variables",
since they are invoked without reference to any specific object.
They are usually used to perform generic operations which affect
all objects belonging to the class.
.PP
Each of the elements in a class can be declared "public", "protected"
or "private". Public elements can be accessed by the class, by
derived classes (other classes that inherit this class), and by
external clients that use the class. Protected elements can be
accessed by the class, and by derived classes. Private elements
are only accessible in the class where they are defined.
.PP
The "public" elements within a class define its interface to the
external world. Public methods define the operations that can
be used to manipulate an object. Public variables are recognized
as configuration options by the "configure" and "cget" methods
that are built into each class. The public interface says
\fIwhat\fR an object will do but not \fIhow\fR it will do it.
Protected and private members, along with the bodies of class
methods and procs, provide the implementation details. Insulating
the application developer from these details leaves the class designer
free to change them at any time, without warning, and without affecting
programs that rely on the class. It is precisely this encapsulation
that makes object-oriented programs easier to understand and maintain.
.PP
The fact that \fB[incr\ Tcl]\fR objects look like Tk widgets is
no accident. \fB[incr\ Tcl]\fR was designed this way, to blend
naturally into a Tcl/Tk application. But \fB[incr\ Tcl]\fR
extends the Tk paradigm from being merely object-based to being
fully object-oriented. An object-oriented system supports
inheritance, allowing classes to share common behaviors by
inheriting them from an ancestor or base class. Having a base
class as a common abstraction allows a programmer to treat
related classes in a similar manner. For example, a toaster
and a blender perform different (specialized) functions, but
both share the abstraction of being appliances. By abstracting
common behaviors into a base class, code can be \fIshared\fR rather
than \fIcopied\fR. The resulting application is easier to
understand and maintain, and derived classes (e.g., specialized
appliances) can be added or removed more easily.
.PP
This description was merely a brief overview of object-oriented
programming and \fB[incr\ Tcl]\fR. A more tutorial introduction is
presented in the paper included with this distribution. See the
\fBclass\fR command for more details on creating and using classes.
.SH NAMESPACES
.PP
\fB[incr\ Tcl]\fR now includes a complete namespace facility.
A namespace is a collection of commands and global variables that
is kept apart from the usual global scope. This allows Tcl code
libraries to be packaged in a well-defined manner, and prevents
unwanted interactions with other libraries. A namespace can also
have child namespaces within it, so one library can contain its
own private copy of many other libraries. A namespace can also
be used to wrap up a group of related classes. The global scope
(named "\fC::\fR") is the root namespace for an interpreter; all
other namespaces are contained within it.
.PP
See the \fBnamespace\fR command for details on creating and
using namespaces.
.SH MEGA-WIDGETS
.PP
Mega-widgets are high-level widgets that are constructed using
Tk widgets as component parts, usually without any C code. A
fileselectionbox, for example, may have a few listboxes, some
entry widgets and some control buttons. These individual widgets
are put together in a way that makes them act like one big
widget.
.PP
\fB[incr\ Tk]\fR is a framework for building mega-widgets. It
uses \fB[incr\ Tcl]\fR to support the object paradigm, and adds
base classes which provide default widget behaviors. See the
\fBitk\fR man page for more details.
.PP
\fB[incr\ Widgets]\fR is a library of mega-widgets built using
\fB[incr\ Tk]\fR. It contains more than 30 different widget
classes that can be used right out of the box to build Tcl/Tk
applications. Each widget class has its own man page describing
the features available.
.SH KEYWORDS
class, object, object-oriented, namespace, mega-widget

46
pkgs/itcl4.2.2/doc/itclcomponent.n Normal file
View File

@@ -0,0 +1,46 @@
'\"
'\" Copyright (c) 2008 Arnulf Wiedemann
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH component n 4.0 itcl "[incr\ Tcl]"
.so man.macros
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
itcl::component \- define components for extendedclass, widget or widgetadaptor
.PP
Parts of this description are "borrowed" from Tcl extension [snit], as the functionality is mostly identical.
.SH WARNING!
This is new functionality in [incr Tcl] where the API can still change!!
.SH SYNOPSIS
.nf
\fBpublic component \fIcomp\fR ?\fB-inherit\fR?
\fBprotected component \fIcomp\fR ?\fB-inherit\fR?
\fBprivate component \fIcomp\fR ?\fB-inherit\fR?
.fi
.BE
.SH DESCRIPTION
.PP
The \fBcomponent\fR command is used inside an \fB[incr\ Tcl]\fR
extendedclass/widget/widgetadaptor definition to define components.
.PP
Explicitly declares a component called comp, and automatically defines
the component's instance variable.
.PP
If the \fI-inherit\fR option is specified then all unknown methods
and options will be delegated to this component. The name -inherit
implies that instances of this new type inherit, in a sense,
the methods and options of the component. That is,
-inherit yes is equivalent to:
.PP
.CS
component mycomp
delegate option * to mycomp
delegate method * to mycomp
.CE
.SH KEYWORDS
component, widget, widgetadaptor, extendedclass

202
pkgs/itcl4.2.2/doc/itcldelegate.n Normal file
View File

@@ -0,0 +1,202 @@
'\"
'\" Copyright (c) 2008 Arnulf Wiedemann
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH delegation n 4.0 itcl "[incr\ Tcl]"
.so man.macros
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
itcl::delegation \- delegate methods, procs or options to other objects
.PP
Parts of this description are "borrowed" from Tcl extension [snit], as the functionality is mostly identical.
.SH WARNING!
This is new functionality in [incr Tcl] where the API can still change!!
.SH SYNOPSIS
.nf
\fBdelegate method \fImethodName\fB to \fIcomponentName\fR ?\fBas \fItargetName\fR?
\fBdelegate method \fImethodName\fR ?\fBto \fIcomponentName\fR? \fBusing \fIpattern\fR
\fBdelegate method \fI* ?\fBto \fIcomponentName\fR? ?\fBusing \fIpattern\fR? ?\fBexcept \fImethodName methodName ...\fR?
\fBdelegate proc \fIprocName\fB to \fIcomponentName\fR ?\fBas \fItargetName\fR?
\fBdelegate proc \fIprocName\fR ?\fBto \fIcomponentName\fR? \fBusing \fIpattern\fR
\fBdelegate proc \fI*\fR ?\fBto \fIcomponentName\fR? ?\fBusing \fIpattern\fR? ?\fBexcept \fIprocName procName ...\fR?
\fBdelegate option \fIoptionSpec\fB to \fIcomponentName\fR
\fBdelegate option \fIoptionSpec\fB to \fIcomponentName\fR \fBas \fItargetname\fR?
\fBdelegate option \fI* \fBto \fIcomponentName\fR
\fBdelegate option \fI* \fBto \fIcomponentName\fR \fBexcept \fIoptionName optionname ...\fR
.fi
.BE
.SH DESCRIPTION
.PP
The \fBdelegate\fR command is used inside an \fB[incr\ Tcl]\fR
extendedclass/widget/widgetadaptor definition to delegate
methods/procs/options to other objects for handling.
.TP
\fBdelegate method \fImethodName\fB to \fIcomponentName\fR ?\fBas \fItargetName\fR?
.
This form of delegate method delegates method methodName to component
componentName. That is, when method methdoNameame is called on an instance of
this type, the method and its arguments will be passed to the named component's
command instead. That is, the following statement
.RS
.PP
.CS
delegate method wag to tail
.CE
.PP
is roughly equivalent to this explicitly defined method:
.PP
.CS
method wag {args} {
uplevel $tail wag $args
}
.CE
.PP
The optional \fBas\fR clause allows you to specify the delegated method
name and possibly add some arguments:
.PP
.CS
delegate method wagtail to tail as "wag briskly"
.CE
.PP
A method cannot be both locally defined and delegated.
.RE
.TP
\fBdelegate method \fImethodName\fR ?\fBto \fIcomponentName\fR? \fBusing \fIpattern\fR
.
In this form of the delegate statement, the \fBusing\fR clause is used to
specify the precise form of the command to which method name name is delegated.
The \fBto\fR clause is optional, since the chosen command might not involve
any particular component.
.RS
.PP
The value of the using clause is a list that may contain any or all of the
following substitution codes; these codes are substituted with the described
value to build the delegated command prefix. Note that the following two
statements are equivalent:
.PP
.CS
delegate method wag to tail
delegate method wag to tail using "%c %m"
.CE
.PP
Each element of the list becomes a single element of the delegated command
--it is never reparsed as a string.
.PP
Substitutions:
.TP
\fB%%\fR
.
This is replaced with a single "%". Thus, to pass the string "%c" to the
command as an argument, you'd write "%%c".
.TP
\fB%c\fR
.
This is replaced with the named component's command.
.TP
\fB%j\fR
.
This is replaced by the method name; if the name consists of multiple tokens,
they are joined by underscores ("_").
.TP
\fB%m\fR
.
This is replaced with the final token of the method name; if the method name
has one token, this is identical to \fB%M\fR.
.TP
\fB%M\fR
.
This is replaced by the method name; if the name consists of multiple tokens,
they are joined by space characters.
.TP
\fB%n\fR
.
This is replaced with the name of the instance's private namespace.
.TP
\fB%s\fR
.
This is replaced with the name of the instance command.
.TP
\fB%t\fR
.
This is replaced with the fully qualified type name.
.TP
\fB%w\fR
.
This is replaced with the original name of the instance command; for Itcl
widgets and widget adaptors, it will be the Tk window name. It remains
constant, even if the instance command is renamed.
.RE
.TP
\fBdelegate method \fI*\fR ?\fBto \fIcomponentName\fR? ?\fBusing \fIpattern\fR? ?\fBexcept \fImethodName methodName ...\fR?
.
In this form all unknown method names are delegeted to the specified
component. The except clause can be used to specify a list of exceptions,
i.e., method names that will not be so delegated. The using clause
is defined as given above. In this form, the statement must
contain the to clause, the using clause, or both.
.RS
.PP
In fact, the "*" can be a list of two or more tokens whose last element
is "*", as in the following example:
.PP
.CS
delegate method {tail *} to tail
.CE
.PP
This implicitly defines the method tail whose subcommands will be
delegated to the tail component.
.PP
The definitions for \fBdelegate proc\fR ... are the same as for method,
the only difference being, that this is for procs.
.RE
.TP
\fBdelegate option \fInamespec\fB to \fIcomp\fR
.TP
\fBdelegate option namespec to comp as target\fR
.TP
\fBdelegate option * to \fIcomp\fR
.TP
\fBdelegate option * to \fIcomp \fBexcept \fIexceptions\fR
.
Defines a delegated option; the namespec is defined as for the option
statement. When the configure, configurelist, or cget instance method is
used to set or retrieve the option's value, the equivalent configure or
cget command will be applied to the component as though the option was
defined with the following \fB-configuremethod\fR and \fB-cgetmethod\fR:
.RS
.PP
.CS
method ConfigureMethod {option value} {
$comp configure $option $value
}
method CgetMethod {option} {
return [$comp cget $option]
}
.CE
.PP
Note that delegated options never appear in the \fBitcl_options\fR array.
If the as clause is specified, then the target option name is used in place
of name.
.RE
.TP
\fBdelegate \fIoption\fB *\fR ?\fBexcept\fI optionName optionName ...\fR?
.
This form delegates all unknown options to the specified component.
The except clause can be used to specify a list of exceptions,
i.e., option names that will not be so delegated.
.RS
.PP
\fBWarning:\fR options can only be delegated to a component if it supports the
\fBconfigure\fR and \fBcget\fR instance methods.
.PP
An option cannot be both locally defined and delegated. TBD: Continue from here.
.RE
.SH KEYWORDS
delegation, option, method, proc

547
pkgs/itcl4.2.2/doc/itclextendedclass.n Normal file
View File

@@ -0,0 +1,547 @@
'\"
'\" Copyright (c) 2008 Arnulf Wiedemann
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH extendedclass n "4.0" itcl "[incr\ Tcl]"
.so man.macros
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
itcl::extendedclass \- create a extendedclass of objects
.SH WARNING!
This is new functionality in [incr Tcl] where the API can still change!!
.SH SYNOPSIS
.nf
\fBitcl::extendedclass \fIextendedclassName\fR \fB{\fR
\fBinherit \fIbaseExtendedclass\fR ?\fIbaseExtendedclass\fR...?
\fBconstructor \fIargs\fR ?\fIinit\fR? \fIbody\fR
\fBdestructor \fIbody\fR
\fBpublic method \fIname\fR ?\fIargs\fR? ?\fIbody\fR?
\fBprotected method \fIname\fR ?\fIargs\fR? ?\fIbody\fR?
\fBprivate method \fIname\fR ?\fIargs\fR? ?\fIbody\fR?
\fBpublic proc \fIname\fR ?\fIargs\fR? ?\fIbody\fR?
\fBprotected proc \fIname\fR ?\fIargs\fR? ?\fIbody\fR?
\fBprivate proc \fIname\fR ?\fIargs\fR? ?\fIbody\fR?
\fBpublic variable \fIvarName\fR ?\fIinit\fR? ?\fIconfig\fR?
\fBprotected variable \fIvarName\fR ?\fIinit\fR? ?\fIconfig\fR?
\fBprivate variable \fIvarName\fR ?\fIinit\fR? ?\fIconfig\fR?
\fBpublic common \fIvarName\fR ?\fIinit\fR?
\fBprotected common \fIvarName\fR ?\fIinit\fR?
\fBprivate common \fIvarName\fR ?\fIinit\fR?
\fBpublic \fIcommand\fR ?\fIarg arg ...\fR?
\fBprotected \fIcommand\fR ?\fIarg arg ...\fR?
\fBprivate \fIcommand\fR ?\fIarg arg ...\fR?
\fB<delegation info>\fR see delegation page
\fB<option info>\fR see option page
\fBset \fIvarName\fR ?\fIvalue\fR?
\fBarray \fIoption\fR ?\fIarg arg ...\fR?
\fB}\fR
\fIextendedclassName objName\fR ?\fIarg arg ...\fR?
\fIobjName method\fR ?\fIarg arg ...\fR?
\fIextendedclassName::proc\fR ?\fIarg arg ...\fR?
.fi
.BE
.SH DESCRIPTION
.PP
The fundamental construct in \fB[incr\ Tcl]\fR is the extendedclass definition.
Each extendedclass acts as a template for actual objects that can be created.
The extendedclass itself is a namespace which contains things common to all
objects. Each object has its own unique bundle of data which contains
instances of the "variables" defined in the extendedclass definition. Each
object also has a built-in variable named "this", which contains the
name of the object. Extendedclasses can also have "common" data members that
are shared by all objects in a extendedclass.
.PP
Two types of functions can be included in the extendedclass definition.
"Methods" are functions which operate on a specific object, and
therefore have access to both "variables" and "common" data members.
"Procs" are ordinary procedures in the extendedclass namespace, and only
have access to "common" data members.
.PP
If the body of any method or proc starts with "\fB@\fR", it is treated
as the symbolic name for a C procedure. Otherwise, it is treated as
a Tcl code script. See below for details on registering and using
C procedures.
.PP
A extendedclass can only be defined once, although the bodies of extendedclass
methods and procs can be defined again and again for interactive
debugging. See the \fBbody\fR and \fBconfigbody\fR commands for
details.
.PP
Each namespace can have its own collection of objects and extendedclasses.
The list of extendedclasses available in the current context can be queried
using the "\fBitcl::find extendedclasses\fR" command, and the list of objects,
with the "\fBitcl::find objects\fR" command.
.PP
A extendedclass can be deleted using the "\fBdelete extendedclass\fR" command.
Individual objects can be deleted using the "\fBdelete object\fR"
command.
.SH "CLASS DEFINITIONS"
.TP
\fBextendedclass \fIextendedclassName definition\fR
.
Provides the definition for a extendedclass named \fIextendedclassName\fR. If
the extendedclass \fIextendedclassName\fR already exists, or if a command called
\fIextendedclassName\fR exists in the current namespace context, this
command returns an error. If the extendedclass definition is successfully
parsed, \fIextendedclassName\fR becomes a command in the current context,
handling the creation of objects for this extendedclass.
.PP
The extendedclass \fIdefinition\fR is evaluated as a series of Tcl
statements that define elements within the extendedclass. The following
extendedclass definition commands are recognized:
.RS
.TP
\fBinherit \fIbaseExtendedclass\fR ?\fIbaseExtendedclass\fR...?
.
Causes the current extendedclass to inherit characteristics from one or
more base extendedclasses. Extendedclasses must have been defined by a previous
\fBextendedclass\fR command, or must be available to the auto-loading
facility (see "AUTO-LOADING" below). A single extendedclass definition
can contain no more than one \fBinherit\fR command.
.RS
.PP
The order of \fIbaseExtendedclass\fR names in the \fBinherit\fR list
affects the name resolution for extendedclass members. When the same
member name appears in two or more base extendedclasses, the base extendedclass
that appears first in the \fBinherit\fR list takes precedence.
For example, if extendedclasses "Foo" and "Bar" both contain the member
"x", and if another extendedclass has the "\fBinherit\fR" statement:
.PP
.CS
inherit Foo Bar
.CE
.PP
then the name "x" means "Foo::x". Other inherited members named
"x" must be referenced with their explicit name, like "Bar::x".
.RE
.TP
\fBconstructor \fIargs\fR ?\fIinit\fR? \fIbody\fR
.
Declares the \fIargs\fR argument list and \fIbody\fR used for
the constructor, which is automatically invoked whenever an
object is created.
.RS
.PP
Before the \fIbody\fR is executed, the
optional \fIinit\fR statement is used to invoke any base extendedclass
constructors that require arguments. Variables in the \fIargs\fR
specification can be accessed in the \fIinit\fR code fragment,
and passed to base extendedclass constructors. After evaluating the
\fIinit\fR statement, any base extendedclass constructors that have
not been executed are invoked automatically without arguments.
This ensures that all base extendedclasses are fully constructed before
the constructor \fIbody\fR is executed. By default, this
scheme causes constructors to be invoked in order from least-
to most-specific. This is exactly the opposite of the order
that extendedclasses are reported by the \fBinfo heritage\fR command.
.PP
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.
.RE
.TP
\fBdestructor \fIbody\fR
.
Declares the \fIbody\fR used for the destructor, which is automatically
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.
.PP
When an object is destroyed, all destructors in its extendedclass hierarchy
are invoked in order from most- to least-specific. This is the
order that the extendedclasses are reported by the "\fBinfo heritage\fR"
command, and it is exactly the opposite of the default constructor
order.
.RE
.TP
\fBmethod \fIname\fR ?\fIargs\fR? ?\fIbody\fR?
.
Declares a method called \fIname\fR. When the method \fIbody\fR is
executed, it will have automatic access to object-specific variables
and common data members.
.RS
.PP
If the \fIargs\fR list is specified, it establishes the usage
information for this method. The \fBbody\fR command can be used
to redefine the method body, but the \fIargs\fR list must match
this specification.
.PP
Within the body of another extendedclass method, a method can be invoked
like any other command\-simply by using its name. Outside of the
extendedclass context, the method name must be prefaced an object name,
which provides the context for the data that it manipulates.
Methods in a base extendedclass that are redefined in the current extendedclass,
or hidden by another base extendedclass, can be qualified using the
"\fIextendedclassName\fR::\fImethod\fR" syntax.
.RE
.TP
\fBproc \fIname\fR ?\fIargs\fR? ?\fIbody\fR?
.
Declares a proc called \fIname\fR. A proc is an ordinary procedure
within the extendedclass namespace. Unlike a method, a proc is invoked
without referring to a specific object. When the proc \fIbody\fR is
executed, it will have automatic access only to common data members.
.RS
.PP
If the \fIargs\fR list is specified, it establishes the usage
information for this proc. The \fBbody\fR command can be used
to redefine the proc body, but the \fIargs\fR list must match
this specification.
.PP
Within the body of another extendedclass method or proc, 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 "\fIextendedclassName\fB::\fIproc\fR". Procs in
a base extendedclass that are redefined in the current extendedclass, or hidden
by another base extendedclass, can also be accessed via their qualified
name.
.RE
.TP
\fBvariable \fIvarName\fR ?\fIinit\fR? ?\fIconfig\fR?
.
Defines an object-specific variable named \fIvarName\fR. All
object-specific variables are automatically available in extendedclass
methods. They need not be declared with anything like the
\fBglobal\fR command.
.RS
.PP
If the optional \fIinit\fR string 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 set
within the constructor and used as arrays.
.PP
The optional \fIconfig\fR script is only allowed for public variables.
If specified, this code fragment is executed whenever a public
variable is modified by the built-in "configure" method. The
\fIconfig\fR script can also be specified outside of the extendedclass
definition using the \fBconfigbody\fR command.
.RE
.TP
\fBcommon \fIvarName\fR ?\fIinit\fR?
.
Declares a common variable named \fIvarName\fR. Common variables
reside in the extendedclass namespace and are shared by all objects belonging
to the extendedclass. They are just like global variables, except that
they need not be declared with the usual \fBglobal\fR command.
They are automatically visible in all extendedclass methods and procs.
.RS
.PP
If the optional \fIinit\fR 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 \fBset\fR and \fBarray\fR commands
and used as arrays.
.PP
Once a common data member has been defined, it can be set using
\fBset\fR and \fBarray\fR commands within the extendedclass definition.
This allows common data members to be initialized as arrays.
For example:
.PP
.CS
itcl::extendedclass Foo {
common boolean
set boolean(true) 1
set boolean(false) 0
}
.CE
.PP
Note that if common data members are initialized within the
constructor, they get initialized again and again whenever new
objects are created.
.RE
.TP
\fBpublic \fIcommand\fR ?\fIarg arg ...\fR?
.TP
\fBprotected \fIcommand\fR ?\fIarg arg ...\fR?
.TP
\fBprivate \fIcommand\fR ?\fIarg arg ...\fR?
.
These commands are used to set the protection level for extendedclass
members that are created when \fIcommand\fR is evaluated.
The \fIcommand\fR is usually \fBmethod\fR, \fBproc\fR,
\fBvariable\fR or\fBcommon\fR, and the remaining \fIarg\fR's
complete the member definition. However, \fIcommand\fR can
also be a script containing many different member definitions,
and the protection level will apply to all of the members
that are created.
.SH "CLASS USAGE"
.PP
Once a extendedclass has been defined, the extendedclass name can be used as a
command to create new objects belonging to the extendedclass.
.TP
\fIextendedclassName objName\fR ?\fIargs...\fR?
.
Creates a new object in extendedclass \fIextendedclassName\fR with the name \fIobjName\fR.
Remaining arguments are passed to the constructor of the most-specific
extendedclass. This in turn passes arguments to base extendedclass constructors before
invoking its own body of commands. If construction is successful, a
command called \fIobjName\fR is created in the current namespace context,
and \fIobjName\fR 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.
.RS
.PP
If \fIobjName\fR contains the string "\fB#auto\fR", that string is
replaced with an automatically generated name. Names have the
form \fIextendedclassName<number>\fR, where the \fIextendedclassName\fR part is
modified to start with a lowercase letter. In extendedclass "Toaster",
for example, the "\fB#auto\fR" specification would produce names
like toaster0, toaster1, etc. Note that "\fB#auto\fR" can be
also be buried within an object name:
.PP
.CS
fileselectiondialog .foo.bar.#auto -background red
.CE
.PP
This would generate an object named ".foo.bar.fileselectiondialog0".
.RE
.SH "OBJECT USAGE"
.PP
Once an object has been created, the object name can be used
as a command to invoke methods that operate on the object.
.TP
\fIobjName method\fR ?\fIargs...\fR?
.
Invokes a method named \fImethod\fR on an object named \fIobjName\fR.
Remaining arguments are passed to the argument list for the
method. The method name can be "constructor", "destructor",
any method name appearing in the extendedclass definition, or any of
the following built-in methods.
.SH "BUILT-IN METHODS"
.TP
\fIobjName\fR \fBcget option\fR
.
Provides access to public variables as configuration options. This
mimics the behavior of the usual "cget" operation for Tk widgets.
The \fIoption\fR argument is a string of the form "\fB-\fIvarName\fR",
and this method returns the current value of the public variable
\fIvarName\fR.
.TP
\fIobjName\fR \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
.
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.
.RS
.PP
If a single \fIoption\fR of the form "\fB-\fIvarName\fR" is specified,
then this method returns the information for that one variable.
.PP
Otherwise, the arguments are treated as \fIoption\fR/\fIvalue\fR
pairs assigning new values to public variables. Each variable
is assigned its new value, and if it has any "config" code associated
with it, it is executed in the context of the extendedclass where it was
defined. If the "config" code generates an error, the variable
is set back to its previous value, and the \fBconfigure\fR method
returns an error.
.RE
.TP
\fIobjName\fR \fBisa \fIextendedclassName\fR
.
Returns non-zero if the given \fIextendedclassName\fR can be found in the
object's heritage, and zero otherwise.
.TP
\fIobjName\fR \fBinfo \fIoption\fR ?\fIargs...\fR?
.
Returns information related to a particular object named
\fIobjName\fR, or to its extendedclass definition. 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 extendedclass\fR
.
Returns the name of the most-specific extendedclass for object \fIobjName\fR.
.TP
\fIobjName\fR \fBinfo inherit\fR
.
Returns the list of base extendedclasses as they were defined in the
"\fBinherit\fR" command, or an empty string if this extendedclass
has no base extendedclasses.
.TP
\fIobjName\fR \fBinfo heritage\fR
.
Returns the current extendedclass name and the entire list of base extendedclasses
in the order that they are traversed for member lookup and object
destruction.
.TP
\fIobjName\fR \fBinfo function\fR ?\fIcmdName\fR? ?\fB-protection\fR? ?\fB-type\fR? ?\fB-name\fR? ?\fB-args\fR? ?\fB-body\fR?
.
With no arguments, this command returns a list of all extendedclass methods
and procs. If \fIcmdName\fR 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.
.TP
\fIobjName\fR \fBinfo variable\fR ?\fIvarName\fR? ?\fB-protection\fR? ?\fB-type\fR? ?\fB-name\fR? ?\fB-init\fR? ?\fB-value\fR? ?\fB-config\fR?
.
With no arguments, this command returns a list of all object-specific
variables and common data members. If \fIvarName\fR is specified, it
returns information for a specific data member. If no flags are
specified, this command returns a list with the following elements: the
protection level, the type (variable/common), the qualified name, the
initial value, and the current value. If \fIvarName\fR is a public
variable, the "config" code is included on this list. Flags can be
used to request specific elements from this list.
.RE
.SH "CHAINING METHODS/PROCS"
.PP
Sometimes a base extendedclass has a method or proc that is redefined with
the same name in a derived extendedclass. This is a way of making the
derived extendedclass handle the same operations as the base extendedclass, but
with its own specialized behavior. For example, suppose we have
a Toaster extendedclass that looks like this:
.PP
.CS
itcl::extendedclass Toaster {
variable crumbs 0
method toast {nslices} {
if {$crumbs > 50} {
error "== FIRE! FIRE! =="
}
set crumbs [expr {$crumbs+4*$nslices}]
}
method clean {} {
set crumbs 0
}
}
.CE
.PP
We might create another extendedclass like SmartToaster that redefines
the "toast" method. If we want to access the base extendedclass method,
we can qualify it with the base extendedclass name, to avoid ambiguity:
.PP
.CS
itcl::extendedclass SmartToaster {
inherit Toaster
method toast {nslices} {
if {$crumbs > 40} {
clean
}
return [Toaster::toast $nslices]
}
}
.CE
.PP
Instead of hard-coding the base extendedclass name, we can use the
"chain" command like this:
.PP
.CS
itcl::extendedclass SmartToaster {
inherit Toaster
method toast {nslices} {
if {$crumbs > 40} {
clean
}
return [chain $nslices]
}
}
.CE
.PP
The chain command searches through the extendedclass hierarchy for
a slightly more generic (base extendedclass) implementation of a method
or proc, and invokes it with the specified arguments. It starts
at the current extendedclass context and searches through base extendedclasses
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.
.SH "AUTO-LOADING"
.PP
Extendedclass definitions need not be loaded explicitly; they can be loaded as
needed by the usual Tcl auto-loading facility. Each directory containing
extendedclass definition files should have an accompanying "tclIndex" file.
Each line in this file identifies a Tcl procedure or \fB[incr\ Tcl]\fR
extendedclass definition and the file where the definition can be found.
.PP
For example, suppose a directory contains the definitions for extendedclasses
"Toaster" and "SmartToaster". Then the "tclIndex" file for this
directory would look like:
.PP
.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"
.CE
.PP
The \fBauto_mkindex\fR command is used to automatically
generate "tclIndex" files.
.PP
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, extendedclasses will be auto-loaded as needed when used in an
application.
.SH "C PROCEDURES"
.PP
C procedures can be integrated into an \fB[incr\ Tcl]\fR extendedclass
definition to implement methods, procs, and the "config" code
for public variables. Any body that starts with "\fB@\fR"
is treated as the symbolic name for a C procedure.
.PP
Symbolic names are established by registering procedures via
\fBItcl_RegisterC()\fR. This is usually done in the \fBTcl_AppInit()\fR
procedure, which is automatically called when the interpreter starts up.
In the following example, the procedure \fCMy_FooCmd()\fR is registered
with the symbolic name "foo". This procedure can be referenced in
the \fBbody\fR command as "\fC@foo\fR".
.PP
.CS
int
Tcl_AppInit(interp)
Tcl_Interp *interp; /* Interpreter for application. */
{
if (Itcl_Init(interp) == TCL_ERROR) {
return TCL_ERROR;
}
if (Itcl_RegisterC(interp, "foo", My_FooCmd) != TCL_OK) {
return TCL_ERROR;
}
}
.CE
.PP
C procedures are implemented just like ordinary Tcl commands.
See the \fBCrtCommand\fR man page for details. Within the procedure,
extendedclass data members can be accessed like ordinary variables
using \fBTcl_SetVar()\fR, \fBTcl_GetVar()\fR, \fBTcl_TraceVar()\fR,
etc. Extendedclass methods and procs can be executed like ordinary commands
using \fBTcl_Eval()\fR. \fB[incr\ Tcl]\fR makes this possible by
automatically setting up the context before executing the C procedure.
.PP
This scheme provides a natural migration path for code development.
Extendedclasses can be developed quickly using Tcl code to implement the
bodies. An entire application can be built and tested. When
necessary, individual bodies can be implemented with C code to
improve performance.
.SH KEYWORDS
extendedclass, object, object-oriented

160
pkgs/itcl4.2.2/doc/itcloption.n Normal file
View File

@@ -0,0 +1,160 @@
'\"
'\" Copyright (c) 2008 Arnulf Wiedemann
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH option n 4.0 itcl "[incr\ Tcl]"
.so man.macros
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
itcl::option \- define options for extendedclass, widget or widgetadaptor
.PP
Parts of this description are "borrowed" from Tcl extension [snit], as the functionality is mostly identical.
.SH WARNING!
This is new functionality in [incr Tcl] where the API can still change!!
.SH SYNOPSIS
.nf
\fBoption \fIoptionSpec\fR ?\fIdefaultValue\fR?
\fBoption \fIoptionSpec\fR ?\fIoptions\fR?
.fi
.BE
.SH DESCRIPTION
.PP
The \fBoption\fR command is used inside an \fB[incr\ Tcl]\fR
extendedclass/widget/widgetadaptor definition to define options.
.PP
In the first form defines an option for instances of this type, and optionally
gives it an initial value. The initial value defaults to the empty string if
no defaultValue is specified.
.PP
An option defined in this way is said to be locally defined.
The optionSpec is a list defining the option's name, resource name, and class
name, e.g.:
.PP
.CS
option {-font font Font} {Courier 12}
.CE
.PP
The option name must begin with a hyphen, and must not contain any upper case
letters. The resource name and class name are optional; if not specified,
the resource name defaults to the option name, minus the hyphen, and the class
name defaults to the resource name with the first letter capitalized. Thus, the
following statement is equivalent to the previous example:
.PP
.CS
option -font {Courier 12}
.CE
.PP
See The Tk Option Database for more information about resource and class names.
.PP
Options are normally set and retrieved using the standard instance methods
configure and cget; within instance code (method bodies, etc.), option values
are available through the options array:
.PP
.CS
set myfont $itcl_options(-font)
.CE
.PP
In the second form you can define option handlers (e.g., -configuremethod),
then it should probably use configure and cget to access its options to avoid
subtle errors.
.PP
The option statement may include the following options:
.TP
\fB-default\fI defvalue\fR
.
Defines the option's default value; the option's default value will be ""
otherwise.
.TP
\fB-readonly\fR
.
The option is handled read-only -- it can only be set using configure at
creation time, i.e., in the type's constructor.
.TP
\fB-cgetmethod\fI methodName\fR
.
Every locally-defined option may define a -cgetmethod; it is called when the
option's value is retrieved using the cget method. Whatever the method's body
returns will be the return value of the call to cget.
.RS
.PP
The named method must take one argument, the option name. For example, this
code is equivalent to (though slower than) Itcl's default handling of cget:
.PP
.CS
option -font -cgetmethod GetOption
method GetOption {option} {
return $itcl_options($option)
}
.CE
.PP
Note that it's possible for any number of options to share a -cgetmethod.
.RE
.TP
\fB-cgetmethodvar\fI varName\fR
.
That is very similar to -cgetmethod, the only difference is, one can define
a variable, where to find the cgetmethod during runtime.
.TP
\fB-configuremethod\fI methodName\fR
.
Every locally-defined option may define a -configuremethod; it is called
when the option's value is set using the configure or configurelist
methods. It is the named method's responsibility to save the option's
value; in other words, the value will not be saved to the itcl_options()
array unless the method saves it there.
.RS
.PP
The named method must take two arguments, the option name and its new value.
For example, this code is equivalent to (though slower than) Itcl's default
handling of configure:
.PP
.CS
option -font -configuremethod SetOption
method SetOption {option value} {
set itcl_options($option) $value
}
.CE
.PP
Note that it's possible for any number of options to share a single -configuremethod.
.RE
.TP
\fB-configuremethodvar\fI varName\fR
.
That is very similar to -configuremethod, the only difference is, one can define
a variable, where to find the configuremethod during runtime.
.TP
\fB-validatemethod\fI methodName\fR
.
Every locally-defined option may define a -validatemethod; it is called when
the option's value is set using the configure or configurelist methods, just
before the -configuremethod (if any). It is the named method's responsibility
to validate the option's new value, and to throw an error if the value is
invalid.
.RS
.PP
The named method must take two arguments, the option name and its new value.
For example, this code verifies that -flag's value is a valid Boolean value:
.PP
.CS
option -font -validatemethod CheckBoolean
method CheckBoolean {option value} {
if {![string is boolean -strict $value]} {
error "option $option must have a boolean value."
}
}
.CE
.PP
Note that it's possible for any number of options to share a single -validatemethod.
.RE
.TP
\fB-validatemethodvar\fI varName\fR
.
That is very similar to -validatemethod, the only difference is, one can define
a variable, where to find the validatemethod during runtime.
.SH KEYWORDS
option, widget, widgetadaptor, extendedclass

106
pkgs/itcl4.2.2/doc/itclvars.n Normal file
View File

@@ -0,0 +1,106 @@
'\"
'\" 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.
'\"
.TH itclvars n 3.0 itcl "[incr\ Tcl]"
.so man.macros
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
itclvars \- variables used by [incr\ Tcl]
.BE
.SH DESCRIPTION
.PP
The following global variables are created and managed automatically
by the \fB[incr\ Tcl]\fR library. Except where noted below, these
variables should normally be treated as read-only by application-specific
code and by users.
.TP
\fBitcl::library\fR
.
When an interpreter is created, \fB[incr\ Tcl]\fR initializes this variable
to hold the name of a directory containing the system library of
\fB[incr\ Tcl]\fR scripts. The initial value of \fBitcl::library\fR
is set from the ITCL_LIBRARY environment variable if it exists,
or from a compiled-in value otherwise.
.TP
\fBitcl::patchLevel\fR
.
When an interpreter is created, \fB[incr\ Tcl]\fR initializes this
variable to hold the current patch level for \fB[incr\ Tcl]\fR.
For example, the value "\fB2.0p1\fR" indicates \fB[incr\ Tcl]\fR
version 2.0 with the first set of patches applied.
.TP
\fBitcl::purist\fR
.
When an interpreter is created containing Tcl/Tk and the
\fB[incr\ Tcl]\fR namespace facility, this variable controls
a "backward-compatibility" mode for widget access.
.RS
.PP
In vanilla Tcl/Tk, there is a single pool of commands, so the
access command for a widget is the same as the window name.
When a widget is created within a namespace, however, its access
command is installed in that namespace, and should be accessed
outside of the namespace using a qualified name. For example,
.PP
.CS
namespace foo {
namespace bar {
button .b -text "Testing"
}
}
foo::bar::.b configure -background red
pack .b
.CE
.PP
Note that the window name "\fC.b\fR" is still used in conjunction
with commands like \fBpack\fR and \fBdestroy\fR. However, the
access command for the widget (i.e., name that appears as the
\fIfirst\fR argument on a command line) must be more specific.
.PP
The "\fBwinfo command\fR" command can be used to query the
fully-qualified access command for any widget, so one can write:
.PP
.CS
[winfo command .b] configure -background red
.CE
.PP
and this is good practice when writing library procedures. Also,
in conjunction with the \fBbind\fR command, the "%q" field can be
used in place of "%W" as the access command:
.PP
.CS
bind Button <Key-Return> {%q flash; %q invoke}
.CE
.PP
While this behavior makes sense from the standpoint of encapsulation,
it causes problems with existing Tcl/Tk applications. Many existing
applications are written with bindings that use "%W". Many
library procedures assume that the window name is the access
command.
.PP
The \fBitcl::purist\fR variable controls a backward-compatibility
mode. By default, this variable is "0", and the window name
can be used as an access command in any context. Whenever the
\fBunknown\fR procedure stumbles across a widget name, it simply
uses "\fBwinfo command\fR" to determine the appropriate command
name. If this variable is set to "1", this backward-compatibility
mode is disabled. This gives better encapsulation, but using the
window name as the access command may lead to "invalid command"
errors.
.RE
.TP
\fBitcl::version\fR
.
When an interpreter is created, \fB[incr\ Tcl]\fR initializes this
variable to hold the version number of the form \fIx.y\fR.
Changes to \fIx\fR represent major changes with probable
incompatibilities and changes to \fIy\fR represent small enhancements
and bug fixes that retain backward compatibility.
.SH KEYWORDS
itcl, variables

549
pkgs/itcl4.2.2/doc/itclwidget.n Normal file
View File

@@ -0,0 +1,549 @@
'\"
'\" Copyright (c) 2008 Arnulf Wiedemann
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH widget n "4.0" itcl "[incr\ Tcl]"
.so man.macros
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
itcl::widget \- create a widget class of objects
.SH WARNING!
This is new functionality in [incr Tcl] where the API can still change!!
.SH SYNOPSIS
.nf
\fBitcl::widget \fIwidgetName\fR \fB{\fR
\fBinherit \fIbaseWidget\fR ?\fIbaseWidget\fR...?
\fBconstructor \fIargs\fR ?\fIinit\fR? \fIbody\fR
\fBdestructor \fIbody\fR
\fBpublic method \fIname\fR ?\fIargs\fR? ?\fIbody\fR?
\fBprotected method \fIname\fR ?\fIargs\fR? ?\fIbody\fR?
\fBprivate method \fIname\fR ?\fIargs\fR? ?\fIbody\fR?
\fBpublic proc \fIname\fR ?\fIargs\fR? ?\fIbody\fR?
\fBprotected proc \fIname\fR ?\fIargs\fR? ?\fIbody\fR?
\fBprivate proc \fIname\fR ?\fIargs\fR? ?\fIbody\fR?
\fBpublic variable \fIvarName\fR ?\fIinit\fR? ?\fIconfig\fR?
\fBprotected variable \fIvarName\fR ?\fIinit\fR? ?\fIconfig\fR?
\fBprivate variable \fIvarName\fR ?\fIinit\fR? ?\fIconfig\fR?
\fBpublic common \fIvarName\fR ?\fIinit\fR?
\fBprotected common \fIvarName\fR ?\fIinit\fR?
\fBprivate common \fIvarName\fR ?\fIinit\fR?
\fBpublic \fIcommand\fR ?\fIarg arg ...\fR?
\fBprotected \fIcommand\fR ?\fIarg arg ...\fR?
\fBprivate \fIcommand\fR ?\fIarg arg ...\fR?
\fB<delegation info>\fR see delegation page
\fB<option info>\fR see option page
\fBset \fIvarName\fR ?\fIvalue\fR?
\fBarray \fIoption\fR ?\fIarg arg ...\fR?
\fB}\fR
\fIwidgetName objName\fR ?\fIarg arg ...\fR?
\fIobjName method\fR ?\fIarg arg ...\fR?
\fIwidgetName::proc\fR ?\fIarg arg ...\fR?
.fi
.BE
.SH DESCRIPTION
.PP
One of the fundamental constructs in \fB[incr\ Tcl]\fR is the widget definition.
A widget is like a class with some additional features.
Each widget acts as a template for actual objects that can be created.
The widget itself is a namespace which contains things common to all
objects. Each object has its own unique bundle of data which contains
instances of the "variables" defined in the widget definition. Each
object also has a built-in variable named "this", which contains the
name of the object. Widgets can also have "common" data members that
are shared by all objects in a widget.
.PP
Two types of functions can be included in the widget definition.
"Methods" are functions which operate on a specific object, and
therefore have access to both "variables" and "common" data members.
"Procs" are ordinary procedures in the widget namespace, and only
have access to "common" data members.
.PP
If the body of any method or proc starts with "\fB@\fR", it is treated
as the symbolic name for a C procedure. Otherwise, it is treated as
a Tcl code script. See below for details on registering and using
C procedures.
.PP
A widget can only be defined once, although the bodies of widget
methods and procs can be defined again and again for interactive
debugging. See the \fBbody\fR and \fBconfigbody\fR commands for
details.
.PP
Each namespace can have its own collection of objects and widgets.
The list of widgets available in the current context can be queried
using the "\fBitcl::find widgets\fR" command, and the list of objects,
with the "\fBitcl::find objects\fR" command.
.PP
A widget can be deleted using the "\fBdelete widget\fR" command.
Individual objects can be deleted using the "\fBdelete object\fR"
command.
.SH "WIDGET DEFINITIONS"
.TP
\fBwidget \fIwidgetName definition\fR
.
Provides the definition for a widget named \fIwidgetName\fR. If
the widget \fIwidgetName\fR already exists, or if a command called
\fIwidgetName\fR exists in the current namespace context, this
command returns an error. If the widget definition is successfully
parsed, \fIwidgetName\fR becomes a command in the current context,
handling the creation of objects for this widget.
.PP
The widget \fIdefinition\fR is evaluated as a series of Tcl
statements that define elements within the widget. The following
widget definition commands are recognized:
.RS
.TP
\fBinherit \fIbaseWidget\fR ?\fIbaseWidget\fR...?
.
Causes the current widget to inherit characteristics from one or
more base widgets. Widgets must have been defined by a previous
\fBwidget\fR command, or must be available to the auto-loading
facility (see "AUTO-LOADING" below). A single widget definition
can contain no more than one \fBinherit\fR command.
.RS
.PP
The order of \fIbaseWidget\fR names in the \fBinherit\fR list
affects the name resolution for widget members. When the same
member name appears in two or more base widgets, the base widget
that appears first in the \fBinherit\fR list takes precedence.
For example, if widgets "Foo" and "Bar" both contain the member
"x", and if another widget has the "\fBinherit\fR" statement:
.PP
.CS
inherit Foo Bar
.CE
.PP
then the name "x" means "Foo::x". Other inherited members named
"x" must be referenced with their explicit name, like "Bar::x".
.RE
.TP
\fBconstructor \fIargs\fR ?\fIinit\fR? \fIbody\fR
.
Declares the \fIargs\fR argument list and \fIbody\fR used for
the constructor, which is automatically invoked whenever an
object is created.
.RS
.PP
Before the \fIbody\fR is executed, the
optional \fIinit\fR statement is used to invoke any base widget
constructors that require arguments. Variables in the \fIargs\fR
specification can be accessed in the \fIinit\fR code fragment,
and passed to base widget constructors. After evaluating the
\fIinit\fR statement, any base widget constructors that have
not been executed are invoked automatically without arguments.
This ensures that all base widgets are fully constructed before
the constructor \fIbody\fR is executed. By default, this
scheme causes constructors to be invoked in order from least-
to most-specific. This is exactly the opposite of the order
that widgets are reported by the \fBinfo heritage\fR command.
.PP
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.
.RE
.TP
\fBdestructor \fIbody\fR
.
Declares the \fIbody\fR used for the destructor, which is automatically
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.
.RS
.PP
When an object is destroyed, all destructors in its widget hierarchy
are invoked in order from most- to least-specific. This is the
order that the widgets are reported by the "\fBinfo heritage\fR"
command, and it is exactly the opposite of the default constructor
order.
.RE
.TP
\fBmethod \fIname\fR ?\fIargs\fR? ?\fIbody\fR?
.
Declares a method called \fIname\fR. When the method \fIbody\fR is
executed, it will have automatic access to object-specific variables
and common data members.
.RS
.PP
If the \fIargs\fR list is specified, it establishes the usage
information for this method. The \fBbody\fR command can be used
to redefine the method body, but the \fIargs\fR list must match
this specification.
.PP
Within the body of another widget method, a method can be invoked
like any other command\-simply by using its name. Outside of the
widget context, the method name must be prefaced an object name,
which provides the context for the data that it manipulates.
Methods in a base widget that are redefined in the current widget,
or hidden by another base widget, can be qualified using the
"\fIwidgetName\fR::\fImethod\fR" syntax.
.RE
.TP
\fBproc \fIname\fR ?\fIargs\fR? ?\fIbody\fR?
.
Declares a proc called \fIname\fR. A proc is an ordinary procedure
within the widget namespace. Unlike a method, a proc is invoked
without referring to a specific object. When the proc \fIbody\fR is
executed, it will have automatic access only to common data members.
.RS
.PP
If the \fIargs\fR list is specified, it establishes the usage
information for this proc. The \fBbody\fR command can be used
to redefine the proc body, but the \fIargs\fR list must match
this specification.
.PP
Within the body of another widget method or proc, 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 "\fIwidgetName\fB::\fIproc\fR". Procs in
a base widget that are redefined in the current widget, or hidden
by another base widget, can also be accessed via their qualified
name.
.RE
.TP
\fBvariable \fIvarName\fR ?\fIinit\fR? ?\fIconfig\fR?
.
Defines an object-specific variable named \fIvarName\fR. All
object-specific variables are automatically available in widget
methods. They need not be declared with anything like the
\fBglobal\fR command.
.RS
.PP
If the optional \fIinit\fR string 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 set
within the constructor and used as arrays.
.PP
The optional \fIconfig\fR script is only allowed for public variables.
If specified, this code fragment is executed whenever a public
variable is modified by the built-in "configure" method. The
\fIconfig\fR script can also be specified outside of the widget
definition using the \fBconfigbody\fR command.
.RE
.TP
\fBcommon \fIvarName\fR ?\fIinit\fR?
.
Declares a common variable named \fIvarName\fR. Common variables
reside in the widget namespace and are shared by all objects belonging
to the widget. They are just like global variables, except that
they need not be declared with the usual \fBglobal\fR command.
They are automatically visible in all widget methods and procs.
.RS
.PP
If the optional \fIinit\fR 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 \fBset\fR and \fBarray\fR commands
and used as arrays.
.PP
Once a common data member has been defined, it can be set using
\fBset\fR and \fBarray\fR commands within the widget definition.
This allows common data members to be initialized as arrays.
For example:
.PP
.CS
itcl::widget Foo {
protected common boolean
set boolean(true) 1
set boolean(false) 0
}
.CE
.PP
Note that if common data members are initialized within the
constructor, they get initialized again and again whenever new
objects are created.
.RE
.TP
\fBpublic \fIcommand\fR ?\fIarg arg ...\fR?
.TP
\fBprotected \fIcommand\fR ?\fIarg arg ...\fR?
.TP
\fBprivate \fIcommand\fR ?\fIarg arg ...\fR?
.
These commands are used to set the protection level for widget
members that are created when \fIcommand\fR is evaluated.
The \fIcommand\fR is usually \fBmethod\fR, \fBproc\fR,
\fBvariable\fR or\fBcommon\fR, and the remaining \fIarg\fR's
complete the member definition. However, \fIcommand\fR can
also be a script containing many different member definitions,
and the protection level will apply to all of the members
that are created.
.RE
.SH "WIDGET USAGE"
.PP
Once a widget has been defined, the widget name can be used as a
command to create new objects belonging to the widget.
.TP
\fIwidgetName objName\fR ?\fIargs...\fR?
.
Creates a new object in widget \fIwidgetName\fR with the name \fIobjName\fR.
Remaining arguments are passed to the constructor of the most-specific
widget. This in turn passes arguments to base widget constructors before
invoking its own body of commands. If construction is successful, a
command called \fIobjName\fR is created in the current namespace context,
and \fIobjName\fR 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.
.RS
.PP
If \fIobjName\fR contains the string "\fB#auto\fR", that string is
replaced with an automatically generated name. Names have the
form \fIwidgetName<number>\fR, where the \fIwidgetName\fR part is
modified to start with a lowercase letter. In widget "Toaster",
for example, the "\fB#auto\fR" specification would produce names
like toaster0, toaster1, etc. Note that "\fB#auto\fR" can be
also be buried within an object name:
.PP
.CS
fileselectiondialog .foo.bar.#auto -background red
.CE
.PP
This would generate an object named ".foo.bar.fileselectiondialog0".
.RE
.SH "OBJECT USAGE"
.PP
Once an object has been created, the object name can be used
as a command to invoke methods that operate on the object.
.TP
\fIobjName method\fR ?\fIargs...\fR?
.
Invokes a method named \fImethod\fR on an object named \fIobjName\fR.
Remaining arguments are passed to the argument list for the
method. The method name can be "constructor", "destructor",
any method name appearing in the widget definition, or any of
the following built-in methods.
.SH "BUILT-IN METHODS"
.TP
\fIobjName\fR \fBcget option\fR
.
Provides access to public variables as configuration options. This
mimics the behavior of the usual "cget" operation for Tk widgets.
The \fIoption\fR argument is a string of the form "\fB-\fIvarName\fR",
and this method returns the current value of the public variable
\fIvarName\fR.
.TP
\fIobjName\fR \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
.
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.
.RS
.PP
If a single \fIoption\fR of the form "\fB-\fIvarName\fR" is specified,
then this method returns the information for that one variable.
.PP
Otherwise, the arguments are treated as \fIoption\fR/\fIvalue\fR
pairs assigning new values to public variables. Each variable
is assigned its new value, and if it has any "config" code associated
with it, it is executed in the context of the widget where it was
defined. If the "config" code generates an error, the variable
is set back to its previous value, and the \fBconfigure\fR method
returns an error.
.RE
.TP
\fIobjName\fR \fBisa \fIwidgetName\fR
.
Returns non-zero if the given \fIwidgetName\fR can be found in the
object's heritage, and zero otherwise.
.TP
\fIobjName\fR \fBinfo \fIoption\fR ?\fIargs...\fR?
.
Returns information related to a particular object named
\fIobjName\fR, or to its widget definition. 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 widget\fR
.
Returns the name of the most-specific widget for object \fIobjName\fR.
.TP
\fIobjName\fR \fBinfo inherit\fR
.
Returns the list of base widgets as they were defined in the
"\fBinherit\fR" command, or an empty string if this widget
has no base widgets.
.TP
\fIobjName\fR \fBinfo heritage\fR
.
Returns the current widget name and the entire list of base widgets
in the order that they are traversed for member lookup and object
destruction.
.TP
\fIobjName\fR \fBinfo function\fR ?\fIcmdName\fR? ?\fB-protection\fR? ?\fB-type\fR? ?\fB-name\fR? ?\fB-args\fR? ?\fB-body\fR?
.
With no arguments, this command returns a list of all widgets methods
and procs. If \fIcmdName\fR 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.
.TP
\fIobjName\fR \fBinfo variable\fR ?\fIvarName\fR? ?\fB-protection\fR? ?\fB-type\fR? ?\fB-name\fR? ?\fB-init\fR? ?\fB-value\fR? ?\fB-config\fR?
.
With no arguments, this command returns a list of all object-specific
variables and common data members. If \fIvarName\fR is specified, it
returns information for a specific data member. If no flags are
specified, this command returns a list with the following elements: the
protection level, the type (variable/common), the qualified name, the
initial value, and the current value. If \fIvarName\fR is a public
variable, the "config" code is included on this list. Flags can be
used to request specific elements from this list.
.RE
.SH "CHAINING METHODS/PROCS"
.PP
Sometimes a base widget has a method or proc that is redefined with
the same name in a derived widget. This is a way of making the
derived widget handle the same operations as the base widget, but
with its own specialized behavior. For example, suppose we have
a Toaster widget that looks like this:
.PP
.CS
itcl::widget Toaster {
variable crumbs 0
method toast {nslices} {
if {$crumbs > 50} {
error "== FIRE! FIRE! =="
}
set crumbs [expr {$crumbs+4*$nslices}]
}
method clean {} {
set crumbs 0
}
}
.CE
.PP
We might create another widget like SmartToaster that redefines
the "toast" method. If we want to access the base widget method,
we can qualify it with the base widget name, to avoid ambiguity:
.PP
.CS
itcl::widget SmartToaster {
inherit Toaster
method toast {nslices} {
if {$crumbs > 40} {
clean
}
return [Toaster::toast $nslices]
}
}
.CE
.PP
Instead of hard-coding the base widget name, we can use the
"chain" command like this:
.PP
.CS
itcl::widget SmartToaster {
inherit Toaster
method toast {nslices} {
if {$crumbs > 40} {
clean
}
return [chain $nslices]
}
}
.CE
.PP
The chain command searches through the widget hierarchy for
a slightly more generic (base widget) implementation of a method
or proc, and invokes it with the specified arguments. It starts
at the current widget context and searches through base widgets
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.
.SH AUTO-LOADING
.PP
Widget definitions need not be loaded explicitly; they can be loaded as
needed by the usual Tcl auto-loading facility. Each directory containing
widget definition files should have an accompanying "tclIndex" file.
Each line in this file identifies a Tcl procedure or \fB[incr\ Tcl]\fR
widget definition and the file where the definition can be found.
.PP
For example, suppose a directory contains the definitions for widgets
"Toaster" and "SmartToaster". Then the "tclIndex" file for this
directory would look like:
.PP
.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"
.CE
.PP
The \fBauto_mkindex\fR command is used to automatically
generate "tclIndex" files.
.PP
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, widgets will be auto-loaded as needed when used in an
application.
.SH C PROCEDURES
.PP
C procedures can be integrated into an \fB[incr\ Tcl]\fR widget
definition to implement methods, procs, and the "config" code
for public variables. Any body that starts with "\fB@\fR"
is treated as the symbolic name for a C procedure.
.PP
Symbolic names are established by registering procedures via
\fBItcl_RegisterC()\fR. This is usually done in the \fBTcl_AppInit()\fR
procedure, which is automatically called when the interpreter starts up.
In the following example, the procedure \fCMy_FooCmd()\fR is registered
with the symbolic name "foo". This procedure can be referenced in
the \fBbody\fR command as "\fC@foo\fR".
.PP
.CS
int
Tcl_AppInit(interp)
Tcl_Interp *interp; /* Interpreter for application. */
{
if (Itcl_Init(interp) == TCL_ERROR) {
return TCL_ERROR;
}
if (Itcl_RegisterC(interp, "foo", My_FooCmd) != TCL_OK) {
return TCL_ERROR;
}
}
.CE
.PP
C procedures are implemented just like ordinary Tcl commands.
See the \fBCrtCommand\fR man page for details. Within the procedure,
widget data members can be accessed like ordinary variables
using \fBTcl_SetVar()\fR, \fBTcl_GetVar()\fR, \fBTcl_TraceVar()\fR,
etc. Widget methods and procs can be executed like ordinary commands
using \fBTcl_Eval()\fR. \fB[incr\ Tcl]\fR makes this possible by
automatically setting up the context before executing the C procedure.
.PP
This scheme provides a natural migration path for code development.
Widgets can be developed quickly using Tcl code to implement the
bodies. An entire application can be built and tested. When
necessary, individual bodies can be implemented with C code to
improve performance.
.SH KEYWORDS
widget, object, object-oriented

27
pkgs/itcl4.2.2/doc/license.terms Normal file
View File

@@ -0,0 +1,27 @@
------------------------------------------------------------------------
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> [incr Tcl] <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
AUTHOR: Michael J. McLennan
Bell Labs Innovations for Lucent Technologies
mmclennan@lucent.com
http://www.tcltk.com/itcl
========================================================================
Copyright (c) 1993-1996 Lucent Technologies
========================================================================
Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted,
provided that the above copyright notice appear in all copies and that
both that the copyright notice and warranty disclaimer appear in
supporting documentation, and that the names of Lucent Technologies
any of their entities not be used in advertising or publicity
pertaining to distribution of the software without specific, written
prior permission.
Lucent Technologies disclaims all warranties with regard to this
software, including all implied warranties of merchantability and
fitness. In no event shall Lucent be liable for any special, indirect
or consequential damages or any damages whatsoever resulting from loss
of use, data or profits, whether in an action of contract, negligence
or other tortuous action, arising out of or in connection with the use
or performance of this software.
========================================================================

75
pkgs/itcl4.2.2/doc/local.n Normal file
View File

@@ -0,0 +1,75 @@
'\"
'\" 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.
'\"
.TH local n "" itcl "[incr\ Tcl]"
.so man.macros
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
itcl::local \- create an object local to a procedure
.SH SYNOPSIS
\fBitcl::local \fIclassName objName\fR ?\fIarg arg ...\fR?
.BE
.SH DESCRIPTION
.PP
The \fBlocal\fR command creates an \fB[incr\ Tcl]\fR object that
is local to the current call frame. When the call frame goes away,
the object is automatically deleted. This command is useful for
creating objects that are local to a procedure.
.PP
As a side effect, this command creates a variable named
"\fBitcl-local-\fIxxx\fR", where \fIxxx\fR is the name of
the object that is created. This variable detects when the
call frame is destroyed and automatically deletes the
associated object.
.SH EXAMPLE
.PP
In the following example, a simple "counter" object is used
within the procedure "test". The counter is created as a
local object, so it is automatically deleted each time the
procedure exits. The \fBputs\fR statements included in the
constructor/destructor show the object coming and going
as the procedure is called.
.PP
.CS
itcl::class counter {
private variable count 0
constructor {} {
puts "created: $this"
}
destructor {
puts "deleted: $this"
}
method bump {{by 1}} {
incr count $by
}
method get {} {
return $count
}
}
proc test {val} {
local counter x
for {set i 0} {$i < $val} {incr i} {
x bump
}
return [x get]
}
set result [test 5]
puts "test: $result"
set result [test 10]
puts "test: $result"
puts "objects: [itcl::find objects *]"
.CE
.SH KEYWORDS
class, object, procedure

267
pkgs/itcl4.2.2/doc/man.macros Normal file
View File

@@ -0,0 +1,267 @@
.\" The -*- nroff -*- 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 ?manpage?
.\" Start of list of standard options for a Tk widget. The manpage
.\" argument defines where to look up the standard options; if
.\" omitted, defaults to "options". The options follow on successive
.\" lines, in three 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.
.\"
.\" .QW arg1 ?arg2?
.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
.\"
.\" .PQ arg1 ?arg2?
.\" Print an open parenthesis, arg1 in quotes, then arg2 normally
.\" (for trailing punctuation) and then a closing parenthesis.
.\"
.\" # 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
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$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
'ie '\\$1'' .ds So \\fBoptions\\fR
'el .ds So \\fB\\$1\\fR
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
.\" # SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\*(So 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
..
.\" # UL - underline word
.de UL
\\$1\l'|0\(ul'\\$2
..
.\" # QW - apply quotation marks to word
.de QW
.ie '\\*(lq'"' ``\\$1''\\$2
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\$2
..
.\" # PQ - apply parens and quotation marks to word
.de PQ
.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
.\"" fix emacs highlighting
.el (\\*(lq\\$1\\*(rq\\$2)\\$3
..
.\" # QR - quoted range
.de QR
.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
..
.\" # MT - "empty" string
.de MT
.QW ""
..

69
pkgs/itcl4.2.2/doc/scope.n Normal file
View File

@@ -0,0 +1,69 @@
'\"
'\" 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.
'\"
.TH scope n "" itcl "[incr\ Tcl]"
.so man.macros
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
itcl::scope \- capture the namespace context for a variable
.SH SYNOPSIS
\fBitcl::scope \fIname\fR
.BE
.SH DESCRIPTION
.PP
Creates a scoped value for the specified \fIname\fR, which must
be a variable name. If the \fIname\fR is an instance variable,
then the scope command returns a name which will resolve in any
context as an instance variable belonging to \fIobject\fR.
The precise format of this name is an internal detail to Itcl.
Use of such a scoped value makes it possible to use
instance variables in conjunction with widgets. For example, if you
have an object with a private variable \fCx\fR, and you can use
\fCx\fR in conjunction with the \fC-textvariable\fR option of an
entry widget. Before itcl3.0, only common variables could be used
in this manner.
.PP
If the \fIname\fR is not an instance variable, then it must be
a common variable or a global variable. In that case, the scope
command returns the fully qualified name of the variable, e.g.,
\fC::foo::bar::x\fR.
.PP
If the \fIname\fR is not recognized as a variable, the scope
command returns an error.
.PP
Ordinary variable names refer to variables in the global namespace.
A scoped value captures a variable name together with its namespace
context in a way that allows it to be referenced properly later.
It is needed, for example, to wrap up variable names when a Tk
widget is used within a namespace:
.CS
namespace foo {
private variable mode 1
radiobutton .rb1 -text "Mode #1" \
-variable [scope mode] -value 1
pack .rb1
radiobutton .rb2 -text "Mode #2" \
-variable [scope mode] -value 2
pack .rb2
}
.CE
Radiobuttons \fC.rb1\fR and \fC.rb2\fR interact via the variable
"mode" contained in the namespace "foo". The \fBscope\fR command
guarantees this by returning the fully qualified variable name
\fC::foo::mode\fR.
.PP
You should never attempt to craft your own scoped variable names,
even if you believe you've flawlessly reverse-engineered the encoding.
Instead, you should always use the scope command to generate the
variable name dynamically. Then, you can pass that name to a widget
or to any other bit of code in your program.
.SH KEYWORDS
code, namespace, variable