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