Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | |
2 | <html> | |
3 | <head> | |
4 | <meta name="description" content="Pmw - a toolkit for building high-level compound widgets in Python"> | |
5 | <meta name="content" content="python, megawidget, mega widget, compound widget, gui, tkinter"> | |
6 | <title>Pmw.MegaArchetype reference manual</title> | |
7 | </head> | |
8 | ||
9 | <body bgcolor="#ffffff" text="#000000" link="#0000ee" | |
10 | vlink="551a8b" alink="ff0000"> | |
11 | ||
12 | <h1 ALIGN="CENTER">Pmw.MegaArchetype</h1> | |
13 | ||
14 | <dl> | |
15 | <dt> <h3>Name</h3></dt><dd> | |
16 | <p>Pmw.MegaArchetype() - | |
17 | abstract base class for all Pmw megawidgets | |
18 | </p> | |
19 | ||
20 | ||
21 | </dd> | |
22 | <dt> <h3>Description</h3></dt><dd> | |
23 | <p> | |
24 | This class is the basis for all Pmw megawidgets. It provides | |
25 | methods to manage options and component widgets.</p> | |
26 | ||
27 | <p> This class is normally used as a base class for other classes. If | |
28 | the <em>hullClass</em> argument is specified, such as in the <a href="MegaWidget.html">Pmw.MegaWidget</a> | |
29 | and <a href="MegaToplevel.html">Pmw.MegaToplevel</a> classes, a container widget is created to act | |
30 | as the parent of all other component widgets. Classes derived | |
31 | from these sub classes create other component widgets and options | |
32 | to implement megawidgets that can be used in applications. </p> | |
33 | ||
34 | <p> If no <em>hullClass</em> argument is given to the constructor, no | |
35 | container widget is created and only the option configuration | |
36 | functionality is available.</p> | |
37 | ||
38 | <p></p> | |
39 | ||
40 | ||
41 | </dd> | |
42 | <dt> <h3>Components</h3></dt><dd> | |
43 | <p> | |
44 | A megawidget is generally made up of other widgets packed | |
45 | within the megawidget's containing widget. These sub-widgets | |
46 | are called the <em>components</em> of the megawidget and are given | |
47 | logical names for easy reference. The component mechanism | |
48 | allows the user of a megawidget to gain controlled access to | |
49 | some of the internals of the megawidget, for example to call a | |
50 | method of a component or to set a component's configuration | |
51 | options.</p> | |
52 | ||
53 | <p> <strong>Sub components:</strong> If a component is itself a megawidget containing | |
54 | sub-components, then these sub-components can be referred to | |
55 | using the notation <em>component_subcomponent</em>. For example, | |
56 | <a href="ComboBox.html">Pmw.ComboBox</a> has a component named <strong>entryfield</strong> which is an | |
57 | instance of <a href="EntryField.html">Pmw.EntryField</a>, which itself has a Tkinter.Entry | |
58 | component named <strong>entry</strong>. In the context of the combobox, this | |
59 | entry widget can be referred to as <strong>entryfield_entry</strong>.</p> | |
60 | ||
61 | <p> <strong>Component aliases:</strong> Because the sub-component notation may | |
62 | make component names inconveniently long, components and | |
63 | sub-components can be aliased to simpler names. For example, | |
64 | the <strong>entryfield_entry</strong> sub-component of <a href="ComboBox.html">Pmw.ComboBox</a> is aliased | |
65 | to simply <strong>entry</strong>. If there is no conflict in component | |
66 | names, sub-component names are usually aliased to the name of | |
67 | the "leaf" component.</p> | |
68 | ||
69 | <p> <strong>Component groups:</strong> Similar components of a megawidget can be | |
70 | given a <em>group</em> name, which allows all components of a group | |
71 | to be referenced using the one group name. For example, the | |
72 | two arrow components of <a href="Counter.html">Pmw.Counter</a> have a group name of <strong>Arrow</strong>. | |
73 | Also, megawidgets that can create an unlimited number of | |
74 | similar components, such as <a href="ButtonBox.html">Pmw.ButtonBox</a>, create each of these | |
75 | components with the same group name. By convention, group | |
76 | names begin with a capital letter.</p> | |
77 | <p> </p> | |
78 | ||
79 | ||
80 | ||
81 | </dd> | |
82 | <dt> <h3>Options</h3></dt><dd> | |
83 | <p> | |
84 | A megawidget defines options which allow the megawidget user | |
85 | to modify the appearance and behaviour of the megawidget. | |
86 | Using the same technique as Tkinter widgets, the values of | |
87 | megawidget options may be set in calls to the constructor and | |
88 | to <code>configure()</code> and the values may be queried by calls to | |
89 | <code>cget()</code> and <code>configure()</code>. Like Tkinter widgets, megawidget | |
90 | options are initialised with default values. Also, if the | |
91 | <em>useTkOptionDb</em> option to <code>Pmw.initialise()</code> has been set, | |
92 | then the Tk option database will be queried to get the initial | |
93 | values. Strings found in the option database are converted | |
94 | to python objects (integer, float, tuple, dictionary, etc) | |
95 | using a restricted <code>eval()</code> call. Anything that is not accepted by | |
96 | <code>eval()</code> is treated as a string.</p> | |
97 | ||
98 | <p> <strong>Inherited options:</strong> As well as the options defined in a class, | |
99 | a derived class inherits all options of its base classes. The | |
100 | default value of an option defined by a base class may be | |
101 | modified by the derived class.</p> | |
102 | ||
103 | <p> <strong>Initialisation options:</strong> Some megawidget options can only be | |
104 | set in the call to the constructor. These are called | |
105 | <em>initialisation options</em>. Unlike normal configuration | |
106 | options, they cannot be set by calling the <code>configure()</code> | |
107 | method.</p> | |
108 | ||
109 | <p> <strong>Component options:</strong> Options of the components of a megawidget | |
110 | can be referred to using the notation <em>component_option</em>. | |
111 | Like the megawidget options, component options can be used in | |
112 | calls to the constructor and to the <code>cget()</code> and <code>configure()</code> | |
113 | methods. For example, the <strong>state</strong> option of the Tkinter.Text | |
114 | <strong>text</strong> component of <a href="ScrolledText.html">Pmw.ScrolledText</a> may be set by calling</p> | |
115 | <dl><dd><pre> widget.configure(text_state = 'disabled')</pre></dd></dl> | |
116 | ||
117 | ||
118 | <p> Sub-components, component aliases and component groups may | |
119 | also be combined with options. For example, the <strong>state</strong> | |
120 | option of the <strong>entryfield_entry</strong> component of <a href="ComboBox.html">Pmw.ComboBox</a> | |
121 | may be set by calling</p> | |
122 | <dl><dd><pre> combobox.configure(entryfield_entry_state = 'normal')</pre></dd></dl> | |
123 | ||
124 | ||
125 | <p> Since it has an alias, it is more convenient to use the | |
126 | equivalent form</p> | |
127 | <dl><dd><pre> combobox.configure(entry_state = 'normal')</pre></dd></dl> | |
128 | ||
129 | ||
130 | <p> Also, the background color of both arrows of <a href="Counter.html">Pmw.Counter</a> | |
131 | can be set using the <strong>Arrow</strong> component group.</p> | |
132 | <dl><dd><pre> counter.configure(Arrow_background = 'aliceblue')</pre></dd></dl> | |
133 | ||
134 | ||
135 | <p> </p> | |
136 | ||
137 | ||
138 | </dd> | |
139 | <dt> <h3>The pyclass component option</h3></dt><dd> | |
140 | <p> | |
141 | The <strong>pyclass</strong> component option is a special notation that can | |
142 | be used to specify a non-default python class for a component. | |
143 | This can only be used when the component is being constructed. | |
144 | For a component created during the construction of its parent | |
145 | megawidget, this option must be given to the constructor in | |
146 | the form <em>component_pyclass</em>. For example, to change the | |
147 | python class of the <strong>text</strong> sub-component of <a href="TextDialog.html">Pmw.TextDialog</a> | |
148 | to a class <strong>FontText.Text</strong></p> | |
149 | <dl><dd><pre> dialog = Pmw.TextDialog(text_pyclass = FontText.Text)</pre></dd></dl> | |
150 | ||
151 | ||
152 | <p> For components created after the construction of the parent | |
153 | megawidget, the <strong>pyclass</strong> option must be passed into the | |
154 | method which constructs the component. For example, to set | |
155 | the python class of a button in <a href="ButtonBox.html">Pmw.ButtonBox</a> to a class | |
156 | <strong>MyButton</strong>:</p> | |
157 | <dl><dd><pre> buttonBox.add('special', pyclass = MyButton)</pre></dd></dl> | |
158 | ||
159 | ||
160 | <p> The new python class of the component must support all methods | |
161 | and options that are used by the megawidget when operating on | |
162 | the component. The exact interface required for each | |
163 | component is not documented. You will have to examine the Pmw | |
164 | source code. However, any class derived from the default | |
165 | class of a component can be used as the new class of the | |
166 | component, as long as all of the original methods and options | |
167 | are still supported. For example, any class derived from | |
168 | <strong>Tkinter.Text</strong> can be used as the class of the <strong>text</strong> | |
169 | sub-component of <a href="TextDialog.html">Pmw.TextDialog</a>. </p> | |
170 | ||
171 | <p> The <strong>pyclass</strong> component option should not be confused with the | |
172 | <strong>class</strong> option that some of the Tk widgets support. The | |
173 | <strong>class</strong> option sets the Tk option database class for the | |
174 | widget and is used by Tk to query the database for the default | |
175 | values of the widget's other options. The name <strong>pyclass</strong> was | |
176 | chosen so that it did not conflict with any known Tk options.</p> | |
177 | ||
178 | <p> </p> | |
179 | ||
180 | ||
181 | </dd> | |
182 | <dt> <h3>Construction</h3></dt><dd> | |
183 | <p> | |
184 | The constructors of classes derived from this class all accept | |
185 | the same arguments: one positional argument and any number of | |
186 | keyword arguments. The positional argument defaults to <strong>None</strong> | |
187 | (meaning the root window) and specifies the widget to use as | |
188 | the parent when creating the | |
189 | megawidget's <strong>hull</strong> component. The keyword arguments define | |
190 | initial values for options. The format for the constructors | |
191 | of derived classes is:</p> | |
192 | ||
193 | <dl><dd><pre> def __init__(self, parent = None, **kw):</pre></dd></dl> | |
194 | <p> </p> | |
195 | ||
196 | ||
197 | ||
198 | </dd> | |
199 | <a name=methods></a> | |
200 | <dt> <h3>Methods</h3></dt><dd> | |
201 | <a name=method.addoptions></a> | |
202 | <dl><dt> <strong>addoptions</strong>(<em>optionDefs</em>)</dt><dd> | |
203 | Add additional options for this megawidget. The <em>optionDefs</em> | |
204 | argument is treated in the same way as for the <code>defineoptions()</code> | |
205 | method.</p> | |
206 | <p> This method is for use by derived classes. It is only used if a | |
207 | megawidget should conditionally define some options, perhaps | |
208 | depending on the value of other options. Usually, megawidgets | |
209 | unconditionally define all their options in the call to | |
210 | <code>defineoptions()</code> and do not need to use <code>addoptions()</code>. This | |
211 | method must be called after the call to <code>defineoptions()</code> and | |
212 | before the call to <code>initialiseoptions()</code>.</p> | |
213 | ||
214 | ||
215 | ||
216 | </dd></dl> | |
217 | <a name=method.cget></a> | |
218 | <dl><dt> <strong>cget</strong>(<em>option</em>)</dt><dd> | |
219 | Return the current value of <em>option</em> (which should be in the | |
220 | format described in the <strong>Options</strong> section). This method is also | |
221 | available using object subscripting, for example | |
222 | <code>myWidget['font']</code>. Unlike Tkinter's cget(), which always returns | |
223 | a string, this method returns the same value and type as used when | |
224 | the option was set (except where <em>option</em> is a component option | |
225 | and the component is a Tkinter widget, in which case it returns | |
226 | the string returned by Tcl/Tk).</p> | |
227 | ||
228 | ||
229 | </dd></dl> | |
230 | <a name=method.component></a> | |
231 | <dl><dt> <strong>component</strong>(<em>name</em>)</dt><dd> | |
232 | Return the component widget whose name is <em>name</em>. This | |
233 | allows the user of a megawidget to access and configure component | |
234 | widgets directly.</p> | |
235 | ||
236 | ||
237 | </dd></dl> | |
238 | <a name=method.componentaliases></a> | |
239 | <dl><dt> <strong>componentaliases</strong>()</dt><dd> | |
240 | Return the list of aliases for components. Each item in the list | |
241 | is a tuple whose first item is the name of the alias and whose | |
242 | second item is the name of the component or sub-component it | |
243 | refers to.</p> | |
244 | ||
245 | ||
246 | </dd></dl> | |
247 | <a name=method.componentgroup></a> | |
248 | <dl><dt> <strong>componentgroup</strong>(<em>name</em>)</dt><dd> | |
249 | Return the group of the component whose name is <em>name</em> or <strong>None</strong> | |
250 | if it does not have a group.</p> | |
251 | ||
252 | ||
253 | </dd></dl> | |
254 | <a name=method.components></a> | |
255 | <dl><dt> <strong>components</strong>()</dt><dd> | |
256 | Return a sorted list of names of the components of this | |
257 | megawidget.</p> | |
258 | ||
259 | ||
260 | </dd></dl> | |
261 | <a name=method.configure></a> | |
262 | <dl><dt> <strong>configure</strong>(<em>option</em> = <strong>None</strong>, **<em>kw</em>)</dt><dd> | |
263 | Query or configure the megawidget options.</p> | |
264 | <p> If no arguments are given, return a tuple consisting of all | |
265 | megawidget options and values, each as a 5-element tuple | |
266 | (<em>name</em>, <em>resourceName</em>, <em>resourceClass</em>, <em>default</em>, <em>value</em>). | |
267 | This is in the same format as the value returned by the standard | |
268 | Tkinter <code>configure()</code> method, except that the resource name is | |
269 | always the same as the option name and the resource class is the | |
270 | option name with the first letter capitalised.</p> | |
271 | ||
272 | <p> If one argument is given, return the 5 element tuple for <em>option</em>.</p> | |
273 | ||
274 | <p> Otherwise, set the configuration options specified by the keyword | |
275 | arguments. Each key should be in the format described in the | |
276 | <strong>Options</strong> section.</p> | |
277 | ||
278 | ||
279 | ||
280 | </dd></dl> | |
281 | <a name=method.createcomponent></a> | |
282 | <dl><dt> <strong>createcomponent</strong>(<em>componentName</em>, <em>componentAliases</em>, <em>componentGroup</em>, <em>widgetClass</em>, *<em>widgetArgs</em>, **<em>kw</em>)</dt><dd> | |
283 | Create a component widget by calling <em>widgetClass</em> with the | |
284 | arguments given by <em>widgetArgs</em> and any keyword arguments. The | |
285 | <em>componentName</em> argument is the name by which the component will | |
286 | be known and must not contain the underscore, <strong>'_'</strong>, character. | |
287 | The <em>componentGroup</em> argument specifies the group of the | |
288 | component. The <em>componentAliases</em> argument is a sequence of | |
289 | 2-element tuples, whose first item is an alias name and whose | |
290 | second item is the name of the component or sub-component it is to | |
291 | refer to.</p> | |
292 | <p> If this method is called during megawidget construction, any | |
293 | component options supplied to the megawidget constructor which | |
294 | refer to this component (by <em>componentName</em> or <em>componentGroup</em>) | |
295 | are added to the <em>kw</em> dictionary before calling <em>widgetClass</em>. If | |
296 | the dictionary contains a <strong>'pyclass'</strong> key, then this item is | |
297 | removed from the dictionary and the value is used instead of | |
298 | <em>widgetClass</em>. For more details see <strong>The pyclass component option</strong> | |
299 | section.</p> | |
300 | ||
301 | <p> This method may be called by derived classes during or after | |
302 | megawidget construction. It returns the instance of the class | |
303 | created.</p> | |
304 | ||
305 | ||
306 | ||
307 | </dd></dl> | |
308 | <a name=method.createlabel></a> | |
309 | <dl><dt> <strong>createlabel</strong>(<em>parent</em>, <em>childCols</em> = <strong>1</strong>, <em>childRows</em> = <strong>1</strong>)</dt><dd> | |
310 | Create a <strong>Tkinter.Label</strong> component named <strong>'label'</strong> in the <em>parent</em> | |
311 | widget. This is a convenience method used by several megawidgets | |
312 | that require an optional label. The widget must have options | |
313 | named <strong>labelpos</strong> and <strong>labelmargin</strong>. If <strong>labelpos</strong> is <strong>None</strong>, no | |
314 | label is created. Otherwise, a label is created and positioned | |
315 | according to the value of <strong>labelpos</strong> and <strong>labelmargin</strong>. The label | |
316 | is added to the parent using the <code>grid()</code> method, with <em>childCols</em> | |
317 | and <em>childRows</em> indicating how many rows and columns the label | |
318 | should span. Note that all other child widgets of the parent | |
319 | <em>must</em> be added to the parent using the <code>grid()</code> method. The | |
320 | <code>createlabel()</code> method may be called by derived classes during | |
321 | megawidget construction.</p> | |
322 | ||
323 | ||
324 | </dd></dl> | |
325 | <a name=method.defineoptions></a> | |
326 | <dl><dt> <strong>defineoptions</strong>(<em>keywords</em>, <em>optionDefs</em>, <em>dynamicGroups</em> = <strong>()</strong>)</dt><dd> | |
327 | Create options for this megawidget. The <em>optionDefs</em> argument | |
328 | defines the options. It is a sequence of 3-element tuples, | |
329 | (<em>name</em>, <em>default</em>, <em>callback</em>), where <em>name</em> is the name of the | |
330 | option, <em>default</em> is its default value and <em>callback</em> is the | |
331 | function to call when the value of the option is set by a call to | |
332 | <code>configure()</code>. The <em>keywords</em> argument should be the keyword | |
333 | arguments passed in to the constructor of the megawidget. The user | |
334 | may override the default value of an option by supplying a keyword | |
335 | argument to the constructor.</p> | |
336 | <p> If any option created by a base class is also defined by | |
337 | <em>optionDefs</em>, then the derived class's default value will take | |
338 | precedence over the base class's. If the <em>callback</em> field is not | |
339 | <strong>None</strong>, then this will also override the callback set by the base | |
340 | class.</p> | |
341 | ||
342 | <p> If <em>callback</em> is <strong>Pmw.INITOPT</strong>, then the option is an | |
343 | <em>initialisation option</em>.</p> | |
344 | ||
345 | <p> The <em>dynamicGroups</em> argument contains a list of the groups of the | |
346 | components created dynamically by this megawidget. If a group is | |
347 | included in this list, then it not an error if a keyword argument | |
348 | for the group is given to the constructor or to <code>configure()</code>, | |
349 | even when no components with this group have been created.</p> | |
350 | ||
351 | <p> If <code>defineoptions()</code> is called, it must be called once in the | |
352 | megawidget constructor before the call to the constructor of the | |
353 | base class and there must be a matching call to | |
354 | <code>initialiseoptions()</code> at the end of the constructor.</p> | |
355 | ||
356 | ||
357 | ||
358 | </dd></dl> | |
359 | <a name=method.destroy></a> | |
360 | <dl><dt> <strong>destroy</strong>()</dt><dd> | |
361 | Destroy the <strong>hull</strong> component widget, if it exists, including all | |
362 | of its children.</p> | |
363 | ||
364 | ||
365 | </dd></dl> | |
366 | <a name=method.destroycomponent></a> | |
367 | <dl><dt> <strong>destroycomponent</strong>(<em>name</em>)</dt><dd> | |
368 | Remove the megawidget component called <em>name</em>. This method may be | |
369 | called by derived classes to destroy a megawidget component. It | |
370 | destroys the component widget and then removes all record of the | |
371 | component from the megawidget.</p> | |
372 | ||
373 | ||
374 | </dd></dl> | |
375 | <a name=method.hulldestroyed></a> | |
376 | <dl><dt> <strong>hulldestroyed</strong>()</dt><dd> | |
377 | Return true if the Tk widget corresponding to the <strong>hull</strong> component | |
378 | has been destroyed.</p> | |
379 | ||
380 | ||
381 | </dd></dl> | |
382 | <a name=method.initialiseoptions></a> | |
383 | <dl><dt> <strong>initialiseoptions</strong>(<em>dummy</em> = <strong>None</strong>)</dt><dd> | |
384 | Check keyword arguments and call option callback functions. This | |
385 | method must be called, at the end of a megawidget constructor, if | |
386 | and only if <code>defineoptions()</code> was also called in the constructor. | |
387 | The <em>dummy</em> argument is not required, but is retained for | |
388 | backwards compatibility.</p> | |
389 | <p> It checks that all keyword arguments given to the constructor have | |
390 | been used. If not, it raises an error indicating which arguments | |
391 | were unused. A keyword is defined to be used if, during the | |
392 | construction of a megawidget, it is defined in a call to | |
393 | <code>defineoptions()</code> or <code>addoptions()</code> (by the megawidget or one of | |
394 | its base classes), or it references, by name, a component of the | |
395 | megawidget, or it references, by group, at least one component. | |
396 | It also calls the configuration callback function for all options | |
397 | that have a callback.</p> | |
398 | ||
399 | <p> This method is only effective when called by the constructor of | |
400 | the <em>leaf</em> class, that is, the class in the class hierarchy which | |
401 | first called <code>defineoptions()</code>. For all other classes in the | |
402 | class hierarchy (base classes), the method returns immediately.</p> | |
403 | ||
404 | ||
405 | ||
406 | </dd></dl> | |
407 | <a name=method.interior></a> | |
408 | <dl><dt> <strong>interior</strong>()</dt><dd> | |
409 | Return the widget framing the interior space in which any children | |
410 | of this megawidget should be created. By default, this returns | |
411 | the <strong>hull</strong> component widget, if one was created, or <strong>None</strong> | |
412 | otherwise. A subclass should use the widget returned by | |
413 | <code>interior()</code> as the parent of any components or sub-widgets it | |
414 | creates. Megawidgets which can be further subclassed, such as | |
415 | <a href="Dialog.html">Pmw.Dialog</a>, should redefine this method to return the widget in | |
416 | which subclasses should create children. The overall containing | |
417 | widget is always available as the <strong>hull</strong> component.</p> | |
418 | ||
419 | ||
420 | </dd></dl> | |
421 | <a name=method.isinitoption></a> | |
422 | <dl><dt> <strong>isinitoption</strong>(<em>option</em>)</dt><dd> | |
423 | If <em>option</em> is an initialisation option, return true. Otherwise, | |
424 | return false (the option is a configuration option). The <em>option</em> | |
425 | argument must be an option of this megawidget, not an option of a | |
426 | component. Otherwise an exception is raised.</p> | |
427 | ||
428 | ||
429 | </dd></dl> | |
430 | <a name=method.options></a> | |
431 | <dl><dt> <strong>options</strong>()</dt><dd> | |
432 | Return a sorted list of this megawidget's options. Each item in | |
433 | the list is a 3-element tuple, (<em>option</em>, <em>default</em>, <em>isinit</em>), | |
434 | where <em>option</em> is the name of the option, <em>default</em> is its default | |
435 | value and <em>isinit</em> is true if the option is an initialisation | |
436 | option.</p> | |
437 | ||
438 | ||
439 | </dd></dl> | |
440 | </dd> | |
441 | </dl> | |
442 | ||
443 | <center><P ALIGN="CENTER"> | |
444 | <IMG SRC = blue_line.gif ALT = "" WIDTH=320 HEIGHT=5> | |
445 | </p></center> | |
446 | ||
447 | ||
448 | <font size=-1> | |
449 | <center><P ALIGN="CENTER"> | |
450 | Pmw 1.2 - | |
451 | 5 Aug 2003 | |
452 | - <a href="index.html">Home</a> | |
453 | <br>Manual page last reviewed: 22 May 1998 | |
454 | </p></center> | |
455 | </font> | |
456 | ||
457 | </body> | |
458 | </html> | |
459 |