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

NAME

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

WARNING!

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

SYNOPSIS

15       itcl::widget widgetName {
16           inherit baseWidget ?baseWidget...?
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
32           public command ?arg arg ...?
33           protected command ?arg arg ...?
34           private command ?arg arg ...?
35
36           <delegation info> see delegation page
37
38           <option info> see option page
39
40           set varName ?value?
41           array option ?arg arg ...?
42       }
43
44       widgetName objName ?arg arg ...?
45
46       objName method ?arg arg ...?
47
48       widgetName::proc ?arg arg ...?
49______________________________________________________________________________
50
51

DESCRIPTION

53       One of the fundamental constructs in [incr Tcl] is the  widget  defini‐
54       tion.   A  widget  is like a class with some additional features.  Each
55       widget acts as a template for actual objects that can be created.   The
56       widget  itself  is  a  namespace  which  contains  things common to all
57       objects.  Each object has its own unique bundle of data which  contains
58       instances  of  the  "variables" defined in the widget definition.  Each
59       object also has a built-in variable named "this",  which  contains  the
60       name  of  the object.  Widgets can also have "common" data members that
61       are shared by all objects in a widget.
62
63       Two types of functions  can  be  included  in  the  widget  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 widget namespace, and only have
67       access to "common" data members.
68
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.
73
74       A  widget can only be defined once, although the bodies of widget meth‐
75       ods and procs can be defined again and again for interactive debugging.
76       See the body and configbody commands for details.
77
78       Each namespace can have its own collection of objects and widgets.  The
79       list of widgets available in the current context can be  queried  using
80       the  "itcl::find  widgets"  command,  and the list of objects, with the
81       "itcl::find objects" command.
82
83       A widget can be deleted using the "delete widget" command.   Individual
84       objects can be deleted using the "delete object" command.
85
86

WIDGET DEFINITIONS

88       widget widgetName definition
89              Provides  the  definition for a widget named widgetName.  If the
90              widget widgetName already exists, or if a command called widget‐
91              Name  exists  in  the  current  namespace  context, this command
92              returns an error.  If  the  widget  definition  is  successfully
93              parsed,  widgetName  becomes  a  command in the current context,
94              handling the creation of objects for this widget.
95
96       The widget definition is evaluated as a series of Tcl  statements  that
97       define  elements  within  the  widget.  The following widget definition
98       commands are recognized:
99
100              inherit baseWidget ?baseWidget...?
101                     Causes the current widget to inherit characteristics from
102                     one or more base widgets.  Widgets must have been defined
103                     by a previous widget command, or must be available to the
104                     auto-loading facility (see "AUTO-LOADING" below).  A sin‐
105                     gle widget  definition  can  contain  no  more  than  one
106                     inherit command.
107
108                     The order of baseWidget names in the inherit list affects
109                     the name resolution for widget members.   When  the  same
110                     member name appears in two or more base widgets, the base
111                     widget that appears  first  in  the  inherit  list  takes
112                     precedence.  For example, if widgets "Foo" and "Bar" both
113                     contain the member "x", and if  another  widget  has  the
114                     "inherit" statement:
115
116                            inherit Foo Bar
117
118                     then  the  name "x" means "Foo::x".  Other inherited mem‐
119                     bers named "x" must be  referenced  with  their  explicit
120                     name, like "Bar::x".
121
122              constructor args ?init? body
123                     Declares  the  args  argument  list and body used for the
124                     constructor, which is automatically invoked  whenever  an
125                     object is created.
126
127                     Before  the body is executed, the optional init statement
128                     is used to  invoke  any  base  widget  constructors  that
129                     require  arguments.   Variables in the args specification
130                     can be accessed in the init code fragment, and passed  to
131                     base  widget  constructors.   After  evaluating  the init
132                     statement, any base widget  constructors  that  have  not
133                     been  executed  are  invoked  automatically without argu‐
134                     ments.  This ensures that all base widgets are fully con‐
135                     structed  before  the  constructor  body is executed.  By
136                     default, this scheme causes constructors to be invoked in
137                     order  from least- to most-specific.  This is exactly the
138                     opposite of the order that widgets are  reported  by  the
139                     info heritage command.
140
141                     If  construction  is  successful,  the constructor always
142                     returns the object name-regardless of  how  the  body  is
143                     defined-and the object name becomes a command in the cur‐
144                     rent namespace context.  If construction fails, an  error
145                     message is returned.
146
147              destructor body
148                     Declares the body used for the destructor, which is auto‐
149                     matically invoked when an  object  is  deleted.   If  the
150                     destructor  is  successful,  the object data is destroyed
151                     and the object name is removed  as  a  command  from  the
152                     interpreter.   If  destruction fails, an error message is
153                     returned and the object remains.
154
155                     When an object is destroyed, all destructors in its  wid‐
156                     get  hierarchy  are invoked in order from most- to least-
157                     specific.   This  is  the  order  that  the  widgets  are
158                     reported  by  the  "info  heritage"  command,  and  it is
159                     exactly the opposite of the default constructor order.
160
161              method name ?args? ?body?
162                     Declares a method called name.  When the method  body  is
163                     executed,  it  will  have automatic access to object-spe‐
164                     cific variables and common data members.
165
166                     If the args list is specified, it establishes  the  usage
167                     information  for  this  method.   The body command can be
168                     used to redefine the method body, but the args list  must
169                     match this specification.
170
171                     Within the body of another widget method, a method can be
172                     invoked like any other command-simply by using its  name.
173                     Outside  of  the  widget context, the method name must be
174                     prefaced an object name, which provides the  context  for
175                     the  data  that it manipulates.  Methods in a base widget
176                     that are redefined in the current widget,  or  hidden  by
177                     another  base widget, can be qualified using the "widget‐
178                     Name::method" syntax.
179
180              proc name ?args? ?body?
181                     Declares a proc called name.  A proc is an ordinary  pro‐
182                     cedure  within  the widget namespace.  Unlike a method, a
183                     proc is invoked without referring to a  specific  object.
184                     When  the  proc  body is executed, it will have automatic
185                     access only to common data members.
186
187                     If the args list is specified, it establishes  the  usage
188                     information  for this proc.  The body command can be used
189                     to redefine the proc body, but the args list  must  match
190                     this specification.
191
192                     Within  the body of another widget method or proc, a proc
193                     can be invoked like any other command-simply by using its
194                     name.   In  any  other  namespace  context,  the  proc is
195                     invoked using a qualified name  like  "widgetName::proc".
196                     Procs  in a base widget that are redefined in the current
197                     widget, or hidden by another base  widget,  can  also  be
198                     accessed via their qualified name.
199
200              variable varName ?init? ?config?
201                     Defines  an  object-specific variable named varName.  All
202                     object-specific variables are automatically available  in
203                     widget  methods.  They need not be declared with anything
204                     like the global command.
205
206                     If the optional init string is specified, it is  used  as
207                     the  initial  value  of the variable when a new object is
208                     created.  Initialization forces the variable to be a sim‐
209                     ple  scalar  value; uninitialized variables, on the other
210                     hand, can be set  within  the  constructor  and  used  as
211                     arrays.
212
213                     The  optional  config  script  is only allowed for public
214                     variables.  If specified, this code fragment is  executed
215                     whenever  a  public  variable is modified by the built-in
216                     "configure" method.  The config script can also be speci‐
217                     fied  outside  of the widget definition using the config‐
218                     body command.
219
220              common varName ?init?
221                     Declares a common variable named varName.   Common  vari‐
222                     ables  reside  in  the widget namespace and are shared by
223                     all objects belonging to the widget.  They are just  like
224                     global  variables,  except that they need not be declared
225                     with the usual global command.   They  are  automatically
226                     visible in all widget methods and procs.
227
228                     If  the  optional init string is specified, it is used as
229                     the initial value of the variable.  Initialization forces
230                     the  variable  to be a simple scalar value; uninitialized
231                     variables, on the other hand, can be set with  subsequent
232                     set and array commands and used as arrays.
233
234                     Once a common data member has been defined, it can be set
235                     using set and array commands within  the  widget  defini‐
236                     tion.   This allows common data members to be initialized
237                     as arrays.  For example:
238
239                            itcl::widget Foo {
240                                protected common boolean
241                                set boolean(true) 1
242                                set boolean(false) 0
243                            }
244
245                     Note that if common data members are  initialized  within
246                     the  constructor,  they  get  initialized again and again
247                     whenever new objects are created.
248
249              public command ?arg arg ...?
250
251              protected command ?arg arg ...?
252
253              private command ?arg arg ...?
254                     These commands are used to set the protection  level  for
255                     widget  members  that  are created when command is evalu‐
256                     ated.  The command  is  usually  method,  proc,  variable
257                     orcommon,  and  the  remaining  arg's complete the member
258                     definition.  However, command can also be a  script  con‐
259                     taining  many  different member definitions, and the pro‐
260                     tection level will apply to all of the members  that  are
261                     created.
262

WIDGET USAGE

264       Once  a  widget has been defined, the widget name can be used as a com‐
265       mand to create new objects belonging to the widget.
266
267       widgetName objName ?args...?
268              Creates a new object in widget widgetName with the name objName.
269              Remaining  arguments  are passed to the constructor of the most-
270              specific widget.  This in turn passes arguments to  base  widget
271              constructors  before invoking its own body of commands.  If con‐
272              struction is successful, a command called objName is created  in
273              the  current  namespace  context, and objName is returned as the
274              result of this operation.  If an  error  is  encountered  during
275              construction,  the destructors are automatically invoked to free
276              any resources that have been allocated, the object  is  deleted,
277              and an error is returned.
278
279              If  objName contains the string "#auto", that string is replaced
280              with an automatically generated name.  Names have the form  wid‐
281              getName<number>,  where the widgetName part is modified to start
282              with a lowercase letter.  In widget "Toaster", for example,  the
283              "#auto"   specification   would  produce  names  like  toaster0,
284              toaster1, etc.  Note that "#auto" can be also be  buried  within
285              an object name:
286
287                     fileselectiondialog .foo.bar.#auto -background red
288
289              This  would generate an object named ".foo.bar.fileselectiondia‐
290              log0".
291

OBJECT USAGE

293       Once an object has been created, the object name can be used as a  com‐
294       mand to invoke methods that operate on the object.
295
296       objName method ?args...?
297              Invokes  a  method  named  method  on  an  object named objName.
298              Remaining arguments are passed to  the  argument  list  for  the
299              method.  The method name can be "constructor", "destructor", any
300              method name appearing in the widget definition, or  any  of  the
301              following built-in methods.
302

BUILT-IN METHODS

304       objName cget option
305              Provides  access  to  public variables as configuration options.
306              This mimics the behavior of the usual "cget"  operation  for  Tk
307              widgets.   The  option  argument  is a string of the form "-var‐
308              Name", and this method returns the current value of  the  public
309              variable varName.
310
311       objName configure ?option? ?value option value ...?
312              Provides  access  to  public variables as configuration options.
313              This mimics the behavior of the usual "configure" operation  for
314              Tk  widgets.   With  no arguments, this method returns a list of
315              lists describing all of the public  variables.   Each  list  has
316              three  elements:   the  variable name, its initial value and its
317              current value.
318
319              If a single option of the form  "-varName"  is  specified,  then
320              this method returns the information for that one variable.
321
322              Otherwise,  the  arguments  are  treated  as  option/value pairs
323              assigning new values to  public  variables.   Each  variable  is
324              assigned  its new value, and if it has any "config" code associ‐
325              ated with it, it is executed in the context of the widget  where
326              it  was  defined.   If the "config" code generates an error, the
327              variable is set back to its previous value,  and  the  configure
328              method returns an error.
329
330       objName isa widgetName
331              Returns  non-zero  if  the  given widgetName can be found in the
332              object's heritage, and zero otherwise.
333
334       objName info option ?args...?
335              Returns information related to a particular  object  named  obj‐
336              Name,  or  to  its  widget  definition.   The  option  parameter
337              includes the following things, as well as the options recognized
338              by the usual Tcl "info" command:
339
340              objName info widget
341                     Returns  the  name of the most-specific widget for object
342                     objName.
343
344              objName info inherit
345                     Returns the list of base widgets as they were defined  in
346                     the  "inherit" command, or an empty string if this widget
347                     has no base widgets.
348
349              objName info heritage
350                     Returns the current widget name and the  entire  list  of
351                     base  widgets  in  the  order that they are traversed for
352                     member lookup and object destruction.
353
354              objName info function ?cmdName?  ?-protection?  ?-type?  ?-name?
355              ?-args? ?-body?
356                     With  no  arguments,  this  command returns a list of all
357                     widgets methods and procs.  If cmdName is  specified,  it
358                     returns information for a specific method or proc.  If no
359                     flags are specified, this command returns a list with the
360                     following  elements:   the  protection  level,  the  type
361                     (method/proc), the qualified name, the argument list  and
362                     the body.  Flags can be used to request specific elements
363                     from this list.
364
365              objName info variable ?varName?  ?-protection?  ?-type?  ?-name?
366              ?-init? ?-value? ?-config?
367                     With  no  arguments,  this  command returns a list of all
368                     object-specific variables and common  data  members.   If
369                     varName  is  specified, it returns information for a spe‐
370                     cific data member.  If no flags are specified, this  com‐
371                     mand  returns  a  list  with the following elements:  the
372                     protection level, the type (variable/common), the  quali‐
373                     fied  name, the initial value, and the current value.  If
374                     varName is  a  public  variable,  the  "config"  code  is
375                     included on this list.  Flags can be used to request spe‐
376                     cific elements from this list.
377

CHAINING METHODS/PROCS

379       Sometimes a base widget has a method or proc that is redefined with the
380       same  name  in  a  derived widget.  This is a way of making the derived
381       widget handle the same operations as the base widget, but with its  own
382       specialized  behavior.   For  example, suppose we have a Toaster widget
383       that looks like this:
384
385              itcl::widget Toaster {
386                  variable crumbs 0
387                  method toast {nslices} {
388                      if {$crumbs > 50} {
389                          error "== FIRE! FIRE! =="
390                      }
391                      set crumbs [expr $crumbs+4*$nslices]
392                  }
393                  method clean {} {
394                      set crumbs 0
395                  }
396              }
397
398       We might create another widget like  SmartToaster  that  redefines  the
399       "toast"  method.   If  we want to access the base widget method, we can
400       qualify it with the base widget name, to avoid ambiguity:
401
402              itcl::widget SmartToaster {
403                  inherit Toaster
404                  method toast {nslices} {
405                      if {$crumbs > 40} {
406                          clean
407                      }
408                      return [Toaster::toast $nslices]
409                  }
410              }
411
412       Instead of hard-coding the base widget name, we  can  use  the  "chain"
413       command like this:
414
415              itcl::widget SmartToaster {
416                  inherit Toaster
417                  method toast {nslices} {
418                      if {$crumbs > 40} {
419                          clean
420                      }
421                      return [chain $nslices]
422                  }
423              }
424
425       The  chain command searches through the widget hierarchy for a slightly
426       more generic (base widget) implementation of  a  method  or  proc,  and
427       invokes it with the specified arguments.  It starts at the current wid‐
428       get context and searches through base widgets in the  order  that  they
429       are reported by the "info heritage" command.  If another implementation
430       is not found, this command does nothing and returns the null string.
431
432

AUTO-LOADING

434       Widget definitions need not be loaded explicitly; they can be loaded as
435       needed by the usual Tcl auto-loading facility.  Each directory contain‐
436       ing widget definition files  should  have  an  accompanying  "tclIndex"
437       file.   Each line in this file identifies a Tcl procedure or [incr Tcl]
438       widget definition and the file where the definition can be found.
439
440       For example, suppose a directory contains the definitions  for  widgets
441       "Toaster" and "SmartToaster".  Then the "tclIndex" file for this direc‐
442       tory would look like:
443
444              # Tcl autoload index file, version 2.0 for [incr Tcl]
445              # This file is generated by the "auto_mkindex" command
446              # and sourced to set up indexing information for one or
447              # more commands.  Typically each line is a command that
448              # sets an element in the auto_index array, where the
449              # element name is the name of a command and the value is
450              # a script that loads the command.
451
452              set auto_index(::Toaster) "source $dir/Toaster.itcl"
453              set auto_index(::SmartToaster) "source $dir/SmartToaster.itcl"
454
455       The auto_mkindex command is used to automatically  generate  "tclIndex"
456       files.
457
458       The  auto-loader  must be made aware of this directory by appending the
459       directory name to the "auto_path" variable.  When  this  is  in  place,
460       widgets will be auto-loaded as needed when used in an application.
461
462

C PROCEDURES

464       C  procedures can be integrated into an [incr Tcl] widget definition to
465       implement methods, procs, and the "config" code for  public  variables.
466       Any  body  that starts with "@" is treated as the symbolic name for a C
467       procedure.
468
469       Symbolic names are established by registering procedures via  Itcl_Reg‐
470       isterC().   This  is usually done in the Tcl_AppInit() procedure, which
471       is automatically called when the interpreter starts up.  In the follow‐
472       ing  example, the procedure My_FooCmd() is registered with the symbolic
473       name "foo".  This procedure can be referenced in the  body  command  as
474       "@foo".
475
476              int
477              Tcl_AppInit(interp)
478                  Tcl_Interp *interp;     /* Interpreter for application. */
479              {
480                  if (Itcl_Init(interp) == TCL_ERROR) {
481                      return TCL_ERROR;
482                  }
483
484                  if (Itcl_RegisterC(interp, "foo", My_FooCmd) != TCL_OK) {
485                      return TCL_ERROR;
486                  }
487              }
488
489       C  procedures are implemented just like ordinary Tcl commands.  See the
490       CrtCommand man page for details.  Within  the  procedure,  widget  data
491       members  can  be  accessed  like ordinary variables using Tcl_SetVar(),
492       Tcl_GetVar(), Tcl_TraceVar(), etc.  Widget methods  and  procs  can  be
493       executed  like  ordinary  commands  using Tcl_Eval().  [incr Tcl] makes
494       this possible by automatically setting up the context before  executing
495       the C procedure.
496
497       This  scheme  provides  a  natural migration path for code development.
498       Widgets can be developed quickly using Tcl code to implement  the  bod‐
499       ies.   An  entire application can be built and tested.  When necessary,
500       individual bodies can be implemented with C  code  to  improve  perfor‐
501       mance.
502
503

KEYWORDS

505       widget, object, object-oriented
506
507
508
509itcl                                  4.0                            widget(n)
Impressum