itk User Commands - Archetype






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 applications.





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 component widget
     must be registered with the Archetype base class  using  the
     "itk_component   add"   method.    When   the  component  is
     registered, its configuration options  are  integrated  into
     the  composite  option list.  Configuring a composite option
     like "-background" causes all of the internal 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.
          In this case, option refers to a  composite  configura-
          tion option for the mega-widget.  Individual components
          integrate their own configuration options onto the com-
          posite   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  accessi-
          ble in the current scope.  The symbolic name for a com-
          ponent is established when  it  is  registered  by  the
          "itk_component  add" method.  Note that component widg-
          ets obey any public/protected/private  access  restric-
          tion 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  arguments
          are  invoked as a method on the component with the sym-
          bolic name name.  This provides a well-defined  way  of
          accessing   internal   components  without  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  pathName
          (see  Tk_ConfigureInfo for information on the format of
          this list).  If option is specified with no value, then
          the  command  returns  a  list describing the one named
          option (this list will be identical to the  correspond-
          ing  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 configura-
          tion  options  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.



PROTECTED METHODS

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

     itk_component add name createCmds ?optionCmds?
          Creates a component widget by executing the  createCmds
          argument  and registers the new component with the sym-
          bolic name name.  The createCmds code can  contain  any
          number  of commands, 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 com-
          mands:

          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 com-
               ponent.  Options like "-background" and  "-cursor"
               are commonly found on the keep list.

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

          usual ?tag?
               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 registered 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 accessible  as  a
          component  of the mega-widget.  Also, any options asso-
          ciated with the component are removed from  the  compo-
          site option list.

          Note that you can destroy a component using the destroy
          command, just as you would destroy any Tk widget.  Com-
          ponents  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  com-
          posite  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  override
          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
                  }
              }



     itk_option add optName ?optName optName ...?
          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 className.  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
             }
         }




?config?

     itk_option  define  switchName  resourceName  resourceClass  init
          This  command is used at the level of the class defini-
          tion to define a synthetic mega-widget option.   Within
          the  configure  and cget methods, this option is refer-
          enced by switchName, which must start with a "-"  sign.
          It  can  also be modified by setting values for resour-
          ceName and resourceClass in the X11 resource  database.
          The  init value string is used as a last resort to ini-
          tialize 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  exe-
          cuted whenever the option is modified via the configure
          method.  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  stan-
          dard  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" com-
          mand.

          Options are  normally  integrated  into  the  composite
          option  list  when a component widget is first created.
          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 redefin-
          ing 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
                      eval itk_initialize $args
                  }
                  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 following
     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 over-
          ride 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