1Archetype(n)                       [incr Tk]                      Archetype(n)
2
3
4
5______________________________________________________________________________
6

NAME

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

INHERITANCE

11       none
12

WIDGET-SPECIFIC OPTIONS

14       Name:           clientData
15       Class:          ClientData
16       Command-Line Switch:           -clientdata
17
18              This  does  not  affect  the widget operation in any way.  It is
19              simply a hook that clients can use to store a bit of  data  with
20              each widget.  This can come in handy when using widgets to build
21              applications.
22_________________________________________________________________
23
24

DESCRIPTION

26       The Archetype class is the basis for all  [incr Tk]  mega-widgets.   It
27       keeps  track of component widgets and provides methods like "configure"
28       and "cget" that are used to access the composite configuration options.
29       Each  component widget must be registered with the Archetype base class
30       using the "itk_component add" method.  When  the  component  is  regis‐
31       tered,  its  configuration  options  are  integrated into the composite
32       option list.  Configuring a composite option like "-background"  causes
33       all of the internal components to change their background color.
34
35       It  is  not used as a widget by itself, but is used as a base class for
36       more  specialized  widgets.   The  Widget  base  class  inherits   from
37       Archetype,  and  adds a Tk frame which acts as the "hull" for the mega-
38       widget.  The Toplevel base class inherits from Archetype, but adds a Tk
39       toplevel which acts as the "hull".
40
41       Each  derived  class  must  invoke the itk_initialize method within its
42       constructor, so that all options are properly integrated  and  initial‐
43       ized in the composite list.
44
45
46

PUBLIC METHODS

48       The  following  methods are provided to support the public interface of
49       the mega-widget.
50
51       pathName cget option
52              Returns the current value of the configuration option  given  by
53              option.
54
55              In  this case, option refers to a composite configuration option
56              for the mega-widget.  Individual components integrate their  own
57              configuration options onto the composite list when they are reg‐
58              istered by the "itk_component add" method.
59
60       pathName component ?name? ?command arg arg ...?
61              Used to query or access component widgets within a  mega-widget.
62              With  no  arguments,  this  returns a list of symbolic names for
63              component widgets that are accessible in the current scope.  The
64              symbolic  name  for a component is established when it is regis‐
65              tered by the "itk_component add" method.   Note  that  component
66              widgets  obey  any  public/protected/private  access restriction
67              that is in force when the component is created.
68
69              If a symbolic name is specified, this method returns the  window
70              path name for that component.
71
72              Otherwise,  the  command  and  any  remaining  arg arguments are
73              invoked as a method on the  component  with  the  symbolic  name
74              name.   This  provides  a well-defined way of accessing internal
75              components without relying on specific window path names,  which
76              are really details of the implementation.
77
78       pathName configure ?option? ?value option value ...?
79              Query  or modify the configuration options of the widget.  If no
80              option is specified, returns a list describing all of the avail‐
81              able  options for pathName (see Tk_ConfigureInfo for information
82              on the format of this list).  If option  is  specified  with  no
83              value,  then the command returns a list describing the one named
84              option (this list will be identical to the corresponding sublist
85              of  the  value  returned  if no option is specified).  If one or
86              more option-value pairs are specified, then the command modifies
87              the  given widget option(s) to have the given value(s);  in this
88              case the command returns an empty string.
89
90              In this case,  the  options  refer  to  composite  configuration
91              options  for  the  mega-widget.  Individual components integrate
92              their own configuration options onto  the  composite  list  when
93              they are registered by the "itk_component add" method.
94
95

PROTECTED METHODS

97       The following methods are used in derived classes as part of the imple‐
98       mentation for a mega-widget.
99
100       itk_component add ?-protected? ?-private? ?--? name createCmds ?option‐
101       Cmds?
102              Creates  a component widget by executing the createCmds argument
103              and registers the new component with  the  symbolic  name  name.
104              The -protected and -private options can be used to keep the com‐
105              ponent hidden from the outside world.  These options have a sim‐
106              ilar  effect  on component visibility as they have on class mem‐
107              bers.
108
109              The createCmds code can contain any number of commands,  but  it
110              must return the window path name for the new component widget.
111
112              The  optionCmds  script  contains commands that describe how the
113              configuration options for the new component should be integrated
114              into the composite list for the mega-widget.  It can contain any
115              of the following commands:
116
117              ignore option ?option option ...?
118                     Removes one or more configuration options from  the  com‐
119                     posite  list.  All options are ignored by default, so the
120                     ignore command is only used to negate  the  effect  of  a
121                     previous  keep  or  rename  command.  This is useful, for
122                     example, when the some of the options added by the  usual
123                     command  should  not apply to a particular component, and
124                     need to be ignored.
125
126              keep option ?option option ...?
127                     Integrates one or more  configuration  options  into  the
128                     composite  list, keeping the name the same.  Whenever the
129                     mega-widget option is configured, the new value  is  also
130                     applied  to  the current component.  Options like "-back‐
131                     ground" and "-cursor" are  commonly  found  on  the  keep
132                     list.
133
134              rename option switchName resourceName resourceClass
135                     Integrates  the  configuration  option into the composite
136                     list with a different name.  The option  will  be  called
137                     switchName  on the composite list.  It will also be modi‐
138                     fied by setting values for resourceName and resourceClass
139                     in the X11 resource database.  The "-highlightbackground"
140                     option is commonly renamed to "-background", so that when
141                     the mega-widget background changes, the background of the
142                     focus ring will change as well.
143
144              usual ?tag?
145                     Finds the usual option-handling commands for  the  speci‐
146                     fied tag name and executes them.  If the tag is not spec‐
147                     ified, then the widget class name  is  used  as  the  tag
148                     name.   The  "usual"  option-handling commands are regis‐
149                     tered via the usual command.
150
151       If the optionCmds script is not specified,  the  usual  option-handling
152       commands  associated with the class of the component widget are used by
153       default.
154
155
156       itk_component delete name ?name name ...?
157              Removes the component widget with the symbolic  name  name  from
158              the  mega-widget.  The component widget will still exist, but it
159              will no longer be accessible as a component of the  mega-widget.
160              Also, any options associated with the component are removed from
161              the composite option list.
162
163              Note that you can destroy a component using the destroy command,
164              just  as  you would destroy any Tk widget.  Components automati‐
165              cally detach  themselves  from  their  mega-widget  parent  when
166              destroyed, so "itk_component delete" is rarely used.
167
168
169       itk_initialize ?option value option value...?
170              This  method  must  be  invoked  within the constructor for each
171              class in a  mega-widget  hierarchy.   It  makes  sure  that  all
172              options  are properly integrated into the composite option list,
173              and synchronizes all components to the  initial  option  values.
174              It  is usually invoked near the bottom of the constructor, after
175              all component widgets have been added.
176
177              If any option/value pairs are specified, they override  settings
178              determined from the X11 resource database.  The arguments to the
179              constructor are usually passed along to this method as follows:
180              itcl::class MyWidget {
181                  inherit Widget
182
183                  constructor {args} {
184                      .
185                      .
186                      .
187                      eval itk_initialize $args
188                  }
189              }
190
191
192       itk_option add optName ?optName optName ...?
193              Adds one or more options to the  composite  option  list  for  a
194              mega-widget.  Here, optName can have one of the following forms:
195
196              component.option
197                     Accesses an option belonging to a component with the sym‐
198                     bolic name component.  The option name is specified with‐
199                     out a leading "-" sign.
200
201              className::option
202                     Accesses  an  option  defined  by the "itk_option define"
203                     command in class className.  The option name is specified
204                     without a leading "-" sign.
205
206       Options  are  normally integrated into the composite option list when a
207       component widget is first created.  This method  can  be  used  to  add
208       options  at  a  later  time.  For example, the Widget and Toplevel base
209       classes keep only the bare minimum options for their "hull"  component:
210       -background  and  -cursor.  A derived class can override this decision,
211       and add options that control the border  of  the  "hull"  component  as
212       well:
213              itcl::class MyWidget {
214                  inherit Widget
215
216                  constructor {args} {
217                      itk_option add hull.borderwidth hull.relief
218
219                      itk_component add label {
220                          label $itk_interior.l1 -text "Hello World!"
221                      }
222                      pack $itk_component(label)
223
224                      eval itk_initialize $args
225                  }
226              }
227
228
229       itk_option define switchName resourceName resourceClass init ?config?
230              This  command  is  used  at the level of the class definition to
231              define a synthetic mega-widget option.  Within the configure and
232              cget  methods,  this  option  is referenced by switchName, which
233              must start with a "-" sign.  It can also be modified by  setting
234              values  for  resourceName  and resourceClass in the X11 resource
235              database.  The init value string is used as  a  last  resort  to
236              initialize  the  option  if  no  other value can be used from an
237              existing option, or queried from the X11 resource database.   If
238              any config code is specified, it is executed whenever the option
239              is modified via the configure method.  The config code can  also
240              be  specified outside of the class definition via the configbody
241              command.
242
243              In the following example, a synthetic  "-background"  option  is
244              added to the class, so that whenever the background changes, the
245              new value is reported to standard output.  Note that  this  syn‐
246              thetic  option  is integrated with the rest of the "-background"
247              options that have been kept from component widgets:
248              itcl::class MyWidget {
249                  inherit Widget
250                  constructor {args} {
251                      itk_component add label {
252                          label $itk_interior.l1 -text "Hello World!"
253                      }
254                      pack $itk_component(label)
255
256                      eval itk_initialize $args
257                  }
258                  itk_option define -background background Background #d9d9d9 {
259                      puts "new background: $itk_option(-background)"
260                  }
261              }
262
263
264       itk_option remove optName ?optName optName ...?
265              Removes one or more options from the composite option list for a
266              mega-widget.   Here, optName can have one of the forms described
267              above for the "itk_option add" command.
268
269              Options are normally integrated into the composite  option  list
270              when  a  component  widget is first created.  This method can be
271              used to remove options at a later time.  For example, a  derived
272              class can override an option defined in a base class by removing
273              and redefining the option:
274              itcl::class Base {
275                  inherit itk::Widget
276                  constructor {args} {
277                      eval itk_initialize $args
278                  }
279
280                  itk_option define -foo foo Foo "" {
281                      puts "Base: $itk_option(-foo)"
282                  }
283              }
284
285              itcl::class Derived {
286                  inherit Base
287
288                  constructor {args} {
289                      itk_option remove Base::foo
290                      eval itk_initialize $args
291                  }
292                  itk_option define -foo foo Foo "" {
293                      puts "Derived: $itk_option(-foo)"
294                  }
295              }
296       Without the "itk_option remove" command, the code fragments for both of
297       the  "-foo"  options  would  be executed each time the composite "-foo"
298       option is configured.  In the example above, the  Base::foo  option  is
299       suppressed  in  all  Derived  class  widgets,  so only the Derived::foo
300       option remains.
301
302

PROTECTED VARIABLES

304       Derived classes can find useful information in the following  protected
305       variables.
306
307       itk_component(name)
308              The  "itk_component" array returns the real window path name for
309              a component widget with the symbolic name name.  The same infor‐
310              mation  can be queried using the component method, but accessing
311              this array is faster and more convenient.
312
313       itk_interior
314              This variable contains the name of the window  that  acts  as  a
315              parent  for  internal components.  It is initialized to the name
316              of the "hull" component provided  by  the  Widget  and  Toplevel
317              classes.   Derived  classes  can override the initial setting to
318              point to another interior window to be used for  further-derived
319              classes.
320
321       itk_option(option)
322              The  "itk_option" array returns the current option value for the
323              composite widget option named option.   Here,  the  option  name
324              should  include a leading "-" sign.  The same information can be
325              queried using the cget  method,  but  accessing  this  array  is
326              faster and more convenient.
327
328

KEYWORDS

330       itk, Widget, Toplevel, mega-widget
331
332
333
334itk                                   3.0                         Archetype(n)
Impressum