NAME

       Archetype - base class for all [incr Tk] mega-widgets


INHERITANCE

       none


WIDGET-SPECIFIC OPTIONS

       Name:           clientData
       Class:          ClientData
       Command-Line Switch:           -clientdata

              This  does  not  affect the widget operation in any
              way.  It is simply a hook that clients can  use  to
              store  a  bit  of  data with each widget.  This can
              come in handy when using widgets to build  applica­
              tions.
_________________________________________________________________


DESCRIPTION

       The  Archetype  class is the basis for all [incr Tk] mega-
       widgets.  It keeps track of component widgets and provides
       methods  like  "configure"  and  "cget"  that  are used to
       access the composite configuration options.   Each  compo­
       nent  widget  must  be  registered with the Archetype base
       class using the "itk_component add" method.  When the com­
       ponent  is registered, its configuration options are inte­
       grated into the composite option list.  Configuring a com­
       posite  option like "-background" causes all of the inter­
       nal components to change their background color.

       It is not used as a widget by itself, but  is  used  as  a
       base  class for more specialized widgets.  The Widget base
       class inherits from Archetype, and adds a Tk  frame  which
       acts as the "hull" for the mega-widget.  The Toplevel base
       class inherits from Archetype,  but  adds  a  Tk  toplevel
       which acts as the "hull".

       Each  derived  class must invoke the itk_initialize method
       within its constructor, so that all options  are  properly
       integrated and initialized in the composite list.


PUBLIC METHODS

       The  following  methods are provided to support the public
       interface of the mega-widget.

       pathName cget option
              Returns the  current  value  of  the  configuration
              option given by option.

              ration option for the mega-widget.  Individual com­
              ponents  integrate  their own configuration options
              onto the composite list when they are registered by
              the "itk_component add" method.

       pathName component ?name? ?command arg arg ...?
              Used  to query or access component widgets within a
              mega-widget.  With no  arguments,  this  returns  a
              list  of  symbolic names for component widgets that
              are accessible in the current scope.  The  symbolic
              name for a component is established when it is reg­
              istered by the "itk_component  add"  method.   Note
              that   component   widgets   obey  any  public/pro­
              tected/private access restriction that is in  force
              when the component is created.

              If  a  symbolic  name  is  specified,  this  method
              returns the window path name for that component.

              Otherwise, the command and any remaining arg  argu­
              ments are invoked as a method on the component with
              the symbolic name  name.   This  provides  a  well-
              defined  way of accessing internal components with­
              out relying on specific window  path  names,  which
              are really details of the implementation.

       pathName configure ?option? ?value option value ...?
              Query  or  modify  the configuration options of the
              widget.  If no option is specified, returns a  list
              describing  all  of the available options for path­
              Name (see Tk_ConfigureInfo for information  on  the
              format  of this list).  If option is specified with
              no value, then the command returns a list  describ­
              ing the one named option (this list will be identi­
              cal to  the  corresponding  sublist  of  the  value
              returned  if  no  option  is specified).  If one or
              more option-value pairs  are  specified,  then  the
              command modifies the given widget option(s) to have
              the given  value(s);   in  this  case  the  command
              returns an empty string.

              In  this  case, the options refer to composite con­
              figuration options for the mega-widget.  Individual
              components   integrate   their   own  configuration
              options onto the composite list when they are  reg­
              istered by the "itk_component add" method.


PROTECTED METHODS

       The  following methods are used in derived classes as part
       of the implementation for a mega-widget.

              createCmds ?optionCmds?
              Creates a component widget by executing the create­
              Cmds  argument and registers the new component with
              the symbolic name name.  The -protected  and  -pri­
              vate options can be used to keep the component hid­
              den from the outside world.  These options  have  a
              similar effect on component visibility as they have
              on class members.

              The createCmds code can contain any number of  com­
              mands,  but it must return the window path name for
              the new component widget.

              The  optionCmds  script  contains   commands   that
              describe  how the configuration options for the new
              component should be integrated into  the  composite
              list  for  the  mega-widget.  It can contain any of
              the following commands:

              ignore option ?option option ...?
                     Removes one or  more  configuration  options
                     from  the  composite  list.  All options are
                     ignored by default, so the ignore command is
                     only used to negate the effect of a previous
                     keep or rename command.  This is useful, for
                     example,  when the some of the options added
                     by the usual command should not apply  to  a
                     particular   component,   and   need  to  be
                     ignored.

              keep option ?option option ...?
                     Integrates one or more configuration options
                     into  the  composite  list, keeping the name
                     the same.  Whenever the  mega-widget  option
                     is configured, the new value is also applied
                     to  the  current  component.   Options  like
                     "-background"  and  "-cursor"  are  commonly
                     found on the keep list.

              rename option switchName resourceName resourceClass
                     Integrates the configuration option into the
                     composite list with a different  name.   The
                     option will be called switchName on the com­
                     posite list.  It will also  be  modified  by
                     setting    values   for   resourceName   and
                     resourceClass in the X11 resource  database.
                     The  "-highlightbackground"  option  is com­
                     monly renamed to "-background", so that when
                     the   mega-widget  background  changes,  the
                     background of the focus ring will change  as
                     well.

                     Finds the usual option-handling commands for
                     the specified tag name  and  executes  them.
                     If the tag is not specified, then the widget
                     class name is used as  the  tag  name.   The
                     "usual"  option-handling commands are regis­
                     tered via the usual command.

       If the optionCmds  script  is  not  specified,  the  usual
       option-handling  commands associated with the class of the
       component widget are used by default.

       itk_component delete name ?name name ...?
              Removes the component widget with the symbolic name
              name  from  the  mega-widget.  The component widget
              will still exist, but it will no longer be accessi­
              ble  as  a component of the mega-widget.  Also, any
              options associated with the component  are  removed
              from the composite option list.

              Note  that  you  can  destroy a component using the
              destroy command, just as you would destroy  any  Tk
              widget.  Components automatically detach themselves
              from their mega-widget parent  when  destroyed,  so
              "itk_component delete" is rarely used.

       itk_initialize ?option value option value...?
              This  method must be invoked within the constructor
              for each class  in  a  mega-widget  hierarchy.   It
              makes sure that all options are properly integrated
              into the composite option  list,  and  synchronizes
              all components to the initial option values.  It is
              usually invoked near the bottom of the constructor,
              after all component widgets have been added.

              If any option/value pairs are specified, they over­
              ride settings  determined  from  the  X11  resource
              database.   The  arguments  to  the constructor are
              usually passed along to this method as follows:
              class MyWidget {
                  inherit Widget

                  constructor {args} {
                      .
                      .
                      .
                      eval itk_initialize $args
                  }
              }

              Adds one or more options to  the  composite  option
              list for a mega-widget.  Here, optName can have one
              of the following forms:

              component.option
                     Accesses an option belonging to a  component
                     with   the  symbolic  name  component.   The
                     option name is specified without  a  leading
                     "-" sign.

              className::option
                     Accesses    an   option   defined   by   the
                     "itk_option define" command in class  class­
                     Name.   The option name is specified without
                     a leading "-" sign.

       Options are normally integrated into the composite  option
       list  when  a  component  widget  is  first created.  This
       method can be used to add options at a  later  time.   For
       example,  the  Widget  and Toplevel base classes keep only
       the bare  minimum  options  for  their  "hull"  component:
       -background  and  -cursor.   A  derived class can override
       this decision, and add options that control the border  of
       the "hull" component as well:
              class MyWidget {
                  inherit Widget

                  constructor {args} {
                      itk_option add hull.borderwidth hull.relief

                      itk_component add label {
                          label $itk_interior.l1 -text "Hello World!"
                      }
                      pack $itk_component(label)

                      eval itk_initialize $args
                  }
              }

       itk_option  define  switchName  resourceName
              resourceClass  init ?config?
              This command is used at the level of the class def­
              inition to define a synthetic  mega-widget  option.
              Within  the configure and cget methods, this option
              is referenced by switchName, which must start  with
              a  "-"  sign.   It  can also be modified by setting
              values for resourceName and  resourceClass  in  the
              X11  resource  database.   The init value string is
              used as a last resort to initialize the  option  if
              no other value can be used from an existing option,
              or queried from the X11 resource database.  If  any
              config  code  is specified, it is executed whenever

              The  config  code  can also be specified outside of
              the class definition via the configbody command.

              In the following example, a synthetic "-background"
              option  is added to the class, so that whenever the
              background changes, the new value  is  reported  to
              standard  output.   Note that this synthetic option
              is integrated with the rest  of  the  "-background"
              options that have been kept from component widgets:
              class MyWidget {
                  inherit Widget
                  constructor {args} {
                      itk_component add label {
                          label $itk_interior.l1 -text "Hello World!"
                      }
                      pack $itk_component(label)

                      eval itk_initialize $args
                  }
                  itk_option define -background background Background #d9d9d9 {
                      puts "new background: $itk_option(-background)"
                  }
              }

       itk_option remove optName ?optName optName ...?
              Removes one or  more  options  from  the  composite
              option  list  for a mega-widget.  Here, optName can
              have one of  the  forms  described  above  for  the
              "itk_option add" command.

              Options  are normally integrated into the composite
              option list when a component widget is  first  cre­
              ated.  This method can be used to remove options at
              a later time.  For example,  a  derived  class  can
              override  an  option  defined  in  a  base class by
              removing and redefining the option:
              class Base {
                  inherit Widget
                  constructor {args} {
                      eval itk_initialize $args
                  }

                  itk_option define -foo foo Foo "" {
                      puts "Base: $itk_option(-foo)"
                  }
              }

              class Derived {
                  inherit Base

                  constructor {args} {
                      itk_option remove Base::foo

                  }
                  itk_option define -foo foo Foo "" {
                      puts "Derived: $itk_option(-foo)"
                  }
              }
       Without the "itk_option remove" command,  the  code  frag­
       ments  for  both  of  the "-foo" options would be executed
       each time the composite "-foo" option is  configured.   In
       the  example  above, the Base::foo option is suppressed in
       all Derived class widgets, so only the Derived::foo option
       remains.


PROTECTED VARIABLES

       Derived classes can find useful information in the follow­
       ing protected variables.

       itk_component(name)
              The "itk_component" array returns the  real  window
              path  name for a component widget with the symbolic
              name name.  The same  information  can  be  queried
              using  the  component  method,  but  accessing this
              array is faster and more convenient.

       itk_interior
              This variable contains the name of the window  that
              acts  as  a  parent for internal components.  It is
              initialized to the name  of  the  "hull"  component
              provided   by  the  Widget  and  Toplevel  classes.
              Derived classes can override the initial setting to
              point  to  another  interior  window to be used for
              further-derived classes.

       itk_option(option)
              The "itk_option" array returns the  current  option
              value for the composite widget option named option.
              Here, the option name should include a leading  "-"
              sign.   The  same  information can be queried using
              the cget method, but accessing this array is faster
              and more convenient.


KEYWORDS

       itk, Widget, Toplevel, mega-widget


Man(1) output converted with man2html