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