| 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.ScrolledFrame 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.ScrolledFrame</h1> |
| 13 | |
| 14 | <center><IMG SRC=ScrolledFrame.gif ALT="" WIDTH=404 HEIGHT=174></center> |
| 15 | <dl> |
| 16 | <dt> <h3>Name</h3></dt><dd> |
| 17 | <p>Pmw.ScrolledFrame() - |
| 18 | frame 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 frame consists of a scrollable interior frame within a |
| 29 | clipping frame. The programmer can create other widgets within |
| 30 | the interior frame. If the frame becomes larger than the |
| 31 | surrounding clipping frame, the user can position the frame using |
| 32 | the horizontal and vertical scrollbars.</p> |
| 33 | |
| 34 | <p> The scrollbars can be <em>dynamic</em>, which means that a scrollbar will |
| 35 | only be displayed if it is necessary. That is, if the frame is |
| 36 | smaller than the surrounding clipping frame, the scrollbar will be |
| 37 | hidden.</p> |
| 38 | |
| 39 | <p></p> |
| 40 | |
| 41 | |
| 42 | </dd> |
| 43 | <dt> <h3>Options</h3></dt><dd> |
| 44 | Options for this megawidget and its base |
| 45 | classes are described below.<p></p> |
| 46 | <a name=option.borderframe></a> |
| 47 | <dl><dt> <strong>borderframe |
| 48 | </strong></dt><dd> |
| 49 | Initialisation option. If true, the <strong>borderframe</strong> component will be created. The default is <strong>1</strong>.</p> |
| 50 | |
| 51 | |
| 52 | </dd></dl> |
| 53 | <a name=option.horizflex></a> |
| 54 | <dl><dt> <strong>horizflex |
| 55 | </strong></dt><dd> |
| 56 | Specifies how the width of the scrollable interior frame should be |
| 57 | resized relative to the clipping frame.</p> |
| 58 | <p> If <strong>'fixed'</strong>, the interior frame is set to the <em>natural</em> width, as |
| 59 | requested by the child widgets of the frame. If <strong>'expand'</strong> and |
| 60 | the requested width of the interior frame is less than the width |
| 61 | of the clipping frame, the interior frame expands to fill the |
| 62 | clipping frame. If <strong>'shrink'</strong> and the requested width of the |
| 63 | interior frame is more than the width of the clipping frame, the |
| 64 | interior frame shrinks to the width of the clipping frame. If |
| 65 | <strong>'elastic'</strong>, the width of the interior frame is always set to the |
| 66 | width of the clipping frame. The default is <strong>'fixed'</strong>.</p> |
| 67 | |
| 68 | |
| 69 | |
| 70 | </dd></dl> |
| 71 | <a name=option.horizfraction></a> |
| 72 | <dl><dt> <strong>horizfraction |
| 73 | </strong></dt><dd> |
| 74 | Initialisation option. The fraction of the width of the clipper frame to scroll the |
| 75 | interior frame when the user clicks on the horizontal scrollbar |
| 76 | arrows. The default is <strong>0.05</strong>.</p> |
| 77 | |
| 78 | |
| 79 | </dd></dl> |
| 80 | <a name=option.hscrollmode></a> |
| 81 | <dl><dt> <strong>hscrollmode |
| 82 | </strong></dt><dd> |
| 83 | The horizontal scroll mode. If <strong>'none'</strong>, the horizontal scrollbar |
| 84 | will never be displayed. If <strong>'static'</strong>, the scrollbar will always |
| 85 | be displayed. If <strong>'dynamic'</strong>, the scrollbar will be displayed |
| 86 | only if necessary. The default is <strong>'dynamic'</strong>.</p> |
| 87 | |
| 88 | |
| 89 | </dd></dl> |
| 90 | <a name=option.labelmargin></a> |
| 91 | <dl><dt> <strong>labelmargin |
| 92 | </strong></dt><dd> |
| 93 | Initialisation option. If the <strong>labelpos</strong> option is not <strong>None</strong>, this specifies the |
| 94 | distance between the <strong>label</strong> component and the rest of the |
| 95 | megawidget. The default is <strong>0</strong>.</p> |
| 96 | |
| 97 | |
| 98 | </dd></dl> |
| 99 | <a name=option.labelpos></a> |
| 100 | <dl><dt> <strong>labelpos |
| 101 | </strong></dt><dd> |
| 102 | Initialisation option. Specifies where to place the <strong>label</strong> component. If not |
| 103 | <strong>None</strong>, it should be a concatenation of one or two of the |
| 104 | letters <strong>'n'</strong>, <strong>'s'</strong>, <strong>'e'</strong> and <strong>'w'</strong>. The first letter |
| 105 | specifies on which side of the megawidget to place the label. |
| 106 | If a second letter is specified, it indicates where on that |
| 107 | side to place the label. For example, if <strong>labelpos</strong> is <strong>'w'</strong>, |
| 108 | the label is placed in the center of the left hand side; if |
| 109 | it is <strong>'wn'</strong>, the label is placed at the top of the left |
| 110 | hand side; if it is <strong>'ws'</strong>, the label is placed at the |
| 111 | bottom of the left hand side.</p> |
| 112 | <p> If <strong>None</strong>, a label component is not created. The default is <strong>None</strong>.</p> |
| 113 | |
| 114 | |
| 115 | |
| 116 | </dd></dl> |
| 117 | <a name=option.scrollmargin></a> |
| 118 | <dl><dt> <strong>scrollmargin |
| 119 | </strong></dt><dd> |
| 120 | Initialisation option. The distance between the scrollbars and the clipping frame. The default is <strong>2</strong>.</p> |
| 121 | |
| 122 | |
| 123 | </dd></dl> |
| 124 | <a name=option.usehullsize></a> |
| 125 | <dl><dt> <strong>usehullsize |
| 126 | </strong></dt><dd> |
| 127 | Initialisation option. If true, the size of the megawidget is determined solely by the |
| 128 | width and height options of the <strong>hull</strong> component.</p> |
| 129 | <p> Otherwise, the size of the megawidget is determined by the width |
| 130 | and height of the <strong>clipper</strong> component, along with the size and/or |
| 131 | existence of the other components, such as the label, the |
| 132 | scrollbars and the scrollmargin option. All these affect the |
| 133 | overall size of the megawidget. The default is <strong>0</strong>.</p> |
| 134 | |
| 135 | |
| 136 | |
| 137 | </dd></dl> |
| 138 | <a name=option.vertflex></a> |
| 139 | <dl><dt> <strong>vertflex |
| 140 | </strong></dt><dd> |
| 141 | Specifies how the height of the scrollable interior frame should |
| 142 | be resized relative to the clipping frame.</p> |
| 143 | <p> If <strong>'fixed'</strong>, the interior frame is set to the <em>natural</em> height, |
| 144 | as requested by the child widgets of the frame. If <strong>'expand'</strong> and |
| 145 | the requested height of the interior frame is less than the height |
| 146 | of the clipping frame, the interior frame expands to fill the |
| 147 | clipping frame. If <strong>'shrink'</strong> and the requested height of the |
| 148 | interior frame is more than the height of the clipping frame, the |
| 149 | interior frame shrinks to the height of the clipping frame. If |
| 150 | <strong>'elastic'</strong>, the height of the interior frame is always set to the |
| 151 | height of the clipping frame. The default is <strong>'fixed'</strong>.</p> |
| 152 | |
| 153 | |
| 154 | |
| 155 | </dd></dl> |
| 156 | <a name=option.vertfraction></a> |
| 157 | <dl><dt> <strong>vertfraction |
| 158 | </strong></dt><dd> |
| 159 | Initialisation option. The fraction of the height of the clipper frame to scroll the |
| 160 | interior frame when the user clicks on the vertical scrollbar |
| 161 | arrows. The default is <strong>0.05</strong>.</p> |
| 162 | |
| 163 | |
| 164 | </dd></dl> |
| 165 | <a name=option.vscrollmode></a> |
| 166 | <dl><dt> <strong>vscrollmode |
| 167 | </strong></dt><dd> |
| 168 | The vertical scroll mode. If <strong>'none'</strong>, the vertical scrollbar |
| 169 | will never be displayed. If <strong>'static'</strong>, the scrollbar will always |
| 170 | be displayed. If <strong>'dynamic'</strong>, the scrollbar will be displayed |
| 171 | only if necessary. The default is <strong>'dynamic'</strong>.</p> |
| 172 | |
| 173 | |
| 174 | </dd></dl> |
| 175 | </dd> |
| 176 | <dt> <h3>Components</h3></dt><dd> |
| 177 | Components created by this megawidget and its base |
| 178 | classes are described below.<p></p> |
| 179 | <a name=component.borderframe></a> |
| 180 | <dl><dt> <strong>borderframe |
| 181 | </strong></dt><dd> |
| 182 | A frame widget which snuggly fits around the clipper, to give the |
| 183 | appearance of a border. It is created with a border so that the |
| 184 | clipper, which is created without a border, looks like it has a |
| 185 | border. By default, this component is a Tkinter.Frame.</p> |
| 186 | |
| 187 | |
| 188 | </dd></dl> |
| 189 | <a name=component.clipper></a> |
| 190 | <dl><dt> <strong>clipper |
| 191 | </strong></dt><dd> |
| 192 | The frame which is used to provide a clipped view of the <strong>frame</strong> |
| 193 | component. If the <strong>borderframe</strong> option is true, this is created |
| 194 | with a borderwidth of <strong>0</strong> to overcome a known problem with using |
| 195 | <code>place</code> to position widgets: if a widget (in this case the |
| 196 | <strong>frame</strong> component) is <code>placed</code> inside a frame (in this case the |
| 197 | <strong>clipper</strong> component) and it extends across one of the edges of the |
| 198 | frame, then the widget obscures the border of the frame. |
| 199 | Therefore, if the clipper has no border, then this overlapping |
| 200 | does not occur. By default, this component is a Tkinter.Frame.</p> |
| 201 | |
| 202 | |
| 203 | </dd></dl> |
| 204 | <a name=component.frame></a> |
| 205 | <dl><dt> <strong>frame |
| 206 | </strong></dt><dd> |
| 207 | The frame within the clipper to contain the widgets to be scrolled. By default, this component is a Tkinter.Frame.</p> |
| 208 | |
| 209 | |
| 210 | </dd></dl> |
| 211 | <a name=component.horizscrollbar></a> |
| 212 | <dl><dt> <strong>horizscrollbar |
| 213 | </strong></dt><dd> |
| 214 | The horizontal scrollbar. By default, this component is a Tkinter.Scrollbar. Its component group is <strong>Scrollbar</strong>.</p> |
| 215 | |
| 216 | |
| 217 | </dd></dl> |
| 218 | <a name=component.hull></a> |
| 219 | <dl><dt> <strong>hull |
| 220 | </strong></dt><dd> |
| 221 | This acts as the body for the entire megawidget. Other components |
| 222 | are created as children of the hull to further specialise this |
| 223 | class. By default, this component is a Tkinter.Frame.</p> |
| 224 | |
| 225 | |
| 226 | </dd></dl> |
| 227 | <a name=component.label></a> |
| 228 | <dl><dt> <strong>label |
| 229 | </strong></dt><dd> |
| 230 | If the <strong>labelpos</strong> option is not <strong>None</strong>, this component is |
| 231 | created as a text label for the megawidget. See the |
| 232 | <strong>labelpos</strong> option for details. Note that to set, for example, |
| 233 | the <strong>text</strong> option of the label, you need to use the <strong>label_text</strong> |
| 234 | component option. By default, this component is a Tkinter.Label.</p> |
| 235 | |
| 236 | |
| 237 | </dd></dl> |
| 238 | <a name=component.vertscrollbar></a> |
| 239 | <dl><dt> <strong>vertscrollbar |
| 240 | </strong></dt><dd> |
| 241 | The vertical scrollbar. By default, this component is a Tkinter.Scrollbar. Its component group is <strong>Scrollbar</strong>.</p> |
| 242 | |
| 243 | |
| 244 | </dd></dl> |
| 245 | </dd> |
| 246 | <a name=methods></a> |
| 247 | <dt> <h3>Methods</h3></dt><dd> |
| 248 | Only methods specific to this megawidget are described below. |
| 249 | For a description of its inherited methods, see the |
| 250 | manual for its base class |
| 251 | <strong><a href="MegaWidget.html#methods">Pmw.MegaWidget</a></strong>. |
| 252 | <p></p> |
| 253 | <a name=method.interior></a> |
| 254 | <dl><dt> <strong>interior</strong>()</dt><dd> |
| 255 | Return the frame within which the programmer may create widgets to |
| 256 | be scrolled. This is the same as <code>component('frame')</code>.</p> |
| 257 | |
| 258 | |
| 259 | </dd></dl> |
| 260 | <a name=method.reposition></a> |
| 261 | <dl><dt> <strong>reposition</strong>()</dt><dd> |
| 262 | Update the position of the <strong>frame</strong> component in the <strong>clipper</strong> and |
| 263 | update the scrollbars.</p> |
| 264 | <p> Usually, this method does not need to be called explicitly, since |
| 265 | the position of the <strong>frame</strong> component and the scrollbars are |
| 266 | automatically updated whenever the size of the <strong>frame</strong> or |
| 267 | <strong>clipper</strong> components change or the user clicks in the scrollbars. |
| 268 | However, if <strong>horizflex</strong> or <strong>vertflex</strong> is <strong>'expand'</strong>, the |
| 269 | megawidget cannot detect when the requested size of the <strong>frame</strong> |
| 270 | increases to greater than the size of the <strong>clipper</strong>. Therefore, |
| 271 | this method should be called when a new widget is added to the |
| 272 | <strong>frame</strong> (or a widget is increased in size) <em>after</em> the initial |
| 273 | megawidget construction.</p> |
| 274 | |
| 275 | |
| 276 | |
| 277 | </dd></dl> |
| 278 | <a name=method.xview></a> |
| 279 | <dl><dt> <strong>xview</strong>(<em>mode</em> = <strong>None</strong>, <em>value</em> = <strong>None</strong>, <em>units</em> = <strong>None</strong>)</dt><dd> |
| 280 | Query or change the horizontal position of the scrollable interior |
| 281 | frame. If <em>mode</em> is <strong>None</strong>, return a tuple of two numbers, each |
| 282 | between 0.0 and 1.0. The first is the position of the left edge |
| 283 | of the visible region of the contents of the scrolled frame, |
| 284 | expressed as a fraction of the total width of the contents. The |
| 285 | second is the position of the right edge of the visible region.</p> |
| 286 | <p> If <em>mode</em> == <strong>'moveto'</strong>, adjust the view of the interior so that |
| 287 | the fraction <em>value</em> of the total width of the contents is |
| 288 | off-screen to the left. The <em>value</em> must be between <em>0.0</em> and |
| 289 | <em>1.0</em>.</p> |
| 290 | |
| 291 | <p> If <em>mode</em> == <strong>'scroll'</strong>, adjust the view of the interior left or |
| 292 | right by a fixed amount. If <em>what</em> is <strong>'units'</strong>, move the view in |
| 293 | units of <strong>horizfraction</strong>. If <em>what</em> is <em>pages</em>, move the view in |
| 294 | units of the width of the scrolled frame. If <em>value</em> is positive, |
| 295 | move to the right, otherwise move to the left.</p> |
| 296 | |
| 297 | |
| 298 | |
| 299 | </dd></dl> |
| 300 | <a name=method.yview></a> |
| 301 | <dl><dt> <strong>yview</strong>(<em>mode</em> = <strong>None</strong>, <em>value</em> = <strong>None</strong>, <em>units</em> = <strong>None</strong>)</dt><dd> |
| 302 | Query or change the vertical position of the scrollable interior |
| 303 | frame. If <em>mode</em> is <strong>None</strong>, return a tuple of two numbers, each |
| 304 | between 0.0 and 1.0. The first is the position of the top edge |
| 305 | of the visible region of the contents of the scrolled frame, |
| 306 | expressed as a fraction of the total height of the contents. The |
| 307 | second is the position of the bottom edge of the visible region.</p> |
| 308 | <p> If <em>mode</em> == <strong>'moveto'</strong>, adjust the view of the interior so that |
| 309 | the fraction <em>value</em> of the total height of the contents is |
| 310 | off-screen to the top. The <em>value</em> must be between <em>0.0</em> and |
| 311 | <em>1.0</em>.</p> |
| 312 | |
| 313 | <p> If <em>mode</em> == <strong>'scroll'</strong>, adjust the view of the interior up or |
| 314 | down by a fixed amount. If <em>what</em> is <strong>'units'</strong>, move the view in |
| 315 | units of <strong>vertfraction</strong>. If <em>what</em> is <em>pages</em>, move the view in |
| 316 | units of the height of the scrolled frame. If <em>value</em> is |
| 317 | positive, move to down, otherwise move up.</p> |
| 318 | |
| 319 | |
| 320 | |
| 321 | </dd></dl> |
| 322 | </dd> |
| 323 | <dt> <h3>Example</h3></dt><dd> |
| 324 | The image at the top of this manual is a snapshot |
| 325 | of the window (or part of the window) produced |
| 326 | by the following code.<p></p> |
| 327 | <pre> |
| 328 | class Demo: |
| 329 | def __init__(self, parent): |
| 330 | # Create the ScrolledFrame. |
| 331 | self.sf = Pmw.ScrolledFrame(parent, |
| 332 | labelpos = 'n', label_text = 'ScrolledFrame', |
| 333 | usehullsize = 1, |
| 334 | hull_width = 400, |
| 335 | hull_height = 220, |
| 336 | ) |
| 337 | |
| 338 | # Create a group widget to contain the flex options. |
| 339 | w = Pmw.Group(parent, tag_text='Flex') |
| 340 | w.pack(side = 'bottom', padx = 5, pady = 3) |
| 341 | |
| 342 | hflex = Pmw.OptionMenu(w.interior(), |
| 343 | labelpos = 'w', |
| 344 | label_text = 'Horizontal:', |
| 345 | items = ['fixed', 'expand', 'shrink', 'elastic'], |
| 346 | command = self.sethflex, |
| 347 | menubutton_width = 8, |
| 348 | ) |
| 349 | hflex.pack(side = 'left', padx = 5, pady = 3) |
| 350 | hflex.invoke('fixed') |
| 351 | |
| 352 | vflex = Pmw.OptionMenu(w.interior(), |
| 353 | labelpos = 'w', |
| 354 | label_text = 'Vertical:', |
| 355 | items = ['fixed', 'expand', 'shrink', 'elastic'], |
| 356 | command = self.setvflex, |
| 357 | menubutton_width = 8, |
| 358 | ) |
| 359 | vflex.pack(side = 'left', padx = 5, pady = 3) |
| 360 | vflex.invoke('fixed') |
| 361 | |
| 362 | # Create a group widget to contain the scrollmode options. |
| 363 | w = Pmw.Group(parent, tag_text='Scroll mode') |
| 364 | w.pack(side = 'bottom', padx = 5, pady = 0) |
| 365 | |
| 366 | hmode = Pmw.OptionMenu(w.interior(), |
| 367 | labelpos = 'w', |
| 368 | label_text = 'Horizontal:', |
| 369 | items = ['none', 'static', 'dynamic'], |
| 370 | command = self.sethscrollmode, |
| 371 | menubutton_width = 8, |
| 372 | ) |
| 373 | hmode.pack(side = 'left', padx = 5, pady = 3) |
| 374 | hmode.invoke('dynamic') |
| 375 | |
| 376 | vmode = Pmw.OptionMenu(w.interior(), |
| 377 | labelpos = 'w', |
| 378 | label_text = 'Vertical:', |
| 379 | items = ['none', 'static', 'dynamic'], |
| 380 | command = self.setvscrollmode, |
| 381 | menubutton_width = 8, |
| 382 | ) |
| 383 | vmode.pack(side = 'left', padx = 5, pady = 3) |
| 384 | vmode.invoke('dynamic') |
| 385 | |
| 386 | self.radio = Pmw.RadioSelect(parent, selectmode = 'multiple', |
| 387 | command = self.radioSelected) |
| 388 | self.radio.add('center', text = 'Keep centered vertically') |
| 389 | self.radio.pack(side = 'bottom') |
| 390 | |
| 391 | buttonBox = Pmw.ButtonBox(parent) |
| 392 | buttonBox.pack(side = 'bottom') |
| 393 | buttonBox.add('add', text = 'Add a button', command = self.addButton) |
| 394 | buttonBox.add('yview', text = 'Show yview', command = self.showYView) |
| 395 | buttonBox.add('scroll', text = 'Page down', command = self.pageDown) |
| 396 | |
| 397 | # Pack this last so that the buttons do not get shrunk when |
| 398 | # the window is resized. |
| 399 | self.sf.pack(padx = 5, pady = 3, fill = 'both', expand = 1) |
| 400 | |
| 401 | self.frame = self.sf.interior() |
| 402 | |
| 403 | self.row = 0 |
| 404 | self.col = 0 |
| 405 | |
| 406 | for count in range(15): |
| 407 | self.addButton() |
| 408 | |
| 409 | def sethscrollmode(self, tag): |
| 410 | self.sf.configure(hscrollmode = tag) |
| 411 | |
| 412 | def setvscrollmode(self, tag): |
| 413 | self.sf.configure(vscrollmode = tag) |
| 414 | |
| 415 | def sethflex(self, tag): |
| 416 | self.sf.configure(horizflex = tag) |
| 417 | |
| 418 | def setvflex(self, tag): |
| 419 | self.sf.configure(vertflex = tag) |
| 420 | |
| 421 | def addButton(self): |
| 422 | button = Tkinter.Button(self.frame, |
| 423 | text = '(%d,%d)' % (self.col, self.row)) |
| 424 | button.grid(row = self.row, column = self.col, sticky = 'nsew') |
| 425 | |
| 426 | self.frame.grid_rowconfigure(self.row, weight = 1) |
| 427 | self.frame.grid_columnconfigure(self.col, weight = 1) |
| 428 | if self.sf.cget('horizflex') == 'expand' or \ |
| 429 | self.sf.cget('vertflex') == 'expand': |
| 430 | self.sf.reposition() |
| 431 | |
| 432 | if 'center' in self.radio.getcurselection(): |
| 433 | self.sf.update_idletasks() |
| 434 | self.centerPage() |
| 435 | |
| 436 | if self.col == self.row: |
| 437 | self.col = 0 |
| 438 | self.row = self.row + 1 |
| 439 | else: |
| 440 | self.col = self.col + 1 |
| 441 | |
| 442 | def showYView(self): |
| 443 | print self.sf.yview() |
| 444 | |
| 445 | def pageDown(self): |
| 446 | self.sf.yview('scroll', 1, 'page') |
| 447 | |
| 448 | def radioSelected(self, name, state): |
| 449 | if state: |
| 450 | self.centerPage() |
| 451 | |
| 452 | def centerPage(self): |
| 453 | # Example of how to use the yview() method of Pmw.ScrolledFrame. |
| 454 | top, bottom = self.sf.yview() |
| 455 | size = bottom - top |
| 456 | middle = 0.5 - size / 2 |
| 457 | self.sf.yview('moveto', middle) |
| 458 | |
| 459 | </pre> |
| 460 | </dd> |
| 461 | </dl> |
| 462 | |
| 463 | <center><P ALIGN="CENTER"> |
| 464 | <IMG SRC = blue_line.gif ALT = "" WIDTH=320 HEIGHT=5> |
| 465 | </p></center> |
| 466 | |
| 467 | |
| 468 | <font size=-1> |
| 469 | <center><P ALIGN="CENTER"> |
| 470 | Pmw 1.2 - |
| 471 | 5 Aug 2003 |
| 472 | - <a href="index.html">Home</a> |
| 473 | <br>Manual page last reviewed: 18 February 2001 |
| 474 | </p></center> |
| 475 | </font> |
| 476 | |
| 477 | </body> |
| 478 | </html> |
| 479 | |