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.ScrolledListBox 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.ScrolledListBox</h1> | |
13 | ||
14 | <center><IMG SRC=ScrolledListBox.gif ALT="" WIDTH=210 HEIGHT=168></center> | |
15 | <dl> | |
16 | <dt> <h3>Name</h3></dt><dd> | |
17 | <p>Pmw.ScrolledListBox() - | |
18 | listbox with optional scrollbars | |
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 scrolled listbox consists of a standard listbox widget with optional | |
29 | scrollbars which can be used to scroll the listbox. The | |
30 | scrollbars can be <em>dynamic</em>, which means that a scrollbar will | |
31 | only be displayed if it is necessary. That is, if the listbox | |
32 | does not contain enough entries, the vertical scrollbar will be | |
33 | automatically hidden and if the entries are not wide enough, the | |
34 | horizontal scrollbar will be automatically hidden.</p> | |
35 | ||
36 | <p></p> | |
37 | ||
38 | ||
39 | </dd> | |
40 | <dt> <h3>Options</h3></dt><dd> | |
41 | Options for this megawidget and its base | |
42 | classes are described below.<p></p> | |
43 | <a name=option.dblclickcommand></a> | |
44 | <dl><dt> <strong>dblclickcommand | |
45 | </strong></dt><dd> | |
46 | This specifies a function to call when mouse button 1 is double | |
47 | clicked over an entry in the <strong>listbox</strong> component. The default is <strong>None</strong>.</p> | |
48 | ||
49 | ||
50 | </dd></dl> | |
51 | <a name=option.hscrollmode></a> | |
52 | <dl><dt> <strong>hscrollmode | |
53 | </strong></dt><dd> | |
54 | The horizontal scroll mode. If <strong>'none'</strong>, the horizontal scrollbar | |
55 | will never be displayed. If <strong>'static'</strong>, the scrollbar will always | |
56 | be displayed. If <strong>'dynamic'</strong>, the scrollbar will be displayed | |
57 | only if necessary. The default is <strong>'dynamic'</strong>.</p> | |
58 | ||
59 | ||
60 | </dd></dl> | |
61 | <a name=option.items></a> | |
62 | <dl><dt> <strong>items | |
63 | </strong></dt><dd> | |
64 | Initialisation option. A tuple containing the initial items to be displayed by the | |
65 | <strong>listbox</strong> component. The default is <strong>()</strong>.</p> | |
66 | ||
67 | ||
68 | </dd></dl> | |
69 | <a name=option.labelmargin></a> | |
70 | <dl><dt> <strong>labelmargin | |
71 | </strong></dt><dd> | |
72 | Initialisation option. If the <strong>labelpos</strong> option is not <strong>None</strong>, this specifies the | |
73 | distance between the <strong>label</strong> component and the rest of the | |
74 | megawidget. The default is <strong>0</strong>.</p> | |
75 | ||
76 | ||
77 | </dd></dl> | |
78 | <a name=option.labelpos></a> | |
79 | <dl><dt> <strong>labelpos | |
80 | </strong></dt><dd> | |
81 | Initialisation option. Specifies where to place the <strong>label</strong> component. If not | |
82 | <strong>None</strong>, it should be a concatenation of one or two of the | |
83 | letters <strong>'n'</strong>, <strong>'s'</strong>, <strong>'e'</strong> and <strong>'w'</strong>. The first letter | |
84 | specifies on which side of the megawidget to place the label. | |
85 | If a second letter is specified, it indicates where on that | |
86 | side to place the label. For example, if <strong>labelpos</strong> is <strong>'w'</strong>, | |
87 | the label is placed in the center of the left hand side; if | |
88 | it is <strong>'wn'</strong>, the label is placed at the top of the left | |
89 | hand side; if it is <strong>'ws'</strong>, the label is placed at the | |
90 | bottom of the left hand side.</p> | |
91 | <p> If <strong>None</strong>, a label component is not created. The default is <strong>None</strong>.</p> | |
92 | ||
93 | ||
94 | ||
95 | </dd></dl> | |
96 | <a name=option.scrollmargin></a> | |
97 | <dl><dt> <strong>scrollmargin | |
98 | </strong></dt><dd> | |
99 | Initialisation option. The distance between the scrollbars and the listbox widget. The default is <strong>2</strong>.</p> | |
100 | ||
101 | ||
102 | </dd></dl> | |
103 | <a name=option.selectioncommand></a> | |
104 | <dl><dt> <strong>selectioncommand | |
105 | </strong></dt><dd> | |
106 | This specifies a function to call when mouse button 1 is single | |
107 | clicked over an entry in the <strong>listbox</strong> component or if the <strong><Space></strong> | |
108 | or <strong><Return></strong> key is hit while the <strong>listbox</strong> has focus. The default is <strong>None</strong>.</p> | |
109 | ||
110 | ||
111 | </dd></dl> | |
112 | <a name=option.usehullsize></a> | |
113 | <dl><dt> <strong>usehullsize | |
114 | </strong></dt><dd> | |
115 | Initialisation option. If true, the size of the megawidget is determined solely by the | |
116 | width and height options of the <strong>hull</strong> component.</p> | |
117 | <p> Otherwise, the size of the megawidget is determined by the width | |
118 | and height of the <strong>listbox</strong> component, along with the size and/or | |
119 | existence of the other components, such as the label, the | |
120 | scrollbars and the scrollmargin option. All these affect the | |
121 | overall size of the megawidget. The default is <strong>0</strong>.</p> | |
122 | ||
123 | ||
124 | ||
125 | </dd></dl> | |
126 | <a name=option.vscrollmode></a> | |
127 | <dl><dt> <strong>vscrollmode | |
128 | </strong></dt><dd> | |
129 | The vertical scroll mode. If <strong>'none'</strong>, the vertical scrollbar | |
130 | will never be displayed. If <strong>'static'</strong>, the scrollbar will always | |
131 | be displayed. If <strong>'dynamic'</strong>, the scrollbar will be displayed | |
132 | only if necessary. The default is <strong>'dynamic'</strong>.</p> | |
133 | ||
134 | ||
135 | </dd></dl> | |
136 | </dd> | |
137 | <dt> <h3>Components</h3></dt><dd> | |
138 | Components created by this megawidget and its base | |
139 | classes are described below.<p></p> | |
140 | <a name=component.horizscrollbar></a> | |
141 | <dl><dt> <strong>horizscrollbar | |
142 | </strong></dt><dd> | |
143 | The horizontal scrollbar. By default, this component is a Tkinter.Scrollbar. Its component group is <strong>Scrollbar</strong>.</p> | |
144 | ||
145 | ||
146 | </dd></dl> | |
147 | <a name=component.hull></a> | |
148 | <dl><dt> <strong>hull | |
149 | </strong></dt><dd> | |
150 | This acts as the body for the entire megawidget. Other components | |
151 | are created as children of the hull to further specialise this | |
152 | class. By default, this component is a Tkinter.Frame.</p> | |
153 | ||
154 | ||
155 | </dd></dl> | |
156 | <a name=component.label></a> | |
157 | <dl><dt> <strong>label | |
158 | </strong></dt><dd> | |
159 | If the <strong>labelpos</strong> option is not <strong>None</strong>, this component is | |
160 | created as a text label for the megawidget. See the | |
161 | <strong>labelpos</strong> option for details. Note that to set, for example, | |
162 | the <strong>text</strong> option of the label, you need to use the <strong>label_text</strong> | |
163 | component option. By default, this component is a Tkinter.Label.</p> | |
164 | ||
165 | ||
166 | </dd></dl> | |
167 | <a name=component.listbox></a> | |
168 | <dl><dt> <strong>listbox | |
169 | </strong></dt><dd> | |
170 | The listbox widget which is scrolled by the scrollbars. By default, this component is a Tkinter.Listbox.</p> | |
171 | ||
172 | ||
173 | </dd></dl> | |
174 | <a name=component.vertscrollbar></a> | |
175 | <dl><dt> <strong>vertscrollbar | |
176 | </strong></dt><dd> | |
177 | The vertical scrollbar. By default, this component is a Tkinter.Scrollbar. Its component group is <strong>Scrollbar</strong>.</p> | |
178 | ||
179 | ||
180 | </dd></dl> | |
181 | </dd> | |
182 | <a name=methods></a> | |
183 | <dt> <h3>Methods</h3></dt><dd> | |
184 | Only methods specific to this megawidget are described below. | |
185 | For a description of its inherited methods, see the | |
186 | manual for its base class | |
187 | <strong><a href="MegaWidget.html#methods">Pmw.MegaWidget</a></strong>. | |
188 | In addition, methods from the | |
189 | <strong>Tkinter.Listbox</strong> class | |
190 | are forwarded by this megawidget to the | |
191 | <strong>listbox</strong> component. | |
192 | <p></p> | |
193 | <a name=method.bbox></a> | |
194 | <dl><dt> <strong>bbox</strong>(<em>index</em>)</dt><dd> | |
195 | This method is explicitly forwarded to the <strong>listbox</strong> component's | |
196 | <code>bbox()</code> method. Without this explicit forwarding, the <code>bbox()</code> | |
197 | method (aliased to <code>grid_bbox()</code>) of the <strong>hull</strong> would be invoked, | |
198 | which is probably not what the programmer intended.</p> | |
199 | ||
200 | ||
201 | </dd></dl> | |
202 | <a name=method.clear></a> | |
203 | <dl><dt> <strong>clear</strong>()</dt><dd> | |
204 | Delete all items from the scrolled listbox. Equivalent to | |
205 | <code>setlist(())</code>.</p> | |
206 | ||
207 | ||
208 | </dd></dl> | |
209 | <a name=method.get></a> | |
210 | <dl><dt> <strong>get</strong>(<em>first</em> = <strong>None</strong>, <em>last</em> = <strong>None</strong>)</dt><dd> | |
211 | This is the same as the <code>get()</code> method of the <strong>listbox</strong> component, | |
212 | except that if <em>first</em> is <strong>None</strong> all list | |
213 | elements are returned.</p> | |
214 | ||
215 | ||
216 | </dd></dl> | |
217 | <a name=method.getcurselection></a> | |
218 | <dl><dt> <strong>getcurselection</strong>()</dt><dd> | |
219 | Same as <code>getvalue()</code> method.</p> | |
220 | ||
221 | ||
222 | </dd></dl> | |
223 | <a name=method.getvalue></a> | |
224 | <dl><dt> <strong>getvalue</strong>()</dt><dd> | |
225 | Return a list of the currently selected items of the listbox.</p> | |
226 | ||
227 | ||
228 | </dd></dl> | |
229 | <a name=method.setlist></a> | |
230 | <dl><dt> <strong>setlist</strong>(<em>items</em>)</dt><dd> | |
231 | Replace all the items of the <strong>listbox</strong> component with those | |
232 | specified by the <em>items</em> sequence.</p> | |
233 | ||
234 | ||
235 | </dd></dl> | |
236 | <a name=method.setvalue></a> | |
237 | <dl><dt> <strong>setvalue</strong>(<em>textOrList</em>)</dt><dd> | |
238 | Set the current selection for the scrolled list to <em>textOrList</em>.</p> | |
239 | <p> If <em>textOrList</em> is a string, select only the list item specified.</p> | |
240 | ||
241 | <p> Otherwise, select only the list items specified by <em>textOrList</em>, | |
242 | which must be a sequence of strings.</p> | |
243 | ||
244 | ||
245 | ||
246 | </dd></dl> | |
247 | <a name=method.size></a> | |
248 | <dl><dt> <strong>size</strong>()</dt><dd> | |
249 | This method is explicitly forwarded to the <strong>listbox</strong> component's | |
250 | <code>size()</code> method. Without this explicit forwarding, the <code>size()</code> | |
251 | method (aliased to <code>grid_size()</code>) of the <strong>hull</strong> would be invoked, | |
252 | which is probably not what the programmer intended.</p> | |
253 | ||
254 | ||
255 | </dd></dl> | |
256 | </dd> | |
257 | <dt> <h3>Example</h3></dt><dd> | |
258 | The image at the top of this manual is a snapshot | |
259 | of the window (or part of the window) produced | |
260 | by the following code.<p></p> | |
261 | <pre> | |
262 | class Demo: | |
263 | def __init__(self, parent): | |
264 | # Create the ScrolledListBox. | |
265 | self.box = Pmw.ScrolledListBox(parent, | |
266 | items=('Sydney', 'Melbourne', 'Brisbane'), | |
267 | labelpos='nw', | |
268 | label_text='Cities', | |
269 | listbox_height = 6, | |
270 | selectioncommand=self.selectionCommand, | |
271 | dblclickcommand=self.defCmd, | |
272 | usehullsize = 1, | |
273 | hull_width = 200, | |
274 | hull_height = 200, | |
275 | ) | |
276 | ||
277 | # Create a group widget to contain the scrollmode options. | |
278 | w = Pmw.Group(parent, tag_text='Scroll mode') | |
279 | w.pack(side = 'bottom', padx = 5, pady = 5) | |
280 | ||
281 | hmode = Pmw.OptionMenu(w.interior(), | |
282 | labelpos = 'w', | |
283 | label_text = 'Horizontal:', | |
284 | items = ['none', 'static', 'dynamic'], | |
285 | command = self.sethscrollmode, | |
286 | menubutton_width = 8, | |
287 | ) | |
288 | hmode.pack(side = 'top', padx = 5, pady = 5) | |
289 | hmode.invoke('dynamic') | |
290 | ||
291 | vmode = Pmw.OptionMenu(w.interior(), | |
292 | labelpos = 'w', | |
293 | label_text = 'Vertical:', | |
294 | items = ['none', 'static', 'dynamic'], | |
295 | command = self.setvscrollmode, | |
296 | menubutton_width = 8, | |
297 | ) | |
298 | vmode.pack(side = 'top', padx = 5, pady = 5) | |
299 | vmode.invoke('dynamic') | |
300 | ||
301 | buttonBox = Pmw.ButtonBox(parent) | |
302 | buttonBox.pack(side = 'bottom') | |
303 | buttonBox.add('yview', text = 'Show\nyview', command = self.showYView) | |
304 | buttonBox.add('scroll', text = 'Page\ndown', command = self.pageDown) | |
305 | buttonBox.add('center', text = 'Center', command = self.centerPage) | |
306 | ||
307 | # Pack this last so that the buttons do not get shrunk when | |
308 | # the window is resized. | |
309 | self.box.pack(fill = 'both', expand = 1, padx = 5, pady = 5) | |
310 | ||
311 | # Do this after packing the scrolled list box, so that the | |
312 | # window does not resize as soon as it appears (because | |
313 | # alignlabels has to do an update_idletasks). | |
314 | Pmw.alignlabels((hmode, vmode)) | |
315 | ||
316 | # Add some more entries to the listbox. | |
317 | items = ('Andamooka', 'Coober Pedy', 'Innamincka', 'Oodnadatta') | |
318 | self.box.setlist(items) | |
319 | self.box.insert(2, 'Wagga Wagga', 'Perth', 'London') | |
320 | self.box.insert('end', 'Darwin', 'Auckland', 'New York') | |
321 | index = list(self.box.get(0, 'end')).index('London') | |
322 | self.box.delete(index) | |
323 | self.box.delete(7, 8) | |
324 | self.box.insert('end', 'Bulli', 'Alice Springs', 'Woy Woy') | |
325 | self.box.insert('end', 'Wallumburrawang', 'Willandra Billabong') | |
326 | ||
327 | def sethscrollmode(self, tag): | |
328 | self.box.configure(hscrollmode = tag) | |
329 | ||
330 | def setvscrollmode(self, tag): | |
331 | self.box.configure(vscrollmode = tag) | |
332 | ||
333 | def selectionCommand(self): | |
334 | sels = self.box.getcurselection() | |
335 | if len(sels) == 0: | |
336 | print 'No selection' | |
337 | else: | |
338 | print 'Selection:', sels[0] | |
339 | ||
340 | def defCmd(self): | |
341 | sels = self.box.getcurselection() | |
342 | if len(sels) == 0: | |
343 | print 'No selection for double click' | |
344 | else: | |
345 | print 'Double click:', sels[0] | |
346 | ||
347 | def showYView(self): | |
348 | print self.box.yview() | |
349 | ||
350 | def pageDown(self): | |
351 | self.box.yview('scroll', 1, 'page') | |
352 | ||
353 | def centerPage(self): | |
354 | top, bottom = self.box.yview() | |
355 | size = bottom - top | |
356 | middle = 0.5 - size / 2 | |
357 | self.box.yview('moveto', middle) | |
358 | ||
359 | </pre> | |
360 | </dd> | |
361 | </dl> | |
362 | ||
363 | <center><P ALIGN="CENTER"> | |
364 | <IMG SRC = blue_line.gif ALT = "" WIDTH=320 HEIGHT=5> | |
365 | </p></center> | |
366 | ||
367 | ||
368 | <font size=-1> | |
369 | <center><P ALIGN="CENTER"> | |
370 | Pmw 1.2 - | |
371 | 5 Aug 2003 | |
372 | - <a href="index.html">Home</a> | |
373 | <br>Manual page last reviewed: 30 August 1998 | |
374 | </p></center> | |
375 | </font> | |
376 | ||
377 | </body> | |
378 | </html> | |
379 |