1class(n) [incr Tcl] class(n)
2______________________________________________________________________________
6
8 itcl::class - create a class of objects
9
11 itcl::class className {
12 inherit baseClass ?baseClass...?
13 constructor args ?init? body
14 destructor body
15 method name ?args? ?body?
16 proc name ?args? ?body?
17 variable varName ?init? ?config?
18 common varName ?init?
19 public command ?arg arg ...?
21 protected command ?arg arg ...?
22 private command ?arg arg ...?
23 set varName ?value?
25 array option ?arg arg ...?
26 }
27 className objName ?arg arg ...?
29 objName method ?arg arg ...?
31 className::proc ?arg arg ...?
33______________________________________________________________________________
34
37 The fundamental construct in [incr Tcl] is the class definition. Each
38 class acts as a template for actual objects that can be created. The
39 class itself is a namespace which contains things common to all
40 objects. Each object has its own unique bundle of data which contains
41 instances of the "variables" defined in the class definition. Each
42 object also has a built-in variable named "this", which contains the
43 name of the object. Classes can also have "common" data members that
44 are shared by all objects in a class.
45 Two types of functions can be included in the class definition. "Meth‐
47 ods" are functions which operate on a specific object, and therefore
48 have access to both "variables" and "common" data members. "Procs" are
49 ordinary procedures in the class namespace, and only have access to
50 "common" data members.
51 If the body of any method or proc starts with "@", it is treated as the
53 symbolic name for a C procedure. Otherwise, it is treated as a Tcl
54 code script. See below for details on registering and using C proce‐
55 dures.
56 A class can only be defined once, although the bodies of class methods
58 and procs can be defined again and again for interactive debugging.
59 See the body and configbody commands for details.
60 Each namespace can have its own collection of objects and classes. The
62 list of classes available in the current context can be queried using
63 the "itcl::find classes" command, and the list of objects, with the
64 "itcl::find objects" command.
65 A class can be deleted using the "delete class" command. Individual
67 objects can be deleted using the "delete object" command.
68
71 class className definition
72 Provides the definition for a class named className. If the
73 class className already exists, or if a command called className
74 exists in the current namespace context, this command returns an
75 error. If the class definition is successfully parsed, class‐
76 Name becomes a command in the current context, handling the cre‐
77 ation of objects for this class.
78 The class definition is evaluated as a series of Tcl statements that
80 define elements within the class. The following class definition com‐
81 mands are recognized:
82 inherit baseClass ?baseClass...?
84 Causes the current class to inherit characteristics from
85 one or more base classes. Classes must have been defined
86 by a previous class command, or must be available to the
87 auto-loading facility (see "AUTO-LOADING" below). A sin‐
88 gle class definition can contain no more than one inherit
89 command.
90 The order of baseClass names in the inherit list affects
92 the name resolution for class members. When the same
93 member name appears in two or more base classes, the base
94 class that appears first in the inherit list takes prece‐
95 dence. For example, if classes "Foo" and "Bar" both con‐
96 tain the member "x", and if another class has the
97 "inherit" statement:
98 inherit Foo Bar
100 then the name "x" means "Foo::x". Other inherited mem‐
102 bers named "x" must be referenced with their explicit
103 name, like "Bar::x".
104 constructor args ?init? body
106 Declares the args argument list and body used for the
107 constructor, which is automatically invoked whenever an
108 object is created.
109 Before the body is executed, the optional init statement
111 is used to invoke any base class constructors that
112 require arguments. Variables in the args specification
113 can be accessed in the init code fragment, and passed to
114 base class constructors. After evaluating the init
115 statement, any base class constructors that have not been
116 executed are invoked automatically without arguments.
117 This ensures that all base classes are fully constructed
118 before the constructor body is executed. By default,
119 this scheme causes constructors to be invoked in order
120 from least- to most-specific. This is exactly the oppo‐
121 site of the order that classes are reported by the info
122 heritage command.
123 If construction is successful, the constructor always
125 returns the object name-regardless of how the body is
126 defined-and the object name becomes a command in the cur‐
127 rent namespace context. If construction fails, an error
128 message is returned.
129 destructor body
131 Declares the body used for the destructor, which is auto‐
132 matically invoked when an object is deleted. If the
133 destructor is successful, the object data is destroyed
134 and the object name is removed as a command from the
135 interpreter. If destruction fails, an error message is
136 returned and the object remains.
137 When an object is destroyed, all destructors in its class
139 hierarchy are invoked in order from most- to least-spe‐
140 cific. This is the order that the classes are reported
141 by the "info heritage" command, and it is exactly the
142 opposite of the default constructor order.
143 method name ?args? ?body?
145 Declares a method called name. When the method body is
146 executed, it will have automatic access to object-spe‐
147 cific variables and common data members.
148 If the args list is specified, it establishes the usage
150 information for this method. The body command can be
151 used to redefine the method body, but the args list must
152 match this specification.
153 Within the body of another class method, a method can be
155 invoked like any other command-simply by using its name.
156 Outside of the class context, the method name must be
157 prefaced an object name, which provides the context for
158 the data that it manipulates. Methods in a base class
159 that are redefined in the current class, or hidden by
160 another base class, can be qualified using the "class‐
161 Name::method" syntax.
162 proc name ?args? ?body?
164 Declares a proc called name. A proc is an ordinary pro‐
165 cedure within the class namespace. Unlike a method, a
166 proc is invoked without referring to a specific object.
167 When the proc body is executed, it will have automatic
168 access only to common data members.
169 If the args list is specified, it establishes the usage
171 information for this proc. The body command can be used
172 to redefine the proc body, but the args list must match
173 this specification.
174 Within the body of another class method or proc, a proc
176 can be invoked like any other command-simply by using its
177 name. In any other namespace context, the proc is
178 invoked using a qualified name like "className::proc".
179 Procs in a base class that are redefined in the current
180 class, or hidden by another base class, can also be
181 accessed via their qualified name.
182 variable varName ?init? ?config?
184 Defines an object-specific variable named varName. All
185 object-specific variables are automatically available in
186 class methods. They need not be declared with anything
187 like the global command.
188 If the optional init string is specified, it is used as
190 the initial value of the variable when a new object is
191 created. Initialization forces the variable to be a sim‐
192 ple scalar value; uninitialized variables, on the other
193 hand, can be set within the constructor and used as
194 arrays.
195 The optional config script is only allowed for public
197 variables. If specified, this code fragment is executed
198 whenever a public variable is modified by the built-in
199 "configure" method. The config script can also be speci‐
200 fied outside of the class definition using the configbody
201 command.
202 common varName ?init?
204 Declares a common variable named varName. Common vari‐
205 ables reside in the class namespace and are shared by all
206 objects belonging to the class. They are just like
207 global variables, except that they need not be declared
208 with the usual global command. They are automatically
209 visible in all class methods and procs.
210 If the optional init string is specified, it is used as
212 the initial value of the variable. Initialization forces
213 the variable to be a simple scalar value; uninitialized
214 variables, on the other hand, can be set with subsequent
215 set and array commands and used as arrays.
216 Once a common data member has been defined, it can be set
218 using set and array commands within the class definition.
219 This allows common data members to be initialized as
220 arrays. For example:
221 itcl::class Foo {
223 common boolean
224 set boolean(true) 1
225 set boolean(false) 0
226 }
227 Note that if common data members are initialized within
229 the constructor, they get initialized again and again
230 whenever new objects are created.
231 public command ?arg arg ...?
233 protected command ?arg arg ...?
235 private command ?arg arg ...?
237 These commands are used to set the protection level for
238 class members that are created when command is evaluated.
239 The command is usually method, proc, variable orcommon,
240 and the remaining arg's complete the member definition.
241 However, command can also be a script containing many
242 different member definitions, and the protection level
243 will apply to all of the members that are created.
244
246 Once a class has been defined, the class name can be used as a command
247 to create new objects belonging to the class.
248 className objName ?args...?
250 Creates a new object in class className with the name objName.
251 Remaining arguments are passed to the constructor of the most-
252 specific class. This in turn passes arguments to base class
253 constructors before invoking its own body of commands. If con‐
254 struction is successful, a command called objName is created in
255 the current namespace context, and objName is returned as the
256 result of this operation. If an error is encountered during
257 construction, the destructors are automatically invoked to free
258 any resources that have been allocated, the object is deleted,
259 and an error is returned.
260 If objName contains the string "#auto", that string is replaced
262 with an automatically generated name. Names have the form
263 className<number>, where the className part is modified to start
264 with a lowercase letter. In class "Toaster", for example, the
265 "#auto" specification would produce names like toaster0,
266 toaster1, etc. Note that "#auto" can be also be buried within
267 an object name:
268 fileselectiondialog .foo.bar.#auto -background red
270 This would generate an object named ".foo.bar.fileselectiondia‐
272 log0".
273
275 Once an object has been created, the object name can be used as a com‐
276 mand to invoke methods that operate on the object.
277 objName method ?args...?
279 Invokes a method named method on an object named objName.
280 Remaining arguments are passed to the argument list for the
281 method. The method name can be "constructor", "destructor", any
282 method name appearing in the class definition, or any of the
283 following built-in methods.
284
286 objName cget option
287 Provides access to public variables as configuration options.
288 This mimics the behavior of the usual "cget" operation for Tk
289 widgets. The option argument is a string of the form "-var‐
290 Name", and this method returns the current value of the public
291 variable varName.
292 objName configure ?option? ?value option value ...?
294 Provides access to public variables as configuration options.
295 This mimics the behavior of the usual "configure" operation for
296 Tk widgets. With no arguments, this method returns a list of
297 lists describing all of the public variables. Each list has
298 three elements: the variable name, its initial value and its
299 current value.
300 If a single option of the form "-varName" is specified, then
302 this method returns the information for that one variable.
303 Otherwise, the arguments are treated as option/value pairs
305 assigning new values to public variables. Each variable is
306 assigned its new value, and if it has any "config" code associ‐
307 ated with it, it is executed in the context of the class where
308 it was defined. If the "config" code generates an error, the
309 variable is set back to its previous value, and the configure
310 method returns an error.
311 objName isa className
313 Returns non-zero if the given className can be found in the
314 object's heritage, and zero otherwise.
315 objName info option ?args...?
317 Returns information related to a particular object named obj‐
318 Name, or to its class definition. The option parameter includes
319 the following things, as well as the options recognized by the
320 usual Tcl "info" command:
321 objName info class
323 Returns the name of the most-specific class for object
324 objName.
325 objName info inherit
327 Returns the list of base classes as they were defined in
328 the "inherit" command, or an empty string if this class
329 has no base classes.
330 objName info heritage
332 Returns the current class name and the entire list of
333 base classes in the order that they are traversed for
334 member lookup and object destruction.
335 objName info function ?cmdName? ?-protection? ?-type? ?-name?
337 ?-args? ?-body?
338 With no arguments, this command returns a list of all
339 class methods and procs. If cmdName is specified, it
340 returns information for a specific method or proc. If no
341 flags are specified, this command returns a list with the
342 following elements: the protection level, the type
343 (method/proc), the qualified name, the argument list and
344 the body. Flags can be used to request specific elements
345 from this list.
346 objName info variable ?varName? ?-protection? ?-type? ?-name?
348 ?-init? ?-value? ?-config?
349 With no arguments, this command returns a list of all
350 object-specific variables and common data members. If
351 varName is specified, it returns information for a spe‐
352 cific data member. If no flags are specified, this com‐
353 mand returns a list with the following elements: the
354 protection level, the type (variable/common), the quali‐
355 fied name, the initial value, and the current value. If
356 varName is a public variable, the "config" code is
357 included on this list. Flags can be used to request spe‐
358 cific elements from this list.
359
361 Sometimes a base class has a method or proc that is redefined with the
362 same name in a derived class. This is a way of making the derived
363 class handle the same operations as the base class, but with its own
364 specialized behavior. For example, suppose we have a Toaster class
365 that looks like this:
366 itcl::class Toaster {
368 variable crumbs 0
369 method toast {nslices} {
370 if {$crumbs > 50} {
371 error "== FIRE! FIRE! =="
372 }
373 set crumbs [expr $crumbs+4*$nslices]
374 }
375 method clean {} {
376 set crumbs 0
377 }
378 }
379 We might create another class like SmartToaster that redefines the
381 "toast" method. If we want to access the base class method, we can
382 qualify it with the base class name, to avoid ambiguity:
383 itcl::class SmartToaster {
385 inherit Toaster
386 method toast {nslices} {
387 if {$crumbs > 40} {
388 clean
389 }
390 return [Toaster::toast $nslices]
391 }
392 }
393 Instead of hard-coding the base class name, we can use the "chain" com‐
395 mand like this:
396 itcl::class SmartToaster {
398 inherit Toaster
399 method toast {nslices} {
400 if {$crumbs > 40} {
401 clean
402 }
403 return [chain $nslices]
404 }
405 }
406 The chain command searches through the class hierarchy for a slightly
408 more generic (base class) implementation of a method or proc, and
409 invokes it with the specified arguments. It starts at the current
410 class context and searches through base classes in the order that they
411 are reported by the "info heritage" command. If another implementation
412 is not found, this command does nothing and returns the null string.
413
415 Class definitions need not be loaded explicitly; they can be loaded as
416 needed by the usual Tcl auto-loading facility. Each directory contain‐
417 ing class definition files should have an accompanying "tclIndex" file.
418 Each line in this file identifies a Tcl procedure or [incr Tcl] class
419 definition and the file where the definition can be found.
420 For example, suppose a directory contains the definitions for classes
422 "Toaster" and "SmartToaster". Then the "tclIndex" file for this direc‐
423 tory would look like:
424 # Tcl autoload index file, version 2.0 for [incr Tcl]
426 # This file is generated by the "auto_mkindex" command
427 # and sourced to set up indexing information for one or
428 # more commands. Typically each line is a command that
429 # sets an element in the auto_index array, where the
430 # element name is the name of a command and the value is
431 # a script that loads the command.
432 set auto_index(::Toaster) "source $dir/Toaster.itcl"
434 set auto_index(::SmartToaster) "source $dir/SmartToaster.itcl"
435 The auto_mkindex command is used to automatically generate "tclIndex"
437 files.
438 The auto-loader must be made aware of this directory by appending the
440 directory name to the "auto_path" variable. When this is in place,
441 classes will be auto-loaded as needed when used in an application.
442
444 C procedures can be integrated into an [incr Tcl] class definition to
445 implement methods, procs, and the "config" code for public variables.
446 Any body that starts with "@" is treated as the symbolic name for a C
447 procedure.
448 Symbolic names are established by registering procedures via Itcl_Reg‐
450 isterC(). This is usually done in the Tcl_AppInit() procedure, which
451 is automatically called when the interpreter starts up. In the follow‐
452 ing example, the procedure My_FooCmd() is registered with the symbolic
453 name "foo". This procedure can be referenced in the body command as
454 "@foo".
455 int
457 Tcl_AppInit(interp)
458 Tcl_Interp *interp; /* Interpreter for application. */
459 {
460 if (Itcl_Init(interp) == TCL_ERROR) {
461 return TCL_ERROR;
462 }
463 if (Itcl_RegisterC(interp, "foo", My_FooCmd) != TCL_OK) {
465 return TCL_ERROR;
466 }
467 }
468 C procedures are implemented just like ordinary Tcl commands. See the
470 CrtCommand man page for details. Within the procedure, class data mem‐
471 bers can be accessed like ordinary variables using Tcl_SetVar(),
472 Tcl_GetVar(), Tcl_TraceVar(), etc. Class methods and procs can be exe‐
473 cuted like ordinary commands using Tcl_Eval(). [incr Tcl] makes this
474 possible by automatically setting up the context before executing the C
475 procedure.
476 This scheme provides a natural migration path for code development.
478 Classes can be developed quickly using Tcl code to implement the bod‐
479 ies. An entire application can be built and tested. When necessary,
480 individual bodies can be implemented with C code to improve perfor‐
481 mance.
482
484 class, object, object-oriented
485itcl class(n)