1class(n)                          [incr Tcl]                          class(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       itcl::class - create a class of objects
9

SYNOPSIS

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
20           public command ?arg arg ...?
21           protected command ?arg arg ...?
22           private command ?arg arg ...?
23
24           set varName ?value?
25           array option ?arg arg ...?
26       }
27
28       className objName ?arg arg ...?
29
30       objName method ?arg arg ...?
31
32       className::proc ?arg arg ...?
33______________________________________________________________________________
34
35

DESCRIPTION

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
46       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
52       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
57       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
61       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
66       A class can be deleted using the "delete  class"  command.   Individual
67       objects can be deleted using the "delete object" command.
68
69

CLASS DEFINITIONS

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
79       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
83              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
91                     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
99                            inherit Foo Bar
100
101                     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
105              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
110                     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
124                     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
130              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
138                     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
144              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
149                     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
154                     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
163              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
170                     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
175                     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
183              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
189                     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
196                     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
203              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
211                     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
217                     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
222                            itcl::class Foo {
223                                common boolean
224                                set boolean(true) 1
225                                set boolean(false) 0
226                            }
227
228                     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
232              public command ?arg arg ...?
233
234              protected command ?arg arg ...?
235
236              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

CLASS USAGE

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
249       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
261              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
269                     fileselectiondialog .foo.bar.#auto -background red
270
271              This would generate an object named  ".foo.bar.fileselectiondia‐
272              log0".
273

OBJECT USAGE

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
278       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

BUILT-IN METHODS

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
293       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
301              If  a  single  option  of the form "-varName" is specified, then
302              this method returns the information for that one variable.
303
304              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
312       objName isa className
313              Returns non-zero if the given className  can  be  found  in  the
314              object's heritage, and zero otherwise.
315
316       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
322              objName info class
323                     Returns the name of the most-specific  class  for  object
324                     objName.
325
326              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
331              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
336              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
347              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

CHAINING METHODS/PROCS

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
367              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
380       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
384              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
394       Instead of hard-coding the base class name, we can use the "chain" com‐
395       mand like this:
396
397              itcl::class SmartToaster {
398                  inherit Toaster
399                  method toast {nslices} {
400                      if {$crumbs > 40} {
401                          clean
402                      }
403                      return [chain $nslices]
404                  }
405              }
406
407       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

AUTO-LOADING

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
421       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
425              # 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
433              set auto_index(::Toaster) "source $dir/Toaster.itcl"
434              set auto_index(::SmartToaster) "source $dir/SmartToaster.itcl"
435
436       The  auto_mkindex  command is used to automatically generate "tclIndex"
437       files.
438
439       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

C PROCEDURES

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
449       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
456              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
464                  if (Itcl_RegisterC(interp, "foo", My_FooCmd) != TCL_OK) {
465                      return TCL_ERROR;
466                  }
467              }
468
469       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
477       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

KEYWORDS

484       class, object, object-oriented
485
486
487
488itcl                                                                  class(n)
Impressum