1extendedclass(n)                  [incr Tcl]                  extendedclass(n)


8       itcl::extendedclass - create a extendedclass of objects


11       This  is  new  functionality  in  [incr  Tcl]  where  the API can still
12       change!!


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?
32           public command ?arg arg ...?
33           protected command ?arg arg ...?
34           private command ?arg arg ...?
36           <delegation info> see delegation page
38           <option info> see option page
40           set varName ?value?
41           array option ?arg arg ...?
42       }
44       extendedclassName objName ?arg arg ...?
46       objName method ?arg arg ...?
48       extendedclassName::proc ?arg arg ...?


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.
63       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.
69       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.
74       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.
79       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.
84       A  extendedclass  can  be deleted using the "delete extendedclass" com‐
85       mand.  Individual objects can be deleted using the "delete object" com‐
86       mand.


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.
99       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:
103              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.
112                     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:
121                            inherit Foo Bar
123                     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".
127              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.
132                     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.
147                     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.
153              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.
161              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.
167       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.
172              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.
177              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.
186       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.
193              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.
197              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.
205       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.
211              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.
217              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.
223       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.
231              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.
237              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:
242                     itcl::extendedclass Foo {
243                         common boolean
244                         set boolean(true) 1
245                         set boolean(false) 0
246                     }
248              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.
252       public command ?arg arg ...?
254       protected command ?arg arg ...?
256       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.


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.
270       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.
282              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:
290                     fileselectiondialog .foo.bar.#auto -background red
292              This  would generate an object named ".foo.bar.fileselectiondia‐
293              log0".


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.
299       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.


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.
314       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.
322              If a single option of the form  "-varName"  is  specified,  then
323              this method returns the information for that one variable.
325              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.
333       objName isa extendedclassName
334              Returns  non-zero if the given extendedclassName can be found in
335              the object's heritage, and zero otherwise.
337       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:
343              objName info extendedclass
344                     Returns  the  name of the most-specific extendedclass for
345                     object objName.
347              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.
352              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.
357              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.
368              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.


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:
388              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              }
401       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:
406              itcl::extendedclass SmartToaster {
407                  inherit Toaster
408                  method toast {nslices} {
409                      if {$crumbs > 40} {
410                          clean
411                      }
412                      return [Toaster::toast $nslices]
413                  }
414              }
416       Instead  of  hard-coding  the  base  extendedclass name, we can use the
417       "chain" command like this:
419              itcl::extendedclass SmartToaster {
420                  inherit Toaster
421                  method toast {nslices} {
422                      if {$crumbs > 40} {
423                          clean
424                      }
425                      return [chain $nslices]
426                  }
427              }
429       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.


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.
446       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:
450              # 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.
458              set auto_index(::Toaster) "source $dir/Toaster.itcl"
459              set auto_index(::SmartToaster) "source $dir/SmartToaster.itcl"
461       The  auto_mkindex  command is used to automatically generate "tclIndex"
462       files.
464       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.


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.
476       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".
483              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                  }
491                  if (Itcl_RegisterC(interp, "foo", My_FooCmd) != TCL_OK) {
492                      return TCL_ERROR;
493                  }
494              }
496       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.
504       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.


512       extendedclass, object, object-oriented
516itcl                                  4.0                     extendedclass(n)