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