1widget(n) [incr Tcl] widget(n)
2______________________________________________________________________________
6
8 itcl::widget - create a widget class of objects
9
11 This is new functionality in [incr Tcl] where the API can still
12 change!!
13
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 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 widgetName objName ?arg arg ...?
45 objName method ?arg arg ...?
47 widgetName::proc ?arg arg ...?
49______________________________________________________________________________
50
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 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 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 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 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 A widget can be deleted using the "delete widget" command. Individual
84 objects can be deleted using the "delete object" command.
85
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 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 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 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 inherit Foo Bar
117 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 itcl::widget Foo {
240 protected common boolean
241 set boolean(true) 1
242 set boolean(false) 0
243 }
244 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 public command ?arg arg ...?
250 protected command ?arg arg ...?
252 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
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 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 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 fileselectiondialog .foo.bar.#auto -background red
288 This would generate an object named ".foo.bar.fileselectiondia‐
290 log0".
291
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 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
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 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 If a single option of the form "-varName" is specified, then
320 this method returns the information for that one variable.
321 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 objName isa widgetName
331 Returns non-zero if the given widgetName can be found in the
332 object's heritage, and zero otherwise.
333 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 objName info widget
341 Returns the name of the most-specific widget for object
342 objName.
343 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 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 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 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
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 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 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 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 Instead of hard-coding the base widget name, we can use the "chain"
413 command like this:
414 itcl::widget SmartToaster {
416 inherit Toaster
417 method toast {nslices} {
418 if {$crumbs > 40} {
419 clean
420 }
421 return [chain $nslices]
422 }
423 }
424 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
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 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 # 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 set auto_index(::Toaster) "source $dir/Toaster.itcl"
453 set auto_index(::SmartToaster) "source $dir/SmartToaster.itcl"
454 The auto_mkindex command is used to automatically generate "tclIndex"
456 files.
457 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
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 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 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 if (Itcl_RegisterC(interp, "foo", My_FooCmd) != TCL_OK) {
485 return TCL_ERROR;
486 }
487 }
488 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 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
505 widget, object, object-oriented
506itcl 4.0 widget(n)