1class(n) [incr Tcl] class(n)
2______________________________________________________________________________
6
8 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
99 then the name "x" means "Foo::x". Other inherited members named
100 "x" must be referenced with their explicit name, like "Bar::x".
101 constructor args ?init? body
103 Declares the args argument list and body used for the
104 constructor, which is automatically invoked whenever an
105 object is created.
106 Before the body is executed, the optional init statement
108 is used to invoke any base class constructors that
109 require arguments. Variables in the args specification
110 can be accessed in the init code fragment, and passed to
111 base class constructors. After evaluating the init
112 statement, any base class constructors that have not been
113 executed are invoked automatically without arguments.
114 This ensures that all base classes are fully constructed
115 before the constructor body is executed. By default,
116 this scheme causes constructors to be invoked in order
117 from least- to most-specific. This is exactly the oppo‐
118 site of the order that classes are reported by the info
119 heritage command.
120 If construction is successful, the constructor always
122 returns the object name-regardless of how the body is
123 defined-and the object name becomes a command in the cur‐
124 rent namespace context. If construction fails, an error
125 message is returned.
126 destructor body
128 Declares the body used for the destructor, which is auto‐
129 matically invoked when an object is deleted. If the
130 destructor is successful, the object data is destroyed
131 and the object name is removed as a command from the
132 interpreter. If destruction fails, an error message is
133 returned and the object remains.
134 When an object is destroyed, all destructors in its class
136 hierarchy are invoked in order from most- to least-spe‐
137 cific. This is the order that the classes are reported
138 by the "info heritage" command, and it is exactly the
139 opposite of the default constructor order.
140 method name ?args? ?body?
142 Declares a method called name. When the method body is
143 executed, it will have automatic access to object-spe‐
144 cific variables and common data members.
145 If the args list is specified, it establishes the usage
147 information for this method. The body command can be
148 used to redefine the method body, but the args list must
149 match this specification.
150 Within the body of another class method, a method can be
152 invoked like any other command-simply by using its name.
153 Outside of the class context, the method name must be
154 prefaced an object name, which provides the context for
155 the data that it manipulates. Methods in a base class
156 that are redefined in the current class, or hidden by
157 another base class, can be qualified using the "class‐
158 Name::method" syntax.
159 proc name ?args? ?body?
161 Declares a proc called name. A proc is an ordinary pro‐
162 cedure within the class namespace. Unlike a method, a
163 proc is invoked without referring to a specific object.
164 When the proc body is executed, it will have automatic
165 access only to common data members.
166 If the args list is specified, it establishes the usage
168 information for this proc. The body command can be used
169 to redefine the proc body, but the args list must match
170 this specification.
171 Within the body of another class method or proc, a proc
173 can be invoked like any other command-simply by using its
174 name. In any other namespace context, the proc is
175 invoked using a qualified name like "className::proc".
176 Procs in a base class that are redefined in the current
177 class, or hidden by another base class, can also be
178 accessed via their qualified name.
179 variable varName ?init? ?config?
181 Defines an object-specific variable named varName. All
182 object-specific variables are automatically available in
183 class methods. They need not be declared with anything
184 like the global command.
185 If the optional init string is specified, it is used as
187 the initial value of the variable when a new object is
188 created. Initialization forces the variable to be a sim‐
189 ple scalar value; uninitialized variables, on the other
190 hand, can be set within the constructor and used as
191 arrays.
192 The optional config script is only allowed for public
194 variables. If specified, this code fragment is executed
195 whenever a public variable is modified by the built-in
196 "configure" method. The config script can also be speci‐
197 fied outside of the class definition using the configbody
198 command.
199 common varName ?init?
201 Declares a common variable named varName. Common vari‐
202 ables reside in the class namespace and are shared by all
203 objects belonging to the class. They are just like
204 global variables, except that they need not be declared
205 with the usual global command. They are automatically
206 visible in all class methods and procs.
207 If the optional init string is specified, it is used as
209 the initial value of the variable. Initialization forces
210 the variable to be a simple scalar value; uninitialized
211 variables, on the other hand, can be set with subsequent
212 set and array commands and used as arrays.
213 Once a common data member has been defined, it can be set
215 using set and array commands within the class definition.
216 This allows common data members to be initialized as
217 arrays. For example:
218 itcl::class Foo {
219 common boolean
220 set boolean(true) 1
221 set boolean(false) 0
222 }
223 Note that if common data members are initialized within the con‐
224 structor, they get initialized again and again whenever new
225 objects are created.
226 public command ?arg arg ...?
228 protected command ?arg arg ...?
230 private command ?arg arg ...?
232 These commands are used to set the protection level for
233 class members that are created when command is evaluated.
234 The command is usually method, proc, variable orcommon,
235 and the remaining arg's complete the member definition.
236 However, command can also be a script containing many
237 different member definitions, and the protection level
238 will apply to all of the members that are created.
239
242 Once a class has been defined, the class name can be used as a command
243 to create new objects belonging to the class.
244 className objName ?args...?
246 Creates a new object in class className with the name objName.
247 Remaining arguments are passed to the constructor of the most-
248 specific class. This in turn passes arguments to base class
249 constructors before invoking its own body of commands. If con‐
250 struction is successful, a command called objName is created in
251 the current namespace context, and objName is returned as the
252 result of this operation. If an error is encountered during
253 construction, the destructors are automatically invoked to free
254 any resources that have been allocated, the object is deleted,
255 and an error is returned.
256 If objName contains the string "#auto", that string is replaced
258 with an automatically generated name. Names have the form
259 className<number>, where the className part is modified to start
260 with a lowercase letter. In class "Toaster", for example, the
261 "#auto" specification would produce names like toaster0,
262 toaster1, etc. Note that "#auto" can be also be buried within
263 an object name:
264 fileselectiondialog .foo.bar.#auto -background red
265 This would generate an object named ".foo.bar.fileselectiondialog0".
266
269 Once an object has been created, the object name can be used as a com‐
270 mand to invoke methods that operate on the object.
271 objName method ?args...?
273 Invokes a method named method on an object named objName.
274 Remaining arguments are passed to the argument list for the
275 method. The method name can be "constructor", "destructor", any
276 method name appearing in the class definition, or any of the
277 following built-in methods.
278
280 objName cget option
281 Provides access to public variables as configuration options.
282 This mimics the behavior of the usual "cget" operation for Tk
283 widgets. The option argument is a string of the form "-var‐
284 Name", and this method returns the current value of the public
285 variable varName.
286 objName configure ?option? ?value option value ...?
288 Provides access to public variables as configuration options.
289 This mimics the behavior of the usual "configure" operation for
290 Tk widgets. With no arguments, this method returns a list of
291 lists describing all of the public variables. Each list has
292 three elements: the variable name, its initial value and its
293 current value.
294 If a single option of the form "-varName" is specified, then
296 this method returns the information for that one variable.
297 Otherwise, the arguments are treated as option/value pairs
299 assigning new values to public variables. Each variable is
300 assigned its new value, and if it has any "config" code associ‐
301 ated with it, it is executed in the context of the class where
302 it was defined. If the "config" code generates an error, the
303 variable is set back to its previous value, and the configure
304 method returns an error.
305 objName isa className
307 Returns non-zero if the given className can be found in the
308 object's heritage, and zero otherwise.
309 objName info option ?args...?
311 Returns information related to a particular object named obj‐
312 Name, or to its class definition. The option parameter includes
313 the following things, as well as the options recognized by the
314 usual Tcl "info" command:
315 objName info class
317 Returns the name of the most-specific class for object
318 objName.
319 objName info inherit
321 Returns the list of base classes as they were defined in
322 the "inherit" command, or an empty string if this class
323 has no base classes.
324 objName info heritage
326 Returns the current class name and the entire list of
327 base classes in the order that they are traversed for
328 member lookup and object destruction.
329 objName info function ?cmdName? ?-protection? ?-type? ?-name?
331 ?-args? ?-body?
332 With no arguments, this command returns a list of all
333 class methods and procs. If cmdName is specified, it
334 returns information for a specific method or proc. If no
335 flags are specified, this command returns a list with the
336 following elements: the protection level, the type
337 (method/proc), the qualified name, the argument list and
338 the body. Flags can be used to request specific elements
339 from this list.
340 objName info variable ?varName? ?-protection? ?-type? ?-name?
342 ?-init? ?-value? ?-config?
343 With no arguments, this command returns a list of all
344 object-specific variables and common data members. If
345 varName is specified, it returns information for a spe‐
346 cific data member. If no flags are specified, this com‐
347 mand returns a list with the following elements: the
348 protection level, the type (variable/common), the quali‐
349 fied name, the initial value, and the current value. If
350 varName is a public variable, the "config" code is
351 included on this list. Flags can be used to request spe‐
352 cific elements from this list.
353
356 Sometimes a base class has a method or proc that is redefined with the
357 same name in a derived class. This is a way of making the derived
358 class handle the same operations as the base class, but with its own
359 specialized behavior. For example, suppose we have a Toaster class
360 that looks like this:
361 itcl::class Toaster {
362 variable crumbs 0
363 method toast {nslices} {
364 if {$crumbs > 50} {
365 error "== FIRE! FIRE! =="
366 }
367 set crumbs [expr $crumbs+4*$nslices]
368 }
369 method clean {} {
370 set crumbs 0
371 }
372 }
373 We might create another class like SmartToaster that redefines the
374 "toast" method. If we want to access the base class method, we can
375 qualify it with the base class name, to avoid ambiguity:
376 itcl::class SmartToaster {
377 inherit Toaster
378 method toast {nslices} {
379 if {$crumbs > 40} {
380 clean
381 }
382 return [Toaster::toast $nslices]
383 }
384 }
385 Instead of hard-coding the base class name, we can use the "chain" com‐
386 mand like this:
387 itcl::class SmartToaster {
388 inherit Toaster
389 method toast {nslices} {
390 if {$crumbs > 40} {
391 clean
392 }
393 return [chain $nslices]
394 }
395 }
396 The chain command searches through the class hierarchy for a slightly
397 more generic (base class) implementation of a method or proc, and
398 invokes it with the specified arguments. It starts at the current
399 class context and searches through base classes in the order that they
400 are reported by the "info heritage" command. If another implementation
401 is not found, this command does nothing and returns the null string.
402
405 Class definitions need not be loaded explicitly; they can be loaded as
406 needed by the usual Tcl auto-loading facility. Each directory contain‐
407 ing class definition files should have an accompanying "tclIndex" file.
408 Each line in this file identifies a Tcl procedure or [incr Tcl] class
409 definition and the file where the definition can be found.
410 For example, suppose a directory contains the definitions for classes
412 "Toaster" and "SmartToaster". Then the "tclIndex" file for this direc‐
413 tory would look like:
414 # Tcl autoload index file, version 2.0 for [incr Tcl]
415 # This file is generated by the "auto_mkindex" command
416 # and sourced to set up indexing information for one or
417 # more commands. Typically each line is a command that
418 # sets an element in the auto_index array, where the
419 # element name is the name of a command and the value is
420 # a script that loads the command.
421 set auto_index(::Toaster) "source $dir/Toaster.itcl"
423 set auto_index(::SmartToaster) "source $dir/SmartToaster.itcl"
424 The auto_mkindex command is used to automatically
426 generate "tclIndex" files.
427 The auto-loader must be made aware of this directory by appending the
428 directory name to the "auto_path" variable. When this is in place,
429 classes will be auto-loaded as needed when used in an application.
430
433 C procedures can be integrated into an [incr Tcl] class definition to
434 implement methods, procs, and the "config" code for public variables.
435 Any body that starts with "@" is treated as the symbolic name for a C
436 procedure.
437 Symbolic names are established by registering procedures via Itcl_Reg‐
439 isterC(). This is usually done in the Tcl_AppInit() procedure, which
440 is automatically called when the interpreter starts up. In the follow‐
441 ing example, the procedure My_FooCmd() is registered with the symbolic
442 name "foo". This procedure can be referenced in the body command as
443 "@foo".
444 int
445 Tcl_AppInit(interp)
446 Tcl_Interp *interp; /* Interpreter for application. */
447 {
448 if (Itcl_Init(interp) == TCL_ERROR) {
449 return TCL_ERROR;
450 }
451 if (Itcl_RegisterC(interp, "foo", My_FooCmd) != TCL_OK) {
453 return TCL_ERROR;
454 }
455 }
456 C procedures are implemented just like ordinary Tcl commands. See the
457 CrtCommand man page for details. Within the procedure, class data mem‐
458 bers can be accessed like ordinary variables using Tcl_SetVar(),
459 Tcl_GetVar(), Tcl_TraceVar(), etc. Class methods and procs can be exe‐
460 cuted like ordinary commands using Tcl_Eval(). [incr Tcl] makes this
461 possible by automatically setting up the context before executing the C
462 procedure.
463 This scheme provides a natural migration path for code development.
465 Classes can be developed quickly using Tcl code to implement the bod‐
466 ies. An entire application can be built and tested. When necessary,
467 individual bodies can be implemented with C code to improve perfor‐
468 mance.
469
472 class, object, object-oriented
473itcl class(n)