1Archetype(n) [incr Tk] Archetype(n)
2______________________________________________________________________________
6
8 Archetype - base class for all [incr Tk] mega-widgets
9
11 none
12
14 Name: clientData
15 Class: ClientData
16 Command-Line Switch: -clientdata
17 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
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 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 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
48 The following methods are provided to support the public interface of
49 the mega-widget.
50 pathName cget option
52 Returns the current value of the configuration option given by
53 option.
54 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 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 If a symbolic name is specified, this method returns the window
70 path name for that component.
71 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 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 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
97 The following methods are used in derived classes as part of the imple‐
98 mentation for a mega-widget.
99 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 The createCmds code can contain any number of commands, but it
110 must return the window path name for the new component widget.
111 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 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 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 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 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 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 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 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 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 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 constructor {args} {
184 .
185 .
186 .
187 eval itk_initialize $args
188 }
189 }
190 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 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 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 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 constructor {args} {
217 itk_option add hull.borderwidth hull.relief
218 itk_component add label {
220 label $itk_interior.l1 -text "Hello World!"
221 }
222 pack $itk_component(label)
223 eval itk_initialize $args
225 }
226 }
227 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 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 eval itk_initialize $args
257 }
258 itk_option define -background background Background #d9d9d9 {
259 puts "new background: $itk_option(-background)"
260 }
261 }
262 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 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 itk_option define -foo foo Foo "" {
281 puts "Base: $itk_option(-foo)"
282 }
283 }
284 itcl::class Derived {
286 inherit Base
287 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
304 Derived classes can find useful information in the following protected
305 variables.
306 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 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 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
330 itk, Widget, Toplevel, mega-widget
331itk 3.0 Archetype(n)