Initial commit of OpenSPARC T2 architecture model.
[OpenSPARC-T2-SAM] / sam-t2 / devtools / amd64 / lib / python2.4 / site-packages / Pmw / Pmw_1_2 / doc / ComboBox.html
CommitLineData
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.ComboBox 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.ComboBox</h1>
13
14<center><IMG SRC=ComboBox.gif ALT="" WIDTH=376 HEIGHT=246></center>
15<dl>
16<dt> <h3>Name</h3></dt><dd>
17<p>Pmw.ComboBox() -
18 dropdown or simple combination box
19</p>
20
21
22</dd>
23<dt> <h3>Inherits</h3></dt><dd>
24<a href="MegaWidget.html">Pmw.MegaWidget</a><br>
25</dd>
26<dt> <h3>Description</h3></dt><dd>
27<p>
28 A combobox contains an entry field and an associated scrolled
29 listbox. When an item in the listbox is selected, it is displayed
30 in the entry field. Optionally, the user may also edit the entry
31 field directly.</p>
32
33<p> For a simple combobox, the scrolled listbox is displayed beneath
34 the entry field. For a dropdown combobox (the default), the
35 scrolled listbox is displayed in a window which pops up beneath
36 the entry field when the user clicks on an arrow button on the
37 right of the entry field. Either style allows an optional label.</p>
38
39<p></p>
40
41
42</dd>
43<dt> <h3>Options</h3></dt><dd>
44Options for this megawidget and its base
45classes are described below.<p></p>
46<a name=option.autoclear></a>
47<dl><dt> <strong>autoclear
48</strong></dt><dd>
49Initialisation option. If both <strong>autoclear</strong> and <strong>history</strong> are true, clear the entry field
50 whenever <strong>&lt;Return&gt;</strong> is pressed, after adding the value to the
51 history list. The default is <strong>0</strong>.</p>
52
53
54</dd></dl>
55<a name=option.buttonaspect></a>
56<dl><dt> <strong>buttonaspect
57</strong></dt><dd>
58Initialisation option. The width of the arrow button as a proportion of the height. The
59 height of the arrow button is set to the height of the entry
60 widget. The default is <strong>1.0</strong>.</p>
61
62
63</dd></dl>
64<a name=option.dropdown></a>
65<dl><dt> <strong>dropdown
66</strong></dt><dd>
67Initialisation option. Specifies whether the combobox should be dropdown or simple. The default is <strong>1</strong>.</p>
68
69
70</dd></dl>
71<a name=option.fliparrow></a>
72<dl><dt> <strong>fliparrow
73</strong></dt><dd>
74Initialisation option. If true, the arrow button is draw upside down when the listbox is
75 being displayed. Used only in dropdown megawidgets. The default is <strong>0</strong>.</p>
76
77
78</dd></dl>
79<a name=option.history></a>
80<dl><dt> <strong>history
81</strong></dt><dd>
82Initialisation option. When <strong>&lt;Return&gt;</strong> is pressed in the entry field, the current value
83 of the entry field is appended to the listbox if <strong>history</strong> is
84 true. The default is <strong>1</strong>.</p>
85
86
87</dd></dl>
88<a name=option.labelmargin></a>
89<dl><dt> <strong>labelmargin
90</strong></dt><dd>
91Initialisation option. If the <strong>labelpos</strong> option is not <strong>None</strong>, this specifies the
92 distance between the <strong>label</strong> component and the rest of the
93 megawidget. The default is <strong>0</strong>.</p>
94
95
96</dd></dl>
97<a name=option.labelpos></a>
98<dl><dt> <strong>labelpos
99</strong></dt><dd>
100Initialisation option. Specifies where to place the <strong>label</strong> component. If not
101 <strong>None</strong>, it should be a concatenation of one or two of the
102 letters <strong>'n'</strong>, <strong>'s'</strong>, <strong>'e'</strong> and <strong>'w'</strong>. The first letter
103 specifies on which side of the megawidget to place the label.
104 If a second letter is specified, it indicates where on that
105 side to place the label. For example, if <strong>labelpos</strong> is <strong>'w'</strong>,
106 the label is placed in the center of the left hand side; if
107 it is <strong>'wn'</strong>, the label is placed at the top of the left
108 hand side; if it is <strong>'ws'</strong>, the label is placed at the
109 bottom of the left hand side.</p>
110<p> If <strong>None</strong>, a label component is not created. The default is <strong>None</strong>.</p>
111
112
113
114</dd></dl>
115<a name=option.listheight></a>
116<dl><dt> <strong>listheight
117</strong></dt><dd>
118Initialisation option. The height, in pixels, of the dropdown listbox. The default is <strong>200</strong>.</p>
119
120
121</dd></dl>
122<a name=option.selectioncommand></a>
123<dl><dt> <strong>selectioncommand
124</strong></dt><dd>
125The function to call when an item is selected.
126 If this function takes a long time to run, and you want the entry
127 field to be updated quickly, call <code>update_idletasks()</code> at the
128 beginning of the function. Alternatively, wrap the function using
129 <code>Pmw.busycallback()</code>. The default is <strong>None</strong>.</p>
130
131
132</dd></dl>
133<a name=option.sticky></a>
134<dl><dt> <strong>sticky
135</strong></dt><dd>
136Initialisation option. The default is <strong>'ew'</strong>.</p>
137
138
139</dd></dl>
140<a name=option.unique></a>
141<dl><dt> <strong>unique
142</strong></dt><dd>
143Initialisation option. If both <strong>unique</strong> and <strong>history</strong> are true, the current value of the
144 entry field is not added to the listbox if it is already in the
145 list. The default is <strong>1</strong>.</p>
146
147
148</dd></dl>
149</dd>
150<dt> <h3>Components</h3></dt><dd>
151Components created by this megawidget and its base
152classes are described below.<p></p>
153<a name=component.arrowbutton></a>
154<dl><dt> <strong>arrowbutton
155</strong></dt><dd>
156In a dropdown combobox, the button to popup the listbox. By default, this component is a Tkinter.Canvas.</p>
157
158
159</dd></dl>
160<a name=component.entryfield></a>
161<dl><dt> <strong>entryfield
162</strong></dt><dd>
163The entry field where the current selection is displayed. By default, this component is a <a href="EntryField.html">Pmw.EntryField</a>.</p>
164
165
166</dd></dl>
167<a name=component.hull></a>
168<dl><dt> <strong>hull
169</strong></dt><dd>
170This acts as the body for the entire megawidget. Other components
171 are created as children of the hull to further specialise this
172 class. By default, this component is a Tkinter.Frame.</p>
173
174
175</dd></dl>
176<a name=component.label></a>
177<dl><dt> <strong>label
178</strong></dt><dd>
179If the <strong>labelpos</strong> option is not <strong>None</strong>, this component is
180 created as a text label for the megawidget. See the
181 <strong>labelpos</strong> option for details. Note that to set, for example,
182 the <strong>text</strong> option of the label, you need to use the <strong>label_text</strong>
183 component option. By default, this component is a Tkinter.Label.</p>
184
185
186</dd></dl>
187<a name=component.popup></a>
188<dl><dt> <strong>popup
189</strong></dt><dd>
190In a dropdown combobox, the dropdown window. By default, this component is a Tkinter.Toplevel.</p>
191
192
193</dd></dl>
194<a name=component.scrolledlist></a>
195<dl><dt> <strong>scrolledlist
196</strong></dt><dd>
197The scrolled listbox which displays the items to select. By default, this component is a <a href="ScrolledListBox.html">Pmw.ScrolledListBox</a>.</p>
198
199
200</dd></dl>
201</dd>
202<dt> <h3>Component aliases</h3></dt><dd>
203Sub-components of components of this megawidget
204may be accessed via the following aliases.<p></p>
205<dl><dt> <strong>entry
206</strong></dt><dd>
207Alias for <strong>entryfield_entry</strong>.
208</dd></dl>
209<dl><dt> <strong>listbox
210</strong></dt><dd>
211Alias for <strong>scrolledlist_listbox</strong>.
212</dd></dl>
213</dd>
214<a name=methods></a>
215<dt> <h3>Methods</h3></dt><dd>
216Only methods specific to this megawidget are described below.
217For a description of its inherited methods, see the
218manual for its base class
219<strong><a href="MegaWidget.html#methods">Pmw.MegaWidget</a></strong>.
220In addition, methods from the following classes
221are forwarded by this megawidget.
222Methods from <strong><a href="ScrolledListBox.html#methods">Pmw.ScrolledListBox</a></strong>
223are forwarded to the
224<strong>scrolledlist</strong> component.
225Methods from <strong><a href="EntryField.html#methods">Pmw.EntryField</a></strong>
226are forwarded to the
227<strong>entryfield</strong> component.
228Forwarded methods are searched in the order given.
229<p></p>
230<a name=method.bbox></a>
231<dl><dt> <strong>bbox</strong>(<em>index</em>)</dt><dd>
232This method is explicitly forwarded to the <strong>scrolledlist</strong>
233 component's <code>bbox()</code> method. Without this explicit forwarding,
234 the <code>bbox()</code> method (aliased to <code>grid_bbox()</code>) of the <strong>hull</strong> would
235 be invoked, which is probably not what the programmer intended.</p>
236
237
238</dd></dl>
239<a name=method.clear></a>
240<dl><dt> <strong>clear</strong>()</dt><dd>
241Delete all items from the scrolled listbox and delete all text
242 from the entry widget.</p>
243
244
245</dd></dl>
246<a name=method.get></a>
247<dl><dt> <strong>get</strong>(<em>first</em> = <strong>None</strong>, <em>last</em> = <strong>None</strong>)</dt><dd>
248This is the same as the <code>get()</code> method of the <strong>scrolledlist</strong>
249 component, except that if <em>first</em> is <strong>None</strong> then
250 the value of the entry field is returned.</p>
251
252
253</dd></dl>
254<a name=method.invoke></a>
255<dl><dt> <strong>invoke</strong>()</dt><dd>
256If a dropdown combobox, display the dropdown listbox. In a simple
257 combobox, select the currently selected item in the listbox,
258 call the <strong>selectioncommand</strong> and return the result.</p>
259
260
261</dd></dl>
262<a name=method.selectitem></a>
263<dl><dt> <strong>selectitem</strong>(<em>index</em>, <em>setentry</em> = <strong>1</strong>)</dt><dd>
264Select the item in the listbox specified by <em>index</em> which may be
265 either one of the items in the listbox or the integer index of one
266 of the items in the listbox.</p>
267<p> If <em>setentry</em> is true, also set the entry field to the selected
268 item.</p>
269
270
271
272</dd></dl>
273<a name=method.size></a>
274<dl><dt> <strong>size</strong>()</dt><dd>
275This method is explicitly forwarded to the <strong>scrolledlist</strong>
276 component's <code>size()</code> method. Without this explicit forwarding,
277 the <code>size()</code> method (aliased to <code>grid_size()</code>) of the <strong>hull</strong> would
278 be invoked, which is probably not what the programmer intended.</p>
279
280
281</dd></dl>
282</dd>
283<dt> <h3>Example</h3></dt><dd>
284The image at the top of this manual is a snapshot
285of the window (or part of the window) produced
286by the following code.<p></p>
287<pre>
288class Demo:
289 def __init__(self, parent):
290 parent.configure(background = 'white')
291
292 # Create and pack the widget to be configured.
293 self.target = Tkinter.Label(parent,
294 relief = 'sunken',
295 padx = 20,
296 pady = 20,
297 )
298 self.target.pack(fill = 'x', padx = 8, pady = 8)
299
300 # Create and pack the simple ComboBox.
301 words = ('Monti', 'Python', 'ik', 'den', 'Holie', 'Grailen', '(Bok)')
302 simple = Pmw.ComboBox(parent,
303 label_text = 'Simple ComboBox:',
304 labelpos = 'nw',
305 selectioncommand = self.changeText,
306 scrolledlist_items = words,
307 dropdown = 0,
308 )
309 simple.pack(side = 'left', fill = 'both',
310 expand = 1, padx = 8, pady = 8)
311
312 # Display the first text.
313 first = words[0]
314 simple.selectitem(first)
315 self.changeText(first)
316
317 # Create and pack the dropdown ComboBox.
318 colours = ('cornsilk1', 'snow1', 'seashell1', 'antiquewhite1',
319 'bisque1', 'peachpuff1', 'navajowhite1', 'lemonchiffon1',
320 'ivory1', 'honeydew1', 'lavenderblush1', 'mistyrose1')
321 dropdown = Pmw.ComboBox(parent,
322 label_text = 'Dropdown ComboBox:',
323 labelpos = 'nw',
324 selectioncommand = self.changeColour,
325 scrolledlist_items = colours,
326 )
327 dropdown.pack(side = 'left', anchor = 'n',
328 fill = 'x', expand = 1, padx = 8, pady = 8)
329
330 # Display the first colour.
331 first = colours[0]
332 dropdown.selectitem(first)
333 self.changeColour(first)
334
335 def changeColour(self, colour):
336 print 'Colour: ' + colour
337 self.target.configure(background = colour)
338
339 def changeText(self, text):
340 print 'Text: ' + text
341 self.target.configure(text = text)
342
343</pre>
344</dd>
345</dl>
346
347 <center><P ALIGN="CENTER">
348 <IMG SRC = blue_line.gif ALT = "" WIDTH=320 HEIGHT=5>
349 </p></center>
350
351
352 <font size=-1>
353 <center><P ALIGN="CENTER">
354 Pmw 1.2 -
355 5 Aug 2003
356 - <a href="index.html">Home</a>
357 <br>Manual page last reviewed: 1 November 1998
358 </p></center>
359 </font>
360
361 </body>
362 </html>
363