Provided by: tcl-itcl4-doc_4.2.2-1_all 
NAME
itcl::widget - create a widget class of objects
WARNING!
This is new functionality in [incr Tcl] where the API can still change!!
SYNOPSIS
itcl::widget widgetName {
inherit baseWidget ?baseWidget...?
constructor args ?init? body
destructor body
public method name ?args? ?body?
protected method name ?args? ?body?
private method name ?args? ?body?
public proc name ?args? ?body?
protected proc name ?args? ?body?
private proc name ?args? ?body?
public variable varName ?init? ?config?
protected variable varName ?init? ?config?
private variable varName ?init? ?config?
public common varName ?init?
protected common varName ?init?
private common varName ?init?
public command ?arg arg ...?
protected command ?arg arg ...?
private command ?arg arg ...?
<delegation info> see delegation page
<option info> see option page
set varName ?value?
array option ?arg arg ...?
}
widgetName objName ?arg arg ...?
objName method ?arg arg ...?
widgetName::proc ?arg arg ...?
_________________________________________________________________________________________________
DESCRIPTION
One of the fundamental constructs in [incr Tcl] is the widget definition. A widget is
like a class with some additional features. Each widget acts as a template for actual
objects that can be created. The widget itself is a namespace which contains things
common to all objects. Each object has its own unique bundle of data which contains
instances of the "variables" defined in the widget definition. Each object also has a
built-in variable named "this", which contains the name of the object. Widgets can also
have "common" data members that are shared by all objects in a widget.
Two types of functions can be included in the widget definition. "Methods" are functions
which operate on a specific object, and therefore have access to both "variables" and
"common" data members. "Procs" are ordinary procedures in the widget namespace, and only
have access to "common" data members.
If the body of any method or proc starts with "@", it is treated as the symbolic name for
a C procedure. Otherwise, it is treated as a Tcl code script. See below for details on
registering and using C procedures.
A widget can only be defined once, although the bodies of widget methods and procs can be
defined again and again for interactive debugging. See the body and configbody commands
for details.
Each namespace can have its own collection of objects and widgets. The list of widgets
available in the current context can be queried using the "itcl::find widgets" command,
and the list of objects, with the "itcl::find objects" command.
A widget can be deleted using the "delete widget" command. Individual objects can be
deleted using the "delete object" command.
WIDGET DEFINITIONS
widget widgetName definition
Provides the definition for a widget named widgetName. If the widget widgetName
already exists, or if a command called widgetName exists in the current namespace
context, this command returns an error. If the widget definition is successfully
parsed, widgetName becomes a command in the current context, handling the creation
of objects for this widget.
The widget definition is evaluated as a series of Tcl statements that define elements
within the widget. The following widget definition commands are recognized:
inherit baseWidget ?baseWidget...?
Causes the current widget to inherit characteristics from one or more base
widgets. Widgets must have been defined by a previous widget command, or
must be available to the auto-loading facility (see "AUTO-LOADING" below).
A single widget definition can contain no more than one inherit command.
The order of baseWidget names in the inherit list affects the name
resolution for widget members. When the same member name appears in two or
more base widgets, the base widget that appears first in the inherit list
takes precedence. For example, if widgets "Foo" and "Bar" both contain the
member "x", and if another widget has the "inherit" statement:
inherit Foo Bar
then the name "x" means "Foo::x". Other inherited members named "x" must be
referenced with their explicit name, like "Bar::x".
constructor args ?init? body
Declares the args argument list and body used for the constructor, which is
automatically invoked whenever an object is created.
Before the body is executed, the optional init statement is used to invoke
any base widget constructors that require arguments. Variables in the args
specification can be accessed in the init code fragment, and passed to base
widget constructors. After evaluating the init statement, any base widget
constructors that have not been executed are invoked automatically without
arguments. This ensures that all base widgets are fully constructed before
the constructor body is executed. By default, this scheme causes
constructors to be invoked in order from least- to most-specific. This is
exactly the opposite of the order that widgets are reported by the info
heritage command.
If construction is successful, the constructor always returns the object
name-regardless of how the body is defined-and the object name becomes a
command in the current namespace context. If construction fails, an error
message is returned.
destructor body
Declares the body used for the destructor, which is automatically invoked
when an object is deleted. If the destructor is successful, the object data
is destroyed and the object name is removed as a command from the
interpreter. If destruction fails, an error message is returned and the
object remains.
When an object is destroyed, all destructors in its widget hierarchy are
invoked in order from most- to least-specific. This is the order that the
widgets are reported by the "info heritage" command, and it is exactly the
opposite of the default constructor order.
method name ?args? ?body?
Declares a method called name. When the method body is executed, it will
have automatic access to object-specific variables and common data members.
If the args list is specified, it establishes the usage information for this
method. The body command can be used to redefine the method body, but the
args list must match this specification.
Within the body of another widget method, a method can be invoked like any
other command-simply by using its name. Outside of the widget context, the
method name must be prefaced an object name, which provides the context for
the data that it manipulates. Methods in a base widget that are redefined
in the current widget, or hidden by another base widget, can be qualified
using the "widgetName::method" syntax.
proc name ?args? ?body?
Declares a proc called name. A proc is an ordinary procedure within the
widget namespace. Unlike a method, a proc is invoked without referring to a
specific object. When the proc body is executed, it will have automatic
access only to common data members.
If the args list is specified, it establishes the usage information for this
proc. The body command can be used to redefine the proc body, but the args
list must match this specification.
Within the body of another widget method or proc, a proc can be invoked like
any other command-simply by using its name. In any other namespace context,
the proc is invoked using a qualified name like "widgetName::proc". Procs
in a base widget that are redefined in the current widget, or hidden by
another base widget, can also be accessed via their qualified name.
variable varName ?init? ?config?
Defines an object-specific variable named varName. All object-specific
variables are automatically available in widget methods. They need not be
declared with anything like the global command.
If the optional init string is specified, it is used as the initial value of
the variable when a new object is created. Initialization forces the
variable to be a simple scalar value; uninitialized variables, on the other
hand, can be set within the constructor and used as arrays.
The optional config script is only allowed for public variables. If
specified, this code fragment is executed whenever a public variable is
modified by the built-in "configure" method. The config script can also be
specified outside of the widget definition using the configbody command.
common varName ?init?
Declares a common variable named varName. Common variables reside in the
widget namespace and are shared by all objects belonging to the widget.
They are just like global variables, except that they need not be declared
with the usual global command. They are automatically visible in all widget
methods and procs.
If the optional init string is specified, it is used as the initial value of
the variable. Initialization forces the variable to be a simple scalar
value; uninitialized variables, on the other hand, can be set with
subsequent set and array commands and used as arrays.
Once a common data member has been defined, it can be set using set and
array commands within the widget definition. This allows common data
members to be initialized as arrays. For example:
itcl::widget Foo {
protected common boolean
set boolean(true) 1
set boolean(false) 0
}
Note that if common data members are initialized within the constructor,
they get initialized again and again whenever new objects are created.
public command ?arg arg ...?
protected command ?arg arg ...?
private command ?arg arg ...?
These commands are used to set the protection level for widget members that
are created when command is evaluated. The command is usually method, proc,
variable orcommon, and the remaining arg's complete the member definition.
However, command can also be a script containing many different member
definitions, and the protection level will apply to all of the members that
are created.
WIDGET USAGE
Once a widget has been defined, the widget name can be used as a command to create new
objects belonging to the widget.
widgetName objName ?args...?
Creates a new object in widget widgetName with the name objName. Remaining
arguments are passed to the constructor of the most-specific widget. This in turn
passes arguments to base widget constructors before invoking its own body of
commands. If construction is successful, a command called objName is created in
the current namespace context, and objName is returned as the result of this
operation. If an error is encountered during construction, the destructors are
automatically invoked to free any resources that have been allocated, the object is
deleted, and an error is returned.
If objName contains the string "#auto", that string is replaced with an
automatically generated name. Names have the form widgetName<number>, where the
widgetName part is modified to start with a lowercase letter. In widget "Toaster",
for example, the "#auto" specification would produce names like toaster0, toaster1,
etc. Note that "#auto" can be also be buried within an object name:
fileselectiondialog .foo.bar.#auto -background red
This would generate an object named ".foo.bar.fileselectiondialog0".
OBJECT USAGE
Once an object has been created, the object name can be used as a command to invoke
methods that operate on the object.
objName method ?args...?
Invokes a method named method on an object named objName. Remaining arguments are
passed to the argument list for the method. The method name can be "constructor",
"destructor", any method name appearing in the widget definition, or any of the
following built-in methods.
BUILT-IN METHODS
objName cget option
Provides access to public variables as configuration options. This mimics the
behavior of the usual "cget" operation for Tk widgets. The option argument is a
string of the form "-varName", and this method returns the current value of the
public variable varName.
objName configure ?option? ?value option value ...?
Provides access to public variables as configuration options. This mimics the
behavior of the usual "configure" operation for Tk widgets. With no arguments,
this method returns a list of lists describing all of the public variables. Each
list has three elements: the variable name, its initial value and its current
value.
If a single option of the form "-varName" is specified, then this method returns
the information for that one variable.
Otherwise, the arguments are treated as option/value pairs assigning new values to
public variables. Each variable is assigned its new value, and if it has any
"config" code associated with it, it is executed in the context of the widget where
it was defined. If the "config" code generates an error, the variable is set back
to its previous value, and the configure method returns an error.
objName isa widgetName
Returns non-zero if the given widgetName can be found in the object's heritage, and
zero otherwise.
objName info option ?args...?
Returns information related to a particular object named objName, or to its widget
definition. The option parameter includes the following things, as well as the
options recognized by the usual Tcl "info" command:
objName info widget
Returns the name of the most-specific widget for object objName.
objName info inherit
Returns the list of base widgets as they were defined in the "inherit"
command, or an empty string if this widget has no base widgets.
objName info heritage
Returns the current widget name and the entire list of base widgets in the
order that they are traversed for member lookup and object destruction.
objName info function ?cmdName? ?-protection? ?-type? ?-name? ?-args? ?-body?
With no arguments, this command returns a list of all widgets methods and
procs. If cmdName is specified, it returns information for a specific
method or proc. If no flags are specified, this command returns a list with
the following elements: the protection level, the type (method/proc), the
qualified name, the argument list and the body. Flags can be used to
request specific elements from this list.
objName info variable ?varName? ?-protection? ?-type? ?-name? ?-init? ?-value?
?-config?
With no arguments, this command returns a list of all object-specific
variables and common data members. If varName is specified, it returns
information for a specific data member. If no flags are specified, this
command returns a list with the following elements: the protection level,
the type (variable/common), the qualified name, the initial value, and the
current value. If varName is a public variable, the "config" code is
included on this list. Flags can be used to request specific elements from
this list.
CHAINING METHODS/PROCS
Sometimes a base widget has a method or proc that is redefined with the same name in a
derived widget. This is a way of making the derived widget handle the same operations as
the base widget, but with its own specialized behavior. For example, suppose we have a
Toaster widget that looks like this:
itcl::widget Toaster {
variable crumbs 0
method toast {nslices} {
if {$crumbs > 50} {
error "== FIRE! FIRE! =="
}
set crumbs [expr {$crumbs+4*$nslices}]
}
method clean {} {
set crumbs 0
}
}
We might create another widget like SmartToaster that redefines the "toast" method. If we
want to access the base widget method, we can qualify it with the base widget name, to
avoid ambiguity:
itcl::widget SmartToaster {
inherit Toaster
method toast {nslices} {
if {$crumbs > 40} {
clean
}
return [Toaster::toast $nslices]
}
}
Instead of hard-coding the base widget name, we can use the "chain" command like this:
itcl::widget SmartToaster {
inherit Toaster
method toast {nslices} {
if {$crumbs > 40} {
clean
}
return [chain $nslices]
}
}
The chain command searches through the widget hierarchy for a slightly more generic (base
widget) implementation of a method or proc, and invokes it with the specified arguments.
It starts at the current widget context and searches through base widgets in the order
that they are reported by the "info heritage" command. If another implementation is not
found, this command does nothing and returns the null string.
AUTO-LOADING
Widget definitions need not be loaded explicitly; they can be loaded as needed by the
usual Tcl auto-loading facility. Each directory containing widget definition files should
have an accompanying "tclIndex" file. Each line in this file identifies a Tcl procedure
or [incr Tcl] widget definition and the file where the definition can be found.
For example, suppose a directory contains the definitions for widgets "Toaster" and
"SmartToaster". Then the "tclIndex" file for this directory would look like:
# Tcl autoload index file, version 2.0 for [incr Tcl]
# This file is generated by the "auto_mkindex" command
# and sourced to set up indexing information for one or
# more commands. Typically each line is a command that
# sets an element in the auto_index array, where the
# element name is the name of a command and the value is
# a script that loads the command.
set auto_index(::Toaster) "source $dir/Toaster.itcl"
set auto_index(::SmartToaster) "source $dir/SmartToaster.itcl"
The auto_mkindex command is used to automatically generate "tclIndex" files.
The auto-loader must be made aware of this directory by appending the directory name to
the "auto_path" variable. When this is in place, widgets will be auto-loaded as needed
when used in an application.
C PROCEDURES
C procedures can be integrated into an [incr Tcl] widget definition to implement methods,
procs, and the "config" code for public variables. Any body that starts with "@" is
treated as the symbolic name for a C procedure.
Symbolic names are established by registering procedures via Itcl_RegisterC(). This is
usually done in the Tcl_AppInit() procedure, which is automatically called when the
interpreter starts up. In the following example, the procedure My_FooCmd() is registered
with the symbolic name "foo". This procedure can be referenced in the body command as
"@foo".
int
Tcl_AppInit(interp)
Tcl_Interp *interp; /* Interpreter for application. */
{
if (Itcl_Init(interp) == TCL_ERROR) {
return TCL_ERROR;
}
if (Itcl_RegisterC(interp, "foo", My_FooCmd) != TCL_OK) {
return TCL_ERROR;
}
}
C procedures are implemented just like ordinary Tcl commands. See the CrtCommand man page
for details. Within the procedure, widget data members can be accessed like ordinary
variables using Tcl_SetVar(), Tcl_GetVar(), Tcl_TraceVar(), etc. Widget methods and procs
can be executed like ordinary commands using Tcl_Eval(). [incr Tcl] makes this possible
by automatically setting up the context before executing the C procedure.
This scheme provides a natural migration path for code development. Widgets can be
developed quickly using Tcl code to implement the bodies. An entire application can be
built and tested. When necessary, individual bodies can be implemented with C code to
improve performance.
KEYWORDS
widget, object, object-oriented