| 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 | |