Subversion Repositories or1k

/configbody.n

configbody.n Property changes : Added: svn:executable ## -0,0 +1 ## +* \ No newline at end of property Index: itclvars.n =================================================================== --- itclvars.n (nonexistent) +++ itclvars.n (revision 1765) @@ -0,0 +1,96 @@ +'\" +'\" Copyright (c) 1993-1998 Lucent Technologies, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: $Id: itclvars.n,v 1.1.1.1 2002-01-16 10:24:46 markom Exp $ +'\" +.so man.macros +.TH itclvars n 3.0 itcl "[incr\ Tcl]" +.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. +.sp +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, +.CS +namespace foo { + namespace bar { + button .b -text "Testing" + } +} +foo::bar::.b configure -background red +pack .b +.CE +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. +.sp +The "\fBwinfo command\fR" command can be used to query the +fully-qualified access command for any widget, so one can write: +.CS +[winfo command .b] configure -background red +.CE +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: +.CS +bind Button {%q flash; %q invoke} +.CE +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. +.sp +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. +.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

itclvars.n Property changes : Added: svn:executable ## -0,0 +1 ## +* \ No newline at end of property Index: itclsh.1 =================================================================== --- itclsh.1 (nonexistent) +++ itclsh.1 (revision 1765) @@ -0,0 +1,30 @@ +'\" +'\" Copyright (c) 1996 Lucent Technologies +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" $Id: itclsh.1,v 1.1.1.1 2002-01-16 10:24:46 markom Exp $ +'\" +.so man.macros +.TH itclsh 1 "" itcl "[incr\ Tcl]" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +itclsh \- Simple shell for [incr Tcl] +.SH SYNOPSIS +\fBitclsh\fR ?\fIfileName arg arg ...\fR? +.BE + +.SH DESCRIPTION +.PP +\fBitclsh\fR is a shell-like application that reads Tcl commands +from its standard input, or from a file, and evaluates them. +It is just like \fBtclsh\fR, but includes the \fB[incr\ Tcl]\fR +extensions for object-oriented programming. +.PP +See the \fBtclsh\fR man page for details concerning usage. See +the \fBitcl\fR man page for an overview of \fB[incr\ Tcl]\fR. + +.SH KEYWORDS +Tcl, itcl, interpreter, script file, shell

itclsh.1 Property changes : Added: svn:executable ## -0,0 +1 ## +* \ No newline at end of property Index: Resolvers.3 =================================================================== --- Resolvers.3 (nonexistent) +++ Resolvers.3 (revision 1765) @@ -0,0 +1,222 @@ +'\" +'\" Copyright (c) 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. +'\" +'\" SCCS: %W% +'\" +.so man.macros +.TH Tcl_AddInterpResolvers 3 8.0 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_AddInterpResolvers, Tcl_GetInterpResolvers, Tcl_RemoveInterpResolvers, Tcl_SetNamespaceResolvers, Tcl_GetNamespaceResolvers \- change the name resolution rules for commands/variables +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +void +\fBTcl_AddInterpResolvers\fR(\fIinterp, name, cmdProc, varProc, compiledVarProc\fR) +.sp +int +\fBTcl_GetInterpResolvers\fR(\fIinterp, name, resInfoPtr\fR) +.sp +int +\fBTcl_RemoveInterpResolvers\fR(\fIinterp, name\fR) +.sp +void +\fBTcl_SetNamespaceResolvers\fR(\fInamespacePtr, cmdProc, varProc, compiledVarProc\fR) +.sp +int +\fBTcl_GetNamespaceResolvers\fR(\fInamespacePtr, resInfoPtr\fR) +.SH ARGUMENTS +.AS Tcl_ResolveCompiledVarProc *compiledVarProc +.AP Tcl_Interp *interp in +Interpreter whose name resolution rules are being queried or modified. +.AP char *name in +Name for a group of name resolution procedures. +.AP Tcl_ResolveCmdProc *cmdProc in +Procedure which will be used to resolve command names. +.AP Tcl_ResolveVarProc *varProc in +Procedure which will be used to resolve variable names at run time. +.AP Tcl_ResolveCompiledVarProc *compiledVarProc in +Procedure which will be used to resolve variable names at compile time. +.AP Tcl_ResolverInfo *resInfoPtr out +Returns the resolution procedures that are currently in effect for +a particular namespace or for a particular name resolution scheme +in the interpreter. +.AP Tcl_Namespace *namespacePtr in +Namespace whose name resolution rules are being queried or modified. +.BE + +.SH DESCRIPTION +.PP +These procedures make it possible to change the way that Tcl +resolves command/variable names. The name resolution rules are +changed by supplying three procedures: \fIcmdProc\fR, \fIvarProc\fR, and +\fIcompiledVarProc\fR. See the section \fBHOW NAME RESOLUTION PROCEDURES +WORK\fR for details about these procedures. +.PP +The name resolution rules can be changed for a particular namespace, +for an entire interpreter, or both. When a name needs to be resolved, +Tcl handles it as follows. The name resolution scheme for the +current namespace is consulted first. Each of the name resolution +schemes for the interpreter are consulted next. Finally, Tcl uses +the default rules for name resolution as described for the +\fBnamespace\fR command. +.PP +\fBTcl_AddInterpResolver\fR adds a set of name resolution procedures +to an interpreter. The procedures are identified by a string \fIname\fR, +so they can be queried or deleted later on. All of the name resolution +schemes for the interpreter are kept on a list, and they are consulted +in order from most- to least-recently added. For example, suppose one +extension adds a name resolution scheme called "fred", and another +extension adds another scheme called "barney". When a name is resolved, +the "barney" scheme will be consulted first, followed by the "fred" +scheme, if necessary. +.PP +\fBTcl_GetInterpResolver\fR looks for a particular name resolution +scheme in an interpreter. If the \fIname\fR is recognized, this +procedure returns a non-zero value along with pointers to the +name resolution procedures in the \fIresInfoPtr\fR structure. Otherwise, +the procedure returns 0. +.PP +\fBTcl_RemoveInterpResolver\fR looks for a particular name resolution +scheme in an interpreter. If the \fIname\fR is recognized, this +procedure deletes the scheme and returns a non-zero value. Otherwise, +it returns 0. +.PP +\fBTcl_SetNamespaceResolver\fR sets the name resolution procedures +for a particular namespace. Unlike an interpreter, a namespace can +have only one name resolution scheme in effect at any given time. +.PP +\fBTcl_GetNamespaceResolver\fR returns the name resolution procedures +for a particular namespace. If the namespace has a special name +resolution scheme, this procedure returns a non-zero value along +with pointers to the name resolution procedures in the \fIresInfoPtr\fR +structure. Otherwise, the procedure returns 0. +.SH "HOW NAME RESOLUTION PROCEDURES WORK" +A name resolution scheme is enforced by three name resolution procedures. +The \fIcmdProc\fR procedure is used to resolve command names. It must +conform to the following type: +.CS +typedef int Tcl_ResolveCmdProc(Tcl_Interp* \fIinterp\fR, + char* \fIname\fR, Tcl_Namespace* \fIcontext\fR, int \fIflags\fR, + Tcl_Command* \fIrPtr\fR); +.CE +The \fIinterp\fR argument is the interpreter performing the resolution; +\fIname\fR is the command name being resolved; \fIcontext\fR is the +namespace context containing the command reference; and \fIflags\fR +may contain TCL_LEAVE_ERR_MSG. +.PP +If this procedure recognizes the command \fIname\fR, it should +store the Tcl_Command token for that command in the \fIrPtr\fR +argument and return TCL_OK. If this procedure doesn't recognize +the command \fIname\fR, it should return TCL_CONTINUE, and the +name resolution will continue with another procedure or with the +default Tcl resolution scheme. If this procedure recognizes +the command \fIname\fR, but for some reason the command is +invalid, the procedure should return TCL_ERROR. If the \fIflags\fR +argument contains TCL_LEAVE_ERR_MSG, the procedure should leave +an error message in the interpreter, explaining why the command +is invalid. +.PP +The \fIvarProc\fR procedure is similar to \fIcmdProc\fR, but it is +used to resolve variable names encountered at run time. It must +conform to the following type: +.CS +typedef int Tcl_ResolveVarProc(Tcl_Interp* \fIinterp\fR, + char* \fIname\fR, Tcl_Namespace* \fIcontext\fR, int \fIflags\fR, + Tcl_Var* \fIrPtr\fR); +.CE +The \fIinterp\fR argument is the interpreter performing the resolution; +\fIname\fR is the variable name being resolved; \fIcontext\fR is the +namespace context containing the variable reference; and \fIflags\fR +may contain TCL_GLOBAL_ONLY, TCL_NAMESPACE_ONLY, or TCL_LEAVE_ERR_MSG. +.PP +If this procedure recognizes the variable \fIname\fR, it should +store the Tcl_Var token for that variable in the \fIrPtr\fR +argument and return TCL_OK. If this procedure doesn't recognize +the variable \fIname\fR, it should return TCL_CONTINUE, and the +name resolution will continue with another procedure or with the +default Tcl resolution scheme. If this procedure recognizes +the variable \fIname\fR, but for some reason the variable is +not accessible, the procedure should return TCL_ERROR. If the +\fIflags\fR argument contains TCL_LEAVE_ERR_MSG, the procedure +should leave an error message in the interpreter, explaining why +the variable reference is invalid. +.PP +Note that this procedure should look for the TCL_GLOBAL_ONLY and +TCL_NAMESPACE_ONLY flags. It should handle them appropriately, or +return TCL_CONTINUE and let Tcl handle the reference. But it should +not ignore the flags. +.PP +Tcl also resolves variables when a body of code is compiled; the +\fIcompiledVarProc\fR procedure handles that case. It must +conform to the following type: +.CS +typedef int Tcl_ResolveCompiledVarProc(Tcl_Interp* \fIinterp\fR, + char* \fIname\fR, int \fIlength\fR, Tcl_Namespace* \fIcontext\fR, + Tcl_ResolvedVarInfo* \fIrPtr\fR); +.CE +The \fIinterp\fR argument is the interpreter performing the resolution; +\fIname\fR is the variable name being resolved; \fIlength\fR is the +number of bytes in \fIname\fR, which is not a null-terminated +string; and \fIcontext\fR is the namespace context containing the +variable reference. +.PP +If this procedure recognizes the variable \fIname\fR, it should +return some information characterizing the variable in the +\fIrPtr\fR structure. This structure is defined as follows: +.CS +typedef struct Tcl_ResolvedVarInfo { + ClientData \fIidentity\fR; + Tcl_ResolveRuntimeVarProc *\fIfetchProc\fR; + Tcl_ResolveVarDeleteProc *\fIdeleteProc\fR; +} Tcl_ResolvedVarInfo; +.CE +The \fIidentity\fR field is an arbitrary value that characterizes +the variable. Each variable should have a unique identity. Each +time the compiled code is executed, Tcl will call the \fIfetchProc\fR +procedure to get the actual variable for a particular \fIidentity\fR +value. This callback procedure must conform to the following type: +.CS +typedef Tcl_Var Tcl_ResolveRuntimeVarProc(Tcl_Interp* \fIinterp\fR, + ClientData \fIidentity\fR); +.CE +The \fIfetchProc\fR procedure takes the \fIinterp\fR interpreter +and the \fIidentity\fR from compile time and returns a Tcl_Var +token representing the variable. If for some reason the variable +can't be found, this procedure should return NULL, and Tcl will +create a local variable within the call frame of the procedure +being executed. +.PP +When the compiled code is discarded, Tcl calls the \fIdeleteProc\fR +procedure to release the \fIidentity\fR data. The delete procedure +must conform to the following type: +.CS +typedef void Tcl_ResolveVarDeleteProc(ClientData \fIidentity\fR); +.CE +.PP +In general, the \fIvarProc\fR and \fIcompiledVarProc\fR procedures +should \fIboth\fR be defined. If the \fIcompiledVarProc\fR is not +defined, then Tcl will create local variables for any variable +names that are not recognized within a procedure. If the \fIvarProc\fR +is not defined, then Tcl will not recognize variables that are +encountered at runtime. For example, consider the following procedure: +.CS +proc foo {args} { + set anotherRef "1" + set name "another" + set ${name}Ref "2" +} +.CE +Suppose that the \fIcompiledVarProc\fR resolves the name +\fBanotherRef\fR at compile time. The name \fB${name}Ref\fR +can't be resolved at compile time, so the resolution of that +name is deferred to run time. If the \fIvarProc\fR procedure +must intercept the name \fBanotherRef\fR at run time and +supply the appropriate variable. + +.SH KEYWORDS +interpreter, namespace, resolution

Resolvers.3 Property changes : Added: svn:executable ## -0,0 +1 ## +* \ No newline at end of property Index: local.n =================================================================== --- local.n (nonexistent) +++ local.n (revision 1765) @@ -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. +'\" +'\" RCS: $Id: local.n,v 1.1.1.1 2002-01-16 10:24:46 markom Exp $ +'\" +.so man.macros +.TH local n "" itcl "[incr\ Tcl]" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +local \- create an object local to a procedure +.SH SYNOPSIS +\fBlocal \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 +"\fCitcl-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 +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. +.CS +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: [info objects]" +.CE + +.SH KEYWORDS +class, object, procedure

local.n Property changes : Added: svn:executable ## -0,0 +1 ## +* \ No newline at end of property Index: ensemble.n =================================================================== --- ensemble.n (nonexistent) +++ ensemble.n (revision 1765) @@ -0,0 +1,173 @@ +'\" +'\" Copyright (c) 1993-1998 Lucent Technologies, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: $Id: ensemble.n,v 1.1.1.1 2002-01-16 10:24:46 markom Exp $ +'\" +.so man.macros +.TH ensemble n 3.0 itcl "[incr\ Tcl]" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +ensemble \- create or modify a composite command +.SH SYNOPSIS +\fBensemble \fIensName\fR ?\fIcommand arg arg...\fR? +.br +or +.br +\fBensemble \fIensName\fR { +.br + \fBpart \fIpartName args body\fR +.br + \fI...\fR +.br + \fBensemble \fIpartName\fR { +.br + \fBpart \fIsubPartName args body\fR +.br + \fBpart \fIsubPartName args body\fR +.br + \fI...\fR + } +.br +} +.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?" +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: +.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\fR +.CE +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 +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: +.CS +vwait x +tkwait visibility .top +tkwait window . +.CE +we could use commands with a uniform syntax, like this: +.CS +wait variable x +wait visibility .top +wait window . +.CE +The Tcl package could define the following ensemble: +.CS +ensemble wait part variable {name} { + uplevel vwait $name +} +.CE +The Tk package could add some options to this ensemble, with a +command like this: +.CS +ensemble wait { + part visibility {name} { + tkwait visibility $name + } + part window {name} { + tkwait window $name + } +} +.CE +Other extensions could add their own parts to the \fBwait\fR command +too. + +.SH KEYWORDS +ensemble, part, info

ensemble.n Property changes : Added: svn:executable ## -0,0 +1 ## +* \ No newline at end of property Index: itcl.n =================================================================== --- itcl.n (nonexistent) +++ itcl.n (revision 1765) @@ -0,0 +1,147 @@ +'\" +'\" Copyright (c) 1993-1998 Lucent Technologies, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: $Id: itcl.n,v 1.1.1.1 2002-01-16 10:24:46 markom Exp $ +'\" +.so man.macros +.TH itcl n 3.0 itcl "[incr\ Tcl]" +.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

itcl.n Property changes : Added: svn:executable ## -0,0 +1 ## +* \ No newline at end of property Index: body.n =================================================================== --- body.n (nonexistent) +++ body.n (revision 1765) @@ -0,0 +1,124 @@ +'\" +'\" Copyright (c) 1993-1998 Lucent Technologies, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: $Id: body.n,v 1.1.1.1 2002-01-16 10:24:46 markom Exp $ +'\" +.so man.macros +.TH body n 3.0 itcl "[incr\ Tcl]" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +body \- change the body for a class method/proc +.SH SYNOPSIS +\fBbody \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 +class File { + private variable fid "" + constructor {name access} { + set fid [open $name $access] + } + destructor { + close $fid + } + + method get {} + method put {line} + method eof {} +} + +body File::get {} { + return [gets $fid] +} +body File::put {line} { + puts $fid $line +} +body File::eof {} { + return [::eof $fid] +} + +# +# See the File class in action: +# +File x /etc/passwd "r" +while {![x eof]} { + puts "=> [x get]" +} +delete object x +.CE + +.SH KEYWORDS +class, object, procedure

body.n Property changes : Added: svn:executable ## -0,0 +1 ## +* \ No newline at end of property Index: man.macros =================================================================== --- man.macros (nonexistent) +++ man.macros (revision 1765) @@ -0,0 +1,236 @@ +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" SCCS: @(#) man.macros 1.9 97/08/22 18:50:59 +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ie !"\\$3"" \{\ +.ta \\n()Au \\n()Bu +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +..

man.macros Property changes : Added: svn:executable ## -0,0 +1 ## +* \ No newline at end of property Index: delete.n =================================================================== --- delete.n (nonexistent) +++ delete.n (revision 1765) @@ -0,0 +1,64 @@ +'\" +'\" Copyright (c) 1993-1998 Lucent Technologies, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: $Id: delete.n,v 1.1.1.1 2002-01-16 10:24:46 markom Exp $ +'\" +.so man.macros +.TH delete n 3.0 itcl "[incr\ Tcl]" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +delete \- delete things in the interpreter +.SH SYNOPSIS +\fBdelete \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. +.sp +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. +.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. +.sp +If the access command for an object resides in another namespace, +then its qualified name can be used: +.CS +delete object foo::bar::x +.CE +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. +.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

delete.n Property changes : Added: svn:executable ## -0,0 +1 ## +* \ No newline at end of property Index: class.n =================================================================== --- class.n (nonexistent) +++ class.n (revision 1765) @@ -0,0 +1,490 @@ +'\" +'\" Copyright (c) 1993-1998 Lucent Technologies, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: $Id: class.n,v 1.1.1.1 2002-01-16 10:24:46 markom Exp $ +'\" +.so man.macros +.TH class n "" itcl "[incr\ Tcl]" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +class \- create a class of objects +.SH SYNOPSIS +\fBclass \fIclassName\fR \fB{ +.br + \fBinherit \fIbaseClass\fR ?\fIbaseClass\fR...? +.br + \fBconstructor \fIargs\fR ?\fIinit\fR? \fIbody\fR +.br + \fBdestructor \fIbody\fR +.br + \fBmethod \fIname\fR ?\fIargs\fR? ?\fIbody\fR? +.br + \fBproc \fIname ?\fIargs\fR? ?\fIbody\fR? +.br + \fBvariable \fIvarName\fR ?\fIinit\fR? ?\fIconfig\fR? +.br + \fBcommon \fIvarName\fR ?\fIinit\fR? +.sp + \fBpublic \fIcommand\fR ?\fIarg arg ...\fR? +.br + \fBprotected \fIcommand\fR ?\fIarg arg ...\fR? +.br + \fBprivate \fIcommand\fR ?\fIarg arg ...\fR? +.sp + \fBset \fIvarName\fR ?\fIvalue\fR? +.br + \fBarray \fIoption\fR ?\fIarg arg ...\fR? +.br +\fB}\fR +.sp +\fIclassName objName\fR ?\fIarg arg ...\fR? +.sp +\fIobjName method\fR ?\fIarg arg ...\fR? +.sp +\fIclassName::proc ?\fIarg arg ...\fR? +.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. +.sp +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: +.CS +inherit Foo Bar +.CE +then the name "x" means "Foo::x". Other inherited members named +"x" must be referenced with their explicit name, like "Bar::x". +.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. +.sp +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. +.sp +If construction is successful, the constructor always returns +the object name\-regardless of how the \fIbody\fR is defined\-and +the object name becomes a command in the current namespace context. +If construction fails, an error message is returned. +.TP +\fBdestructor \fIbody\fR +Declares the \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. +.sp +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. +.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. +.sp +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. +.sp +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. +.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. +.sp +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. +.sp +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. +.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. +.sp +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. +.sp +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. +.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. +.sp +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. +.sp +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: +.CS +class Foo { + common boolean + set boolean(true) 1 + set boolean(false) 0 +} +.CE +Note that if common data members are initialized within the +constructor, they get initialized again and again whenever new +objects are created. +.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. + +.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. +.sp +If \fIobjName\fR contains the string "\fB#auto\fR", that string is +replaced with an automatically generated name. Names have the +form \fIclassName\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: +.CS +fileselectiondialog .foo.bar.#auto -background red +.CE +This would generate an object named ".foo.bar.fileselectiondialog0". + +.SH OBJECT USAGE +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\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. +.sp +If a single \fIoption\fR of the form "\fB-\fIvarName\fR" is specified, +then this method returns the information for that one variable. +.sp +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. +.TP +\fIobjName\fR \fBisa \fIclassName\fR +Returns non-zero if the given \fIclassName\fR can be found in the +object's heritage, and zero otherwise. +.TP +\fIobjName\fR \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\fR \fBinfo class\fR +Returns the name of the most-specific class for object \fIobjName\fR. +.TP +\fIobjName\fR \fBinfo inherit\fR +Returns the list of base classes as they were defined in the +"\fBinherit\fR" command, or an empty string if this class +has no base classes. +.TP +\fIobjName\fR \fBinfo heritage\fR +Returns the current class name and the entire list of base classes +in the order that they are traversed for member lookup and object +destruction. +.TP +\fIobjName\fR \fBinfo 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\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. + +.SH CHAINING METHODS/PROCS +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: +.CS +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 +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: +.CS +class SmartToaster { + inherit Toaster + method toast {nslices} { + if {$crumbs > 40} { + clean + } + return [Toaster::toast $nslices] + } +} +.CE +Instead of hard-coding the base class name, we can use the +"chain" command like this: +.CS +class SmartToaster { + inherit Toaster + method toast {nslices} { + if {$crumbs > 40} { + clean + } + return [chain $nslices] + } +} +.CE +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: +.CS +# Tcl autoload index file, version 2.0 for [incr Tcl] +# This file is generated by the "auto_mkindex" command +# and sourced to set up indexing information for one or +# more commands. Typically each line is a command that +# sets an element in the auto_index array, where the +# element name is the name of a command and the value is +# a script that loads the command. + +set auto_index(::Toaster) "source $dir/Toaster.itcl" +set auto_index(::SmartToaster) "source $dir/SmartToaster.itcl" +.PP +The \fBauto_mkindex\fR command is used to automatically +generate "tclIndex" files. +.CE +The auto-loader must be made aware of this directory by appending +the directory name to the "auto_path" variable. When this is in +place, classes will be auto-loaded as needed when used in an +application. + +.SH 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". +.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. + +.SH KEYWORDS +class, object, object-oriented

class.n Property changes : Added: svn:executable ## -0,0 +1 ## +* \ No newline at end of property Index: itcl_info.n =================================================================== --- itcl_info.n (nonexistent) +++ itcl_info.n (revision 1765) @@ -0,0 +1,62 @@ +'\" +'\" Copyright (c) 1993-1998 Lucent Technologies, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: $Id: itcl_info.n,v 1.1.1.1 2002-01-16 10:24:46 markom Exp $ +'\" +.so man.macros +.TH itcl_info n 3.0 itcl "[incr\ Tcl]" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +itcl_info \- query info regarding classes and objects (obsolete) +.SH SYNOPSIS +\fBitcl_info classes ?\fIpattern\fR? +.br +\fBitcl_info objects ?\fIpattern\fR? ?\fB-class \fIclassName\fR? ?\fB-isa \fIclassName\fR? +.BE + +.SH DESCRIPTION +.PP +This command is considered obsolete, but is retained for +backward-compatibility with earlier versions of \fB[incr\ Tcl]\fR. +It has been replaced by the "\fBinfo classes\fR" and "\fBinfo objects\fR" +commands, which should be used for any new development. + +.PP +The following commands are available in the global namespace to +query information about classes and objects that have been created. +.TP +\fBitcl_info classes ?\fIpattern\fR? +Returns a list of classes available in the current namespace context. +.VS +If a class belongs to the current namespace context, its simple name +is reported; otherwise, if a class is imported from another namespace, +its fully-qualified name is reported. +.VE +.sp +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. +.TP +\fBitcl_info objects ?\fIpattern\fR? ?\fB-class \fIclassName\fR? ?\fB-isa \fIclassName\fR? +Returns a list of objects available in the current namespace context. +.VS +If an object belongs to the current namespace context, its simple name +is reported; otherwise, if an object is imported from another namespace, +its fully-qualified access command is reported. +.VE +.sp +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. + +.SH KEYWORDS +class, object, object-oriented

itcl_info.n Property changes : Added: svn:executable ## -0,0 +1 ## +* \ No newline at end of property Index: scope.n =================================================================== --- scope.n (nonexistent) +++ scope.n (revision 1765) @@ -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. +'\" +'\" RCS: $Id: scope.n,v 1.1.1.1 2002-01-16 10:24:46 markom Exp $ +'\" +.so man.macros +.TH scope n "" Tcl "[incr\ Tcl]" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +scope \- capture the namespace context for a variable +.SH SYNOPSIS +\fBscope \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 string of the following form: +.CS +@itcl \fIobject varName\fP +.CE +This is recognized in any context as an instance variable belonging +to \fIobject\fR. So with itcl3.0 and beyond, it is 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 use the \fC@itcl\fR syntax directly. For example, +it is a bad idea to write code like this: +.CS +set {@itcl ::fred x} 3 +puts "value = ${@itcl ::fred x}" +.CE +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

scope.n Property changes : Added: svn:executable ## -0,0 +1 ## +* \ No newline at end of property Index: code.n =================================================================== --- code.n (nonexistent) +++ code.n (revision 1765) @@ -0,0 +1,96 @@ +'\" +'\" Copyright (c) 1993-1998 Lucent Technologies, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: $Id: code.n,v 1.1.1.1 2002-01-16 10:24:46 markom Exp $ +'\" +.so man.macros +.TH code n 3.0 itcl "[incr\ Tcl]" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +code \- capture the namespace context for a code fragment +.SH SYNOPSIS +\fBcode \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

code.n Property changes : Added: svn:executable ## -0,0 +1 ## +* \ No newline at end of property Index: license.terms =================================================================== --- license.terms (nonexistent) +++ license.terms (revision 1765) @@ -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. +========================================================================

license.terms Property changes : Added: svn:executable ## -0,0 +1 ## +* \ No newline at end of property Index: itcl_class.n =================================================================== --- itcl_class.n (nonexistent) +++ itcl_class.n (revision 1765) @@ -0,0 +1,419 @@ +'\" +'\" Copyright (c) 1993-1998 Lucent Technologies, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: $Id: itcl_class.n,v 1.1.1.1 2002-01-16 10:24:46 markom Exp $ +'\" +.so man.macros +.TH itcl_class n 3.0 itcl "[incr\ Tcl]" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +itcl_class \- create a class of objects (obsolete) +.SH SYNOPSIS +\fBitcl_class \fIclassName\fR \fB{ +.br + \fBinherit \fIbaseClass\fR ?\fIbaseClass\fR...? +.br + \fBconstructor \fIargs\fR ?\fIinit\fR? \fIbody\fR +.br + \fBdestructor \fIbody\fR +.br + \fBmethod \fIname args body\fR +.br + \fBproc \fIname args body\fR +.br + \fBpublic \fIvarName\fR ?\fIinit\fR? ?\fIconfig\fR? +.br + \fBprotected \fIvarName\fR ?\fIinit\fR? +.br + \fBcommon \fIvarName\fR ?\fIinit\fR? +.br +\fB}\fR +.sp +\fIclassName objName\fR ?\fIargs...\fR? +.br +\fIclassName\fR \fB#auto\fR ?\fIargs...\fR? +.br +\fIclassName\fR \fB::\fR \fIproc\fR ?\fIargs...\fR? +.sp +\fIobjName method\fR ?\fIargs...\fR? +.sp +\fICommands available within class methods/procs:\fR +.br +\fBglobal \fIvarName\fR ?\fIvarName...\fR? +.br +\fBprevious \fIcommand\fR ?\fIargs...\fR? +.br +\fBvirtual \fIcommand\fR ?\fIargs...\fR? +.BE + +.SH DESCRIPTION +.PP +This command is considered obsolete, but is retained for +backward-compatibility with earlier versions of \fB[incr\ Tcl]\fR. +It has been replaced by the \fBclass\fR command, which should +be used for any new development. + +.TP +\fBitcl_class \fIclassName definition\fR +Provides the definition for a class named \fIclassName\fR. If +\fIclassName\fR is already defined, then this command returns +an error. If the class definition is successfully parsed, +\fIclassName\fR becomes a command in the current namespace +context, handling the +creation of objects and providing access to class scope. +The class \fIdefinition\fR +is evaluated as a series of Tcl statements that define +elements within the class. In addition to the usual +commands, the following class definition commands are recognized: +.RS +.TP +\fBinherit \fIbaseClass\fR ?\fIbaseClass\fR...? +Declares one or more base classes, causing the current class to +inherit their characteristics. Classes must have been defined by +a previous \fBitcl_class\fR command, or must be available to the +auto-loading facility (see "AUTO-LOADING" below). A single class +definition can contain no more than one \fBinherit\fR command. +.RS +.LP +When the same member name appears in two or more base classes, +the base class that appears first in the \fBinherit\fR list takes +precedence. For example, if classes "Foo" and "Bar" both contain +the member "x", then the "\fBinherit\fR" statement: +.CS +inherit Foo Bar +.CE +allows "Foo::x" to be accessed simply as "x" but forces "Bar::x" (and +all other inherited members named "x") to be referenced with their +explicit "\fIclass\fR::\fImember\fR" name. +.RE +.TP +\fBconstructor \fIargs\fR ?\fIinit\fR? \fIbody\fR +Declares the argument list and body used for the constructor, which +is automatically invoked whenever an object is created. Before +.VS +the \fIbody\fR is executed, the optional \fIinit\fR statement is +used to invoke any base class constructors that require arguments. +Variables in the \fIargs\fR specification can be accessed in the +\fIinit\fR code fragment, and passed to base class constructors. +After evaluating the \fIinit\fR statement, any base class +constructors that have not been executed are invoked without +arguments. This ensures that all base classes are fully +constructed before the constructor \fIbody\fR is executed. +.VE +If construction is successful, the constructor always returns +the object name\-regardless of how the \fIbody\fR is defined\-and +the object name becomes a command in the current namespace context. +If construction fails, an error message is returned. +.TP +\fBdestructor \fIbody\fR +Declares the body used for the destructor, which is automatically invoked +whenever an object is deleted. If the destructor is successful, the object +data is destroyed and the object name is removed as a command from the +interpreter. If destruction fails, an error message is returned +and the object remains. +.RS +.LP +.VS +When an object is destroyed, all destructors in a class hierarchy +are invoked in order from most- to least-specific. This is the +order that the classes are reported by the "\fBinfo heritage\fR" +command, and it is exactly the opposite of the default constructor +order. +.VE +.RE +.TP +\fBmethod \fIname args body\fR +Declares a method called \fIname\fR with an argument list \fIargs\fR +and a \fIbody\fR of Tcl statements. A method is just like the usual +Tcl "proc" except that it has transparent access to +.VS +object-specific variables, as well as +.VE +common variables. Within the class scope, a method can be invoked +like any other command\-simply by using its name. Outside of the +class scope, the method name must be prefaced by an object +name. Methods in a base class that are redefined in the current class +or hidden by another base class can be explicitly scoped using the +"\fIclass\fR::\fImethod\fR" syntax. +.TP +\fBproc \fIname args body\fR +Declares a proc called \fIname\fR with an argument list \fIargs\fR +and a \fIbody\fR of Tcl statements. A proc is similar to a method, +except that it can be invoked without referring to a specific object, +and therefore has access only to common variables\-not +.VS +to object-specific variables declared with the \fBpublic\fR +and \fBprotected\fR commands. +.VE +Within the class scope, a proc can be invoked +like any other command\-simply by using its name. In any other +namespace context, the proc is invoked using a qualified name +like "\fIclassName\fB::\fIproc\fR". +Procs in a base class that are redefined in the current +class, or hidden by another base class, can also be accessed +via their qualified name. +.TP +\fBpublic \fIvarName\fR ?\fIinit\fR? ?\fIconfig\fR? +Declares a public variable named \fIvarName\fR. Public variables are +visible in methods within the scope of their class and any derived class. +In addition, they can be modified outside of the class scope using the special +"config" formal argument (see "ARGUMENT LISTS" above). If the optional +\fIinit\fR is specified, it is used as the initial value of the variable +when a new object is created. If the optional \fIconfig\fR command +is specified, +it is invoked whenever a public variable is modified via the "config" +formal argument; if the \fIconfig\fR command returns an error, the +public variable is reset to its value before configuration, and the +method handling the configuration returns an error. +.TP +\fBprotected \fIvarName\fR ?\fIinit\fR? +Declares a protected variable named \fIvarName\fR. Protected variables +are visible in methods within the scope of their class and any derived class, +but cannot +be modified outside of the class scope. If the optional \fIinit\fR +is specified, it is used as the initial value of the variable when a new +object is created. Initialization forces the variable to be a simple +scalar value; uninitialized variables, on the other hand, can be used +as arrays. All objects have a built-in protected variable named +"this" which is initialized to the instance name for the object. +.TP +\fBcommon \fIvarName\fR ?\fIinit\fR? +Declares a common variable named \fIvarName\fR. Common variables are +shared among all objects in a class. They are visible in methods and +procs in the scope of their class and any derived class, but cannot be +modified outside of the class scope. +If the optional \fIinit\fR is specified, it is used as the +initial value of the variable. Initialization forces the variable to be +a simple scalar value; uninitialized variables, on the other hand, can +be used as arrays. +.RS +.LP +Once a common variable has been declared, it can be configured using +ordinary Tcl code within the class definition. This facility is +particularly useful when the initialization of the variable is +non-trivial\-when the variable contains an array of values, for example: +.CS +itcl_class Foo { + . + . + common boolean + set boolean(true) 1 + set boolean(false) 0 +} +.CE +.RE +.RE + +.SH CLASS USAGE +.PP +When a class definition has been loaded (or made available to the +auto-loader), the class name can be used as a command. +.TP +\fIclassName objName\fR ?\fIargs...\fR? +Creates a new object in class \fIclassName\fR with the name \fIobjName\fR. +Remaining arguments are passed to the constructor. If construction is +successful, the object name is returned and this name becomes a command +in the current namespace context. Otherwise, an error is returned. +.TP +\fIclassName\fR #auto ?\fIargs...\fR? +Creates a new object in class \fIclassName\fR with an automatically +generated name. Names are of the form \fIclassName\fR, +.VS +where the \fIclassName\fR part is modified to start with a lowercase +letter. In class "Toaster", for example, the "\fB#auto\fR" specification +would produce names toaster0, toaster1, etc. Remaining arguments are +.VE +passed to the constructor. If construction is successful, the object +name is returned and this name becomes a command in the current +namespace context. Otherwise, an error is returned. +.TP +\fIclassName\fR :: \fIproc\fR ?\fIargs...\fR? +Used outside of the class scope to invoke a class proc named \fIproc\fR. +Class procs are like ordinary Tcl procs, except that they are executed +in the scope of the class and therefore have transparent +access to common data members. +.RS +.LP +.VS +Notice that, unlike any other scope qualifier in \fB[incr\ Tcl]\fR, the "::" +shown above is surrounded by spaces. This is unnecessary with the +new namespace facility, and is considered obsolete. The capability +is still supported, however, to provide backward-compatibility with +earlier versions. +.VE +.RE + +.SH OBJECT USAGE +.TP +\fIobjName method\fR ?\fIargs...\fR? +Invokes a method named \fImethod\fR to operate on the specified object. +Remaining arguments are passed to the method. The method name can +be "constructor", "destructor", any method name appearing in the +class definition, or any of the following built-in methods. +.SH BUILT-IN METHODS +.TP +\fIobjName\fR \fBisa \fIclassName\fR +Returns non-zero if the given \fIclassName\fR can be found in the +object's heritage, and zero otherwise. +.TP +\fIobjName\fR \fBdelete\fR +Invokes the destructor associated with an object. +If the destructor is successful, data associated with the object is +deleted and \fIobjName\fR is removed as a command from the +interpreter. Returns the empty string, regardless of the destructor +body. +.RS +.LP +.VS +The built-in \fBdelete\fR method has been replaced by the +"\fBdelete object\fR" command in the global namespace, and +is considered obsolete. The capability is still supported, +however, to provide backward-compatibility with earlier versions. +.VE +.RE +.TP +\fIobjName\fR \fBinfo \fIoption\fR ?\fIargs...\fR? +Returns information related to the class definition or to +a particular object named \fIobjName\fR. +The \fIoption\fR parameter includes the following things, as well as +the options recognized by the usual Tcl "info" command: +.RS +.TP +\fIobjName\fR \fBinfo class\fR +.VS +Returns the name of the most-specific class for object \fIobjName\fR. +.VE +.TP +\fIobjName\fR \fBinfo inherit\fR +Returns the list of base classes as they were defined in the +"\fBinherit\fR" command, or an empty string if this class +has no base classes. +.TP +\fIobjName\fR \fBinfo heritage\fR +Returns the current class name and the entire list of base classes in +the order that they are traversed for member lookup and object +destruction. +.TP +\fIobjName\fR \fBinfo method\fR ?\fImethodName\fR? ?\fB-args\fR? ?\fB-body\fR? +With no arguments, this command returns a list of all class methods. +If \fImethodName\fR is specified, it returns information for a specific method. +If neither of the optional \fB-args\fR or \fB-body\fR flags is specified, +a complete method definition is returned as a list of three elements +including the method name, argument list and body. Otherwise, the +requested information is returned without the method name. +If the \fImethodName\fR is not recognized, an empty string is returned. +.TP +\fIobjName\fR \fBinfo proc\fR ?\fIprocName\fR? ?\fB-args\fR? ?\fB-body\fR? +With no arguments, this command returns a list of all class procs. +If \fIprocName\fR is specified, it returns information for a specific proc. +If neither of the optional \fB-args\fR or \fB-body\fR flags is specified, +a complete proc definition is returned as a list of three elements +including the proc name, argument list and body. Otherwise, the +requested information is returned without the proc name. +If the \fIprocName\fR is not recognized, an empty string is returned. +.TP +\fIobjName\fR \fBinfo public\fR ?\fIvarName\fR? ?\fB-init\fR? ?\fB-value\fR? ?\fB-config\fR? +With no arguments, this command returns a list of all public variables. +If \fIvarName\fR is specified, it returns information for a specific public +variable. +If none of the optional \fB-init\fR, \fB-value\fR or \fB-config\fR flags +are specified, all available information is returned as a list of four +elements including the variable name, initial value, current value, +and configuration commands. Otherwise, the requested information is +returned without the variable name. +If the \fIvarName\fR is not recognized, an empty string is returned. +.TP +\fIobjName\fR \fBinfo protected\fR ?\fIvarName\fR? ?\fB-init\fR? ?\fB-value\fR? +With no arguments, this command returns a list of all protected variables. +If \fIvarName\fR is specified, it returns information for a specific protected +variable. +If neither of the optional \fB-init\fR or \fB-value\fR flags is specified, +all available information is returned as a list of three elements +including the variable name, initial value and current value. +Otherwise, the requested information is returned without the variable name. +If the \fIvarName\fR is not recognized, an empty string is returned. +.TP +\fIobjName\fR \fBinfo common\fR ?\fIvarName\fR? ?\fB-init\fR? ?\fB-value\fR? +With no arguments, this command returns a list of all common variables. +If \fIvarName\fR is specified, it returns information for a specific common +variable. +If neither of the optional \fB-init\fR or \fB-value\fR flags is specified, +all available information is returned as a list of three elements +including the variable name, initial value and current value. +Otherwise, the requested information is returned without the variable name. +If the \fIvarName\fR is not recognized, an empty string is returned. +.RE +.SH OTHER BUILT-IN COMMANDS +The following commands are also available within the scope of each class. +They cannot be accessed from outside of the class as proper methods or +procs; rather, they are useful inside the class when implementing its +functionality. +.TP +\fBglobal \fIvarName\fR ?\fIvarName...\fR? +Creates a link to one or more global variables in the current +namespace context. Global variables can also be accessed in +other namespaces by including namespace qualifiers in \fIvarName\fR. +This is useful when communicating with Tk widgets that rely on global +variables. +.TP +\fBprevious \fIcommand\fR ?\fIargs...\fR? +Invokes \fIcommand\fR in the scope of the most immediate base class +.VS +(i.e., the "previous" class) for the object. For classes using single +.VE +inheritance, this facility can be used to avoid hard-wired base class +references of the form "\fIclass\fR::\fIcommand\fR", making code easier +to maintain. For classes using multiple inheritance, the utility of +this function is dubious. +If the class at the relevant scope has no base class, an error is returned. +.TP +\fBvirtual \fIcommand\fR ?\fIargs...\fR? +.VS +Invokes \fIcommand\fR in the scope of the most-specific class for the +object. The methods within a class are automatically virtual; whenever +an unqualified method name is used, it always refers to the most-specific +implementation for that method. This function provides a way of +evaluating code fragments in a base class that have access to the +most-specific object information. It is useful, for example, for +creating base classes that can capture and save an object's state. +It inverts the usual notions of object-oriented programming, however, +and should therefore be used sparingly. +.VE + +.SH AUTO-LOADING +.PP +Class definitions need not be loaded explicitly; they can be loaded as +needed by the usual Tcl auto-loading facility. Each directory containing +class definition files should have an accompanying "tclIndex" file. +Each line in this file identifies a Tcl procedure or \fB[incr\ Tcl]\fR +class definition and the file where the definition can be found. +.PP +For example, suppose a directory contains the definitions for classes +"Toaster" and "SmartToaster". Then the "tclIndex" file for this +directory would look like: +.CS +# Tcl autoload index file, version 2.0 for [incr Tcl] +# This file is generated by the "auto_mkindex" command +# and sourced to set up indexing information for one or +# more commands. Typically each line is a command that +# sets an element in the auto_index array, where the +# element name is the name of a command and the value is +# a script that loads the command. + +set auto_index(::Toaster) "source $dir/Toaster.itcl" +set auto_index(::SmartToaster) "source $dir/SmartToaster.itcl" +.PP +The \fBauto_mkindex\fR command is used to automatically +generate "tclIndex" files. +.CE +The auto-loader must be made aware of this directory by appending +the directory name to the "auto_path" variable. When this is in +place, classes will be auto-loaded as needed when used in an +application. + +.SH KEYWORDS +class, object, object-oriented

itcl_class.n Property changes : Added: svn:executable ## -0,0 +1 ## +* \ No newline at end of property Index: find.n =================================================================== --- find.n (nonexistent) +++ find.n (revision 1765) @@ -0,0 +1,62 @@ +'\" +'\" Copyright (c) 1993-1998 Lucent Technologies, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: $Id: find.n,v 1.1.1.1 2002-01-16 10:24:46 markom Exp $ +'\" +.so man.macros +.TH find n 3.0 itcl "[incr\ Tcl]" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +find \- search for classes and objects +.SH SYNOPSIS +\fBfind \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 context. A class or object is +"available" if its access command can be found in the current +namespace context or in the global namespace. Therefore, +classes and objects created in the global namespace are +available to all other namespaces in a program. Classes and +objects created in one namespace can also be imported into +another using the \fBnamespace import\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 +\fBfind classes ?\fIpattern\fR? +Returns a list of classes found in the current namespace context. +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. +.sp +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. +.TP +\fBfind objects ?\fIpattern\fR? ?\fB-class \fIclassName\fR? ?\fB-isa \fIclassName\fR? +Returns a list of objects found in the current namespace context. +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. +.sp +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. + +.SH KEYWORDS +class, object, search, import

find.n Property changes : Added: svn:executable ## -0,0 +1 ## +* \ No newline at end of property