Archetype man page on Darwin

Man page or keyword search:  
man Server   23457 pages
apropos Keyword Search (all sections)
Output format
Darwin logo
[printable version]

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_component add" 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  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  initial‐
       ized 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.  Individual components integrate their  own
	      configuration options onto the composite list when they are reg‐
	      istered 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 regis‐
	      tered 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  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 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 avail‐
	      able  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 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 "itk_component add" method.

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

       itk_component add ?-protected? ?-private? ?--? name createCmds ?option‐
       Cmds?
	      Creates  a component widget by executing the createCmds argument
	      and registers the new component with  the	 symbolic  name	 name.
	      The -protected and -private 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:

	      ignore option ?option option ...?
		     Removes one or more configuration options from  the  com‐
		     posite  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 "-back‐
		     ground" 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 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.

	      usual ?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 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 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 automati‐
	      cally 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 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 sym‐
		     bolic name component.  The option name is specified with‐
		     out 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:
	      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  syn‐
	      thetic  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 infor‐
	      mation  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)
[top]

List of man pages available for Darwin

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net