Provided by: tcl-itcl4-doc_4.1.2-1_all bug

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