Archetype(n) [incr Tk] Archetype(n)

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

IINNHHEERRIITTAANNCCEE
       none

WWIIDDGGEETT-SSPPEECCIIFFIICC OOPPTTIIOONNSS
       Name:           cclliieennttDDaattaa
       Class:          CClliieennttDDaattaa
       Command-Line Switch:           -cclliieennttddaattaa

              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 AArrcchheettyyppee class is the basis for all  [[iinnccrr TTkk]]  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 AArrcchheettyyppee base class
       using the "iittkkccoommppoonneenntt aadddd" method.  When  the  component  is  regis-
       tered,  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  WWiiddggeett  base  class  inherits   from
       AArrcchheettyyppee,  and  adds a Tk frame which acts as the "hull" for the mega-
       widget.  The TToopplleevveell base class inherits from AArrcchheettyyppee, but adds a Tk
       toplevel which acts as the "hull".

       Each  derived  class  must  invoke the iittkkiinniittiiaalliizzee method within its
       constructor, so that all options are properly integrated  and  initial-
       ized in the composite list.



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

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

              In  this case, option refers to a composite configuration option
              for the mega-widget.  Individual components integrate their  own
              configuration options onto the composite list when they are reg-
              istered by the "iittkkccoommppoonneenntt aadddd" method.

       pathName ccoommppoonneenntt ?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 regis-
              tered by the "iittkkccoommppoonneenntt aadddd" method.   Note  that  component
              widgets  obey  any  public/protected/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 arguments are
              invoked as a method on the  component  with  the  symbolic  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 ccoonnffiigguurree ?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 avail-
              able  options for pathName (see TTkkCCoonnffiigguurreeIInnffoo 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 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  configuration
              options  for  the  mega-widget.  Individual components integrate
              their own configuration options onto  the  composite  list  when
              they are registered by the "iittkkccoommppoonneenntt aadddd" method.


PPRROOTTEECCTTEEDD MMEETTHHOODDSS
       The following methods are used in derived classes as part of the imple-
       mentation for a mega-widget.

       iittkkccoommppoonneenntt aadddd ?-pprrootteecctteedd? ?-pprriivvaattee? ?--? name createCmds ?option-
       Cmds?
              Creates a component widget by executing the createCmds  argument
              and  registers  the  new  component with the symbolic name name.
              The -pprrootteecctteedd and -pprriivvaattee options can be used to keep the com-
              ponent hidden from the outside world.  These options have a sim-
              ilar effect on component visibility as they have on  class  mem-
              bers.

              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 commands:

              iiggnnoorree option ?option option ...?
                     Removes  one  or more configuration options from the com-
                     posite list.  All options are ignored by default, so  the
                     iiggnnoorree  command  is  only  used to negate the effect of a
                     previous kkeeeepp or rreennaammee command.   This  is  useful,  for
                     example,  when the some of the options added by the uussuuaall
                     command should not apply to a particular  component,  and
                     need to be ignored.

              kkeeeepp 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  "-back-
                     ground"  and  "-cursor"  are  commonly  found on the kkeeeepp
                     list.

              rreennaammee option switchName resourceName resourceClass
                     Integrates the configuration option  into  the  composite
                     list  with  a  different name.  The option will be called
                     switchName on the composite list.  It will also be  modi-
                     fied 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.

              uussuuaall ??tag?
                     Finds  the  usual option-handling commands for the speci-
                     fied tag name and executes them.  If the tag is not spec-
                     ified,  then  the  widget  class  name is used as the tag
                     name.  The "usual" option-handling  commands  are  regis-
                     tered via the uussuuaall 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.


       iittkkccoommppoonneenntt ddeelleettee 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 associated with the component are removed from
              the composite option list.

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


       iittkkiinniittiiaalliizzee ??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 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 itkinitialize $args
                  } }


       iittkkooppttiioonn aadddd 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 sym-
                     bolic name component.  The option name is specified with-
                     out a leading "-" sign.

              className::option
                     Accesses an option defined  by  the  "iittkkooppttiioonn  ddeeffiinnee"
                     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  WWiiddggeett  and  TToopplleevveell  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} {
               itkoption add hull.borderwidth hull.relief

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

               eval itkinitialize $args
           } }


       iittkkooppttiioonn ddeeffiinnee switchName resourceName resourceClass init ?config?
              This command is used at the level of  the  class  definition  to
              define a synthetic mega-widget option.  Within the ccoonnffiigguurree and
              ccggeett 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 option
              is  modified via the ccoonnffiigguurree method.  The config code can also
              be specified outside of the class definition via the  ccoonnffiiggbbooddyy
              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 syn-
              thetic option is integrated with the rest of  the  "-background"
              options that have been kept from component widgets: class MyWid-
              get {
                  inherit Widget
                  constructor {args} {
                      itkcomponent add label {
                          label $itkinterior.l1 -text "Hello World!"
                      }
                      pack $itkcomponent(label)

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


       iittkkooppttiioonn rreemmoovvee 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 "iittkkooppttiioonn aadddd" command.

              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 redefining the option: class Base {
                  inherit Widget
                  constructor {args} {
                      eval itkinitialize $args
                  }

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

              class Derived {
                  inherit Base

                  constructor {args} {
                      itkoption remove Base::foo
                      eval itkinitialize $args
                  }
                  itkoption define -foo foo Foo "" {
                      puts "Derived: $itkoption(-foo)"
                  }  } Without the "iittkkooppttiioonn rreemmoovvee" 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.


PPRROOTTEECCTTEEDD VVAARRIIAABBLLEESS
       Derived  classes can find useful information in the following protected
       variables.

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

       itkinterior
              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 WWiiddggeett and TToopplleevveell
              classes.  Derived classes can override the  initial  setting  to
              point  to another interior window to be used for further-derived
              classes.

       itkoption(option)
              The "itkoption" 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  ccggeett  method,  but  accessing this array is
              faster and more convenient.


KKEEYYWWOORRDDSS
       itk, Widget, Toplevel, mega-widget



itk                                   3.0                         Archetype(n)