1extendedclass(n) [incr Tcl] extendedclass(n)
2______________________________________________________________________________
6
8 itcl::extendedclass - create a extendedclass of objects
9
11 This is new functionality in [incr Tcl] where the API can still
12 change!!
13
15 itcl::extendedclass extendedclassName {
16 inherit baseExtendedclass ?baseExtendedclass...?
17 constructor args ?init? body
18 destructor body
19 public method name ?args? ?body?
20 protected method name ?args? ?body?
21 private method name ?args? ?body?
22 public proc name ?args? ?body?
23 protected proc name ?args? ?body?
24 private proc name ?args? ?body?
25 public variable varName ?init? ?config?
26 protected variable varName ?init? ?config?
27 private variable varName ?init? ?config?
28 public common varName ?init?
29 protected common varName ?init?
30 private common varName ?init?
31 public command ?arg arg ...?
33 protected command ?arg arg ...?
34 private command ?arg arg ...?
35 <delegation info> see delegation page
37 <option info> see option page
39 set varName ?value?
41 array option ?arg arg ...?
42 }
43 extendedclassName objName ?arg arg ...?
45 objName method ?arg arg ...?
47 extendedclassName::proc ?arg arg ...?
49______________________________________________________________________________
50
53 The fundamental construct in [incr Tcl] is the extendedclass defini‐
54 tion. Each extendedclass acts as a template for actual objects that
55 can be created. The extendedclass itself is a namespace which contains
56 things common to all objects. Each object has its own unique bundle of
57 data which contains instances of the "variables" defined in the extend‐
58 edclass definition. Each object also has a built-in variable named
59 "this", which contains the name of the object. Extendedclasses can
60 also have "common" data members that are shared by all objects in a
61 extendedclass.
62 Two types of functions can be included in the extendedclass definition.
64 "Methods" are functions which operate on a specific object, and there‐
65 fore have access to both "variables" and "common" data members.
66 "Procs" are ordinary procedures in the extendedclass namespace, and
67 only have access to "common" data members.
68 If the body of any method or proc starts with "@", it is treated as the
70 symbolic name for a C procedure. Otherwise, it is treated as a Tcl
71 code script. See below for details on registering and using C proce‐
72 dures.
73 A extendedclass can only be defined once, although the bodies of
75 extendedclass methods and procs can be defined again and again for
76 interactive debugging. See the body and configbody commands for
77 details.
78 Each namespace can have its own collection of objects and extended‐
80 classes. The list of extendedclasses available in the current context
81 can be queried using the "itcl::find extendedclasses" command, and the
82 list of objects, with the "itcl::find objects" command.
83 A extendedclass can be deleted using the "delete extendedclass" com‐
85 mand. Individual objects can be deleted using the "delete object" com‐
86 mand.
87
90 extendedclass extendedclassName definition
91 Provides the definition for a extendedclass named extendedclass‐
92 Name. If the extendedclass extendedclassName already exists, or
93 if a command called extendedclassName exists in the current
94 namespace context, this command returns an error. If the
95 extendedclass definition is successfully parsed, extendedclass‐
96 Name becomes a command in the current context, handling the cre‐
97 ation of objects for this extendedclass.
98 The extendedclass definition is evaluated as a series of Tcl statements
100 that define elements within the extendedclass. The following extended‐
101 class definition commands are recognized:
102 inherit baseExtendedclass ?baseExtendedclass...?
104 Causes the current extendedclass to inherit characteris‐
105 tics from one or more base extendedclasses. Extended‐
106 classes must have been defined by a previous extended‐
107 class command, or must be available to the auto-loading
108 facility (see "AUTO-LOADING" below). A single extended‐
109 class definition can contain no more than one inherit
110 command.
111 The order of baseExtendedclass names in the inherit list
113 affects the name resolution for extendedclass members.
114 When the same member name appears in two or more base
115 extendedclasses, the base extendedclass that appears
116 first in the inherit list takes precedence. For example,
117 if extendedclasses "Foo" and "Bar" both contain the mem‐
118 ber "x", and if another extendedclass has the "inherit"
119 statement:
120 inherit Foo Bar
122 then the name "x" means "Foo::x". Other inherited mem‐
124 bers named "x" must be referenced with their explicit
125 name, like "Bar::x".
126 constructor args ?init? body
128 Declares the args argument list and body used for the
129 constructor, which is automatically invoked whenever an
130 object is created.
131 Before the body is executed, the optional init statement
133 is used to invoke any base extendedclass constructors
134 that require arguments. Variables in the args specifica‐
135 tion can be accessed in the init code fragment, and
136 passed to base extendedclass constructors. After evalu‐
137 ating the init statement, any base extendedclass con‐
138 structors that have not been executed are invoked auto‐
139 matically without arguments. This ensures that all base
140 extendedclasses are fully constructed before the con‐
141 structor body is executed. By default, this scheme
142 causes constructors to be invoked in order from least- to
143 most-specific. This is exactly the opposite of the order
144 that extendedclasses are reported by the info heritage
145 command.
146 If construction is successful, the constructor always
148 returns the object name-regardless of how the body is
149 defined-and the object name becomes a command in the cur‐
150 rent namespace context. If construction fails, an error
151 message is returned.
152 destructor body
154 Declares the body used for the destructor, which is auto‐
155 matically invoked when an object is deleted. If the
156 destructor is successful, the object data is destroyed
157 and the object name is removed as a command from the
158 interpreter. If destruction fails, an error message is
159 returned and the object remains.
160 When an object is destroyed, all destructors in its extended‐
162 class hierarchy are invoked in order from most- to least-spe‐
163 cific. This is the order that the extendedclasses are reported
164 by the "info heritage" command, and it is exactly the opposite
165 of the default constructor order.
166 method name ?args? ?body?
168 Declares a method called name. When the method body is exe‐
169 cuted, it will have automatic access to object-specific vari‐
170 ables and common data members.
171 If the args list is specified, it establishes the usage informa‐
173 tion for this method. The body command can be used to redefine
174 the method body, but the args list must match this specifica‐
175 tion.
176 Within the body of another extendedclass method, a method can be
178 invoked like any other command-simply by using its name. Out‐
179 side of the extendedclass context, the method name must be pref‐
180 aced an object name, which provides the context for the data
181 that it manipulates. Methods in a base extendedclass that are
182 redefined in the current extendedclass, or hidden by another
183 base extendedclass, can be qualified using the "extendedclass‐
184 Name::method" syntax.
185 proc name ?args? ?body?
187 Declares a proc called name. A proc is an ordinary procedure
188 within the extendedclass namespace. Unlike a method, a proc is
189 invoked without referring to a specific object. When the proc
190 body is executed, it will have automatic access only to common
191 data members.
192 If the args list is specified, it establishes the usage informa‐
194 tion for this proc. The body command can be used to redefine
195 the proc body, but the args list must match this specification.
196 Within the body of another extendedclass method or proc, a proc
198 can be invoked like any other command-simply by using its name.
199 In any other namespace context, the proc is invoked using a
200 qualified name like "extendedclassName::proc". Procs in a base
201 extendedclass that are redefined in the current extendedclass,
202 or hidden by another base extendedclass, can also be accessed
203 via their qualified name.
204 variable varName ?init? ?config?
206 Defines an object-specific variable named varName. All object-
207 specific variables are automatically available in extendedclass
208 methods. They need not be declared with anything like the
209 global command.
210 If the optional init string is specified, it is used as the ini‐
212 tial value of the variable when a new object is created. Ini‐
213 tialization forces the variable to be a simple scalar value;
214 uninitialized variables, on the other hand, can be set within
215 the constructor and used as arrays.
216 The optional config script is only allowed for public variables.
218 If specified, this code fragment is executed whenever a public
219 variable is modified by the built-in "configure" method. The
220 config script can also be specified outside of the extendedclass
221 definition using the configbody command.
222 common varName ?init?
224 Declares a common variable named varName. Common variables
225 reside in the extendedclass namespace and are shared by all
226 objects belonging to the extendedclass. They are just like
227 global variables, except that they need not be declared with the
228 usual global command. They are automatically visible in all
229 extendedclass methods and procs.
230 If the optional init string is specified, it is used as the ini‐
232 tial value of the variable. Initialization forces the variable
233 to be a simple scalar value; uninitialized variables, on the
234 other hand, can be set with subsequent set and array commands
235 and used as arrays.
236 Once a common data member has been defined, it can be set using
238 set and array commands within the extendedclass definition.
239 This allows common data members to be initialized as arrays.
240 For example:
241 itcl::extendedclass Foo {
243 common boolean
244 set boolean(true) 1
245 set boolean(false) 0
246 }
247 Note that if common data members are initialized within the con‐
249 structor, they get initialized again and again whenever new
250 objects are created.
251 public command ?arg arg ...?
253 protected command ?arg arg ...?
255 private command ?arg arg ...?
257 These commands are used to set the protection level for extend‐
258 edclass members that are created when command is evaluated. The
259 command is usually method, proc, variable orcommon, and the
260 remaining arg's complete the member definition. However, com‐
261 mand can also be a script containing many different member defi‐
262 nitions, and the protection level will apply to all of the mem‐
263 bers that are created.
264
267 Once a extendedclass has been defined, the extendedclass name can be
268 used as a command to create new objects belonging to the extendedclass.
269 extendedclassName objName ?args...?
271 Creates a new object in extendedclass extendedclassName with the
272 name objName. Remaining arguments are passed to the constructor
273 of the most-specific extendedclass. This in turn passes argu‐
274 ments to base extendedclass constructors before invoking its own
275 body of commands. If construction is successful, a command
276 called objName is created in the current namespace context, and
277 objName is returned as the result of this operation. If an
278 error is encountered during construction, the destructors are
279 automatically invoked to free any resources that have been allo‐
280 cated, the object is deleted, and an error is returned.
281 If objName contains the string "#auto", that string is replaced
283 with an automatically generated name. Names have the form
284 extendedclassName<number>, where the extendedclassName part is
285 modified to start with a lowercase letter. In extendedclass
286 "Toaster", for example, the "#auto" specification would produce
287 names like toaster0, toaster1, etc. Note that "#auto" can be
288 also be buried within an object name:
289 fileselectiondialog .foo.bar.#auto -background red
291 This would generate an object named ".foo.bar.fileselectiondia‐
293 log0".
294
296 Once an object has been created, the object name can be used as a com‐
297 mand to invoke methods that operate on the object.
298 objName method ?args...?
300 Invokes a method named method on an object named objName.
301 Remaining arguments are passed to the argument list for the
302 method. The method name can be "constructor", "destructor", any
303 method name appearing in the extendedclass definition, or any of
304 the following built-in methods.
305
307 objName cget option
308 Provides access to public variables as configuration options.
309 This mimics the behavior of the usual "cget" operation for Tk
310 widgets. The option argument is a string of the form "-var‐
311 Name", and this method returns the current value of the public
312 variable varName.
313 objName configure ?option? ?value option value ...?
315 Provides access to public variables as configuration options.
316 This mimics the behavior of the usual "configure" operation for
317 Tk widgets. With no arguments, this method returns a list of
318 lists describing all of the public variables. Each list has
319 three elements: the variable name, its initial value and its
320 current value.
321 If a single option of the form "-varName" is specified, then
323 this method returns the information for that one variable.
324 Otherwise, the arguments are treated as option/value pairs
326 assigning new values to public variables. Each variable is
327 assigned its new value, and if it has any "config" code associ‐
328 ated with it, it is executed in the context of the extendedclass
329 where it was defined. If the "config" code generates an error,
330 the variable is set back to its previous value, and the config‐
331 ure method returns an error.
332 objName isa extendedclassName
334 Returns non-zero if the given extendedclassName can be found in
335 the object's heritage, and zero otherwise.
336 objName info option ?args...?
338 Returns information related to a particular object named obj‐
339 Name, or to its extendedclass definition. The option parameter
340 includes the following things, as well as the options recognized
341 by the usual Tcl "info" command:
342 objName info extendedclass
344 Returns the name of the most-specific extendedclass for
345 object objName.
346 objName info inherit
348 Returns the list of base extendedclasses as they were
349 defined in the "inherit" command, or an empty string if
350 this extendedclass has no base extendedclasses.
351 objName info heritage
353 Returns the current extendedclass name and the entire
354 list of base extendedclasses in the order that they are
355 traversed for member lookup and object destruction.
356 objName info function ?cmdName? ?-protection? ?-type? ?-name?
358 ?-args? ?-body?
359 With no arguments, this command returns a list of all
360 extendedclass methods and procs. If cmdName is speci‐
361 fied, it returns information for a specific method or
362 proc. If no flags are specified, this command returns a
363 list with the following elements: the protection level,
364 the type (method/proc), the qualified name, the argument
365 list and the body. Flags can be used to request specific
366 elements from this list.
367 objName info variable ?varName? ?-protection? ?-type? ?-name?
369 ?-init? ?-value? ?-config?
370 With no arguments, this command returns a list of all
371 object-specific variables and common data members. If
372 varName is specified, it returns information for a spe‐
373 cific data member. If no flags are specified, this com‐
374 mand returns a list with the following elements: the
375 protection level, the type (variable/common), the quali‐
376 fied name, the initial value, and the current value. If
377 varName is a public variable, the "config" code is
378 included on this list. Flags can be used to request spe‐
379 cific elements from this list.
380
382 Sometimes a base extendedclass has a method or proc that is redefined
383 with the same name in a derived extendedclass. This is a way of making
384 the derived extendedclass handle the same operations as the base
385 extendedclass, but with its own specialized behavior. For example,
386 suppose we have a Toaster extendedclass that looks like this:
387 itcl::extendedclass Toaster {
389 variable crumbs 0
390 method toast {nslices} {
391 if {$crumbs > 50} {
392 error "== FIRE! FIRE! =="
393 }
394 set crumbs [expr $crumbs+4*$nslices]
395 }
396 method clean {} {
397 set crumbs 0
398 }
399 }
400 We might create another extendedclass like SmartToaster that redefines
402 the "toast" method. If we want to access the base extendedclass
403 method, we can qualify it with the base extendedclass name, to avoid
404 ambiguity:
405 itcl::extendedclass SmartToaster {
407 inherit Toaster
408 method toast {nslices} {
409 if {$crumbs > 40} {
410 clean
411 }
412 return [Toaster::toast $nslices]
413 }
414 }
415 Instead of hard-coding the base extendedclass name, we can use the
417 "chain" command like this:
418 itcl::extendedclass SmartToaster {
420 inherit Toaster
421 method toast {nslices} {
422 if {$crumbs > 40} {
423 clean
424 }
425 return [chain $nslices]
426 }
427 }
428 The chain command searches through the extendedclass hierarchy for a
430 slightly more generic (base extendedclass) implementation of a method
431 or proc, and invokes it with the specified arguments. It starts at the
432 current extendedclass context and searches through base extendedclasses
433 in the order that they are reported by the "info heritage" command. If
434 another implementation is not found, this command does nothing and
435 returns the null string.
436
439 Extendedclass definitions need not be loaded explicitly; they can be
440 loaded as needed by the usual Tcl auto-loading facility. Each direc‐
441 tory containing extendedclass definition files should have an accompa‐
442 nying "tclIndex" file. Each line in this file identifies a Tcl proce‐
443 dure or [incr Tcl] extendedclass definition and the file where the def‐
444 inition can be found.
445 For example, suppose a directory contains the definitions for extended‐
447 classes "Toaster" and "SmartToaster". Then the "tclIndex" file for
448 this directory would look like:
449 # Tcl autoload index file, version 2.0 for [incr Tcl]
451 # This file is generated by the "auto_mkindex" command
452 # and sourced to set up indexing information for one or
453 # more commands. Typically each line is a command that
454 # sets an element in the auto_index array, where the
455 # element name is the name of a command and the value is
456 # a script that loads the command.
457 set auto_index(::Toaster) "source $dir/Toaster.itcl"
459 set auto_index(::SmartToaster) "source $dir/SmartToaster.itcl"
460 The auto_mkindex command is used to automatically generate "tclIndex"
462 files.
463 The auto-loader must be made aware of this directory by appending the
465 directory name to the "auto_path" variable. When this is in place,
466 extendedclasses will be auto-loaded as needed when used in an applica‐
467 tion.
468
471 C procedures can be integrated into an [incr Tcl] extendedclass defini‐
472 tion to implement methods, procs, and the "config" code for public
473 variables. Any body that starts with "@" is treated as the symbolic
474 name for a C procedure.
475 Symbolic names are established by registering procedures via Itcl_Reg‐
477 isterC(). This is usually done in the Tcl_AppInit() procedure, which
478 is automatically called when the interpreter starts up. In the follow‐
479 ing example, the procedure My_FooCmd() is registered with the symbolic
480 name "foo". This procedure can be referenced in the body command as
481 "@foo".
482 int
484 Tcl_AppInit(interp)
485 Tcl_Interp *interp; /* Interpreter for application. */
486 {
487 if (Itcl_Init(interp) == TCL_ERROR) {
488 return TCL_ERROR;
489 }
490 if (Itcl_RegisterC(interp, "foo", My_FooCmd) != TCL_OK) {
492 return TCL_ERROR;
493 }
494 }
495 C procedures are implemented just like ordinary Tcl commands. See the
497 CrtCommand man page for details. Within the procedure, extendedclass
498 data members can be accessed like ordinary variables using Tcl_Set‐
499 Var(), Tcl_GetVar(), Tcl_TraceVar(), etc. Extendedclass methods and
500 procs can be executed like ordinary commands using Tcl_Eval().
501 [incr Tcl] makes this possible by automatically setting up the context
502 before executing the C procedure.
503 This scheme provides a natural migration path for code development.
505 Extendedclasses can be developed quickly using Tcl code to implement
506 the bodies. An entire application can be built and tested. When nec‐
507 essary, individual bodies can be implemented with C code to improve
508 performance.
509
512 extendedclass, object, object-oriented
513itcl 4.0 extendedclass(n)