Страницы справочника OS X

Эта страница руководства для  версии 10.9 Mac OS X

Читать страницы руководства

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



____________________________________________________________________________________________________________

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_com-ponent "itk_component
       ponent 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. megawidget.
       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 configuration option for the mega-widget.  Individ-ual Individual
              ual components 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  registered  by  the
              "itk_component  add"  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 compo-nent component
              nent with the symbolic name name.  This provides a well-defined way of accessing internal com-ponents components
              ponents  without relying on specific window path names, which are really details of the imple-mentation. implementation.
              mentation.

       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 informa-tion information
              tion 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 corresponding
              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 configuration options for the mega-widget.  Indi-vidual Individual
              vidual  components 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 ?-protected? ?-private? ?--? name createCmds ?optionCmds?
              Creates a component widget by executing the createCmds argument and registers the  new  compo-nent component
              nent with the symbolic name name.  The -protected and -private options can be used to keep the
              component hidden 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 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 con-tain contain
              tain 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 previ-ous previous
                     ous 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 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-wid-get. mega-widget.
              get.  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 bot-tom bottom
              tom 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:
              itcl::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 cre-ated. created.
       ated.  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:
              itcl::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 definition 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
              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 standard output.  Note that this
              synthetic option is integrated with the rest of the "-background" options that have been  kept
              from component widgets:
              itcl::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  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:
              itcl::class Base {
                  inherit itk::Widget
                  constructor {args} {
                      eval itk_initialize $args
                  }

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

              itcl::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 fragments 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 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



itk                                                  3.0                                        Archetype(n)