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.HistoryText 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.HistoryText</h1> | |
13 | ||
14 | <center><IMG SRC=HistoryText.gif ALT="" WIDTH=551 HEIGHT=142></center> | |
15 | <dl> | |
16 | <dt> <h3>Name</h3></dt><dd> | |
17 | <p>Pmw.HistoryText() - | |
18 | text widget with a course-grained form of history | |
19 | </p> | |
20 | ||
21 | ||
22 | </dd> | |
23 | <dt> <h3>Inherits</h3></dt><dd> | |
24 | <a href="ScrolledText.html">Pmw.ScrolledText</a><br> | |
25 | </dd> | |
26 | <dt> <h3>Description</h3></dt><dd> | |
27 | <p> | |
28 | A history text is a scrolled text widget with added functionality | |
29 | to maintain a history of each screen and allow editing of prior | |
30 | screens. Here, <em>screen</em> refers to the entire contents of the text | |
31 | widget. This widget does not support a fine-grained history of | |
32 | every change made to the text.</p> | |
33 | ||
34 | <p> Together with a few buttons and a scrolled text to display the | |
35 | results, a history text can be used as the query-entry part of a | |
36 | simple interactive text-based database query system. When the | |
37 | user enters and executes a query, the query (the entire contents | |
38 | of the text widget) is added to the history list. The user may | |
39 | view previous queries and either execute them again or modify them | |
40 | and execute the new query. If a previously executed query is | |
41 | modified, the user may undo or redo all changes made to the query | |
42 | <em>before the query is executed</em>.</p> | |
43 | ||
44 | <p></p> | |
45 | ||
46 | ||
47 | </dd> | |
48 | <dt> <h3>Options</h3></dt><dd> | |
49 | Options for this megawidget and its base | |
50 | classes are described below.<p></p> | |
51 | <a name=option.borderframe></a> | |
52 | <dl><dt> <strong>borderframe | |
53 | </strong></dt><dd> | |
54 | Initialisation option. If true, the <strong>borderframe</strong> component will be created. The default is <strong>0</strong>.</p> | |
55 | ||
56 | ||
57 | </dd></dl> | |
58 | <a name=option.columnheader></a> | |
59 | <dl><dt> <strong>columnheader | |
60 | </strong></dt><dd> | |
61 | Initialisation option. If true, the <strong>columnheader</strong> component will be created. The default is <strong>0</strong>.</p> | |
62 | ||
63 | ||
64 | </dd></dl> | |
65 | <a name=option.compressany></a> | |
66 | <dl><dt> <strong>compressany | |
67 | </strong></dt><dd> | |
68 | See <code>addhistory()</code>. The default is <strong>1</strong>.</p> | |
69 | ||
70 | ||
71 | </dd></dl> | |
72 | <a name=option.compresstail></a> | |
73 | <dl><dt> <strong>compresstail | |
74 | </strong></dt><dd> | |
75 | See <code>addhistory()</code>. The default is <strong>1</strong>.</p> | |
76 | ||
77 | ||
78 | </dd></dl> | |
79 | <a name=option.historycommand></a> | |
80 | <dl><dt> <strong>historycommand | |
81 | </strong></dt><dd> | |
82 | This is a callback to indicate whether the currently displayed | |
83 | entry in the history list has a previous or next entry. The | |
84 | callback is given two arguments, <em>prevstate</em> and <em>nextstate</em>. If | |
85 | the currently displayed entry is first in the history list, then | |
86 | <em>prevstate</em> is <strong>'disabled'</strong>, otherwise it is <strong>'normal'</strong>. If the | |
87 | currently displayed entry is last in the history list, then | |
88 | <em>nextstate</em> is <strong>'disabled'</strong>, otherwise it is <strong>'normal'</strong>. These | |
89 | values can be used, for example, to modify the state of <strong>Next</strong> and | |
90 | <strong>Previous</strong> buttons that call the <code>next()</code> and <code>prev()</code> methods. The default is <strong>None</strong>.</p> | |
91 | ||
92 | ||
93 | </dd></dl> | |
94 | <a name=option.hscrollmode></a> | |
95 | <dl><dt> <strong>hscrollmode | |
96 | </strong></dt><dd> | |
97 | The horizontal scroll mode. If <strong>'none'</strong>, the horizontal scrollbar | |
98 | will never be displayed. If <strong>'static'</strong>, the scrollbar will always | |
99 | be displayed. If <strong>'dynamic'</strong>, the scrollbar will be displayed | |
100 | only if necessary. The default is <strong>'dynamic'</strong>.</p> | |
101 | ||
102 | ||
103 | </dd></dl> | |
104 | <a name=option.labelmargin></a> | |
105 | <dl><dt> <strong>labelmargin | |
106 | </strong></dt><dd> | |
107 | Initialisation option. If the <strong>labelpos</strong> option is not <strong>None</strong>, this specifies the | |
108 | distance between the <strong>label</strong> component and the rest of the | |
109 | megawidget. The default is <strong>0</strong>.</p> | |
110 | ||
111 | ||
112 | </dd></dl> | |
113 | <a name=option.labelpos></a> | |
114 | <dl><dt> <strong>labelpos | |
115 | </strong></dt><dd> | |
116 | Initialisation option. Specifies where to place the <strong>label</strong> component. If not | |
117 | <strong>None</strong>, it should be a concatenation of one or two of the | |
118 | letters <strong>'n'</strong>, <strong>'s'</strong>, <strong>'e'</strong> and <strong>'w'</strong>. The first letter | |
119 | specifies on which side of the megawidget to place the label. | |
120 | If a second letter is specified, it indicates where on that | |
121 | side to place the label. For example, if <strong>labelpos</strong> is <strong>'w'</strong>, | |
122 | the label is placed in the center of the left hand side; if | |
123 | it is <strong>'wn'</strong>, the label is placed at the top of the left | |
124 | hand side; if it is <strong>'ws'</strong>, the label is placed at the | |
125 | bottom of the left hand side.</p> | |
126 | <p> If <strong>None</strong>, a label component is not created. The default is <strong>None</strong>.</p> | |
127 | ||
128 | ||
129 | ||
130 | </dd></dl> | |
131 | <a name=option.rowcolumnheader></a> | |
132 | <dl><dt> <strong>rowcolumnheader | |
133 | </strong></dt><dd> | |
134 | Initialisation option. If true, the <strong>rowcolumnheader</strong> component will be created. The default is <strong>0</strong>.</p> | |
135 | ||
136 | ||
137 | </dd></dl> | |
138 | <a name=option.rowheader></a> | |
139 | <dl><dt> <strong>rowheader | |
140 | </strong></dt><dd> | |
141 | Initialisation option. If true, the <strong>rowheader</strong> component will be created. The default is <strong>0</strong>.</p> | |
142 | ||
143 | ||
144 | </dd></dl> | |
145 | <a name=option.scrollmargin></a> | |
146 | <dl><dt> <strong>scrollmargin | |
147 | </strong></dt><dd> | |
148 | Initialisation option. The distance between the scrollbars and the text widget. The default is <strong>2</strong>.</p> | |
149 | ||
150 | ||
151 | </dd></dl> | |
152 | <a name=option.usehullsize></a> | |
153 | <dl><dt> <strong>usehullsize | |
154 | </strong></dt><dd> | |
155 | Initialisation option. If true, the size of the megawidget is determined solely by the | |
156 | width and height options of the <strong>hull</strong> component.</p> | |
157 | <p> Otherwise, the size of the megawidget is determined by the width | |
158 | and height of the <strong>text</strong> component, along with the size and/or | |
159 | existence of the other components, such as the label, the | |
160 | scrollbars and the scrollmargin option. All these affect the | |
161 | overall size of the megawidget. The default is <strong>0</strong>.</p> | |
162 | ||
163 | ||
164 | ||
165 | </dd></dl> | |
166 | <a name=option.vscrollmode></a> | |
167 | <dl><dt> <strong>vscrollmode | |
168 | </strong></dt><dd> | |
169 | The vertical scroll mode. If <strong>'none'</strong>, the vertical scrollbar | |
170 | will never be displayed. If <strong>'static'</strong>, the scrollbar will always | |
171 | be displayed. If <strong>'dynamic'</strong>, the scrollbar will be displayed | |
172 | only if necessary. The default is <strong>'dynamic'</strong>.</p> | |
173 | ||
174 | ||
175 | </dd></dl> | |
176 | </dd> | |
177 | <dt> <h3>Components</h3></dt><dd> | |
178 | Components created by this megawidget and its base | |
179 | classes are described below.<p></p> | |
180 | <a name=component.borderframe></a> | |
181 | <dl><dt> <strong>borderframe | |
182 | </strong></dt><dd> | |
183 | A frame widget which snuggly fits around the text widget, to give | |
184 | the appearance of a text border. It is created with a border so | |
185 | that the text widget, which is created without a border, looks | |
186 | like it has a border. By default, this component is a Tkinter.Frame.</p> | |
187 | ||
188 | ||
189 | </dd></dl> | |
190 | <a name=component.columnheader></a> | |
191 | <dl><dt> <strong>columnheader | |
192 | </strong></dt><dd> | |
193 | A text widget with a default height of 1 displayed above the main | |
194 | text widget and which scrolls horizontally in sync with the | |
195 | horizontal scrolling of the main text widget. By default, this component is a Tkinter.Text. Its component group is <strong>Header</strong>.</p> | |
196 | ||
197 | ||
198 | </dd></dl> | |
199 | <a name=component.horizscrollbar></a> | |
200 | <dl><dt> <strong>horizscrollbar | |
201 | </strong></dt><dd> | |
202 | The horizontal scrollbar. By default, this component is a Tkinter.Scrollbar. Its component group is <strong>Scrollbar</strong>.</p> | |
203 | ||
204 | ||
205 | </dd></dl> | |
206 | <a name=component.hull></a> | |
207 | <dl><dt> <strong>hull | |
208 | </strong></dt><dd> | |
209 | This acts as the body for the entire megawidget. Other components | |
210 | are created as children of the hull to further specialise this | |
211 | class. By default, this component is a Tkinter.Frame.</p> | |
212 | ||
213 | ||
214 | </dd></dl> | |
215 | <a name=component.label></a> | |
216 | <dl><dt> <strong>label | |
217 | </strong></dt><dd> | |
218 | If the <strong>labelpos</strong> option is not <strong>None</strong>, this component is | |
219 | created as a text label for the megawidget. See the | |
220 | <strong>labelpos</strong> option for details. Note that to set, for example, | |
221 | the <strong>text</strong> option of the label, you need to use the <strong>label_text</strong> | |
222 | component option. By default, this component is a Tkinter.Label.</p> | |
223 | ||
224 | ||
225 | </dd></dl> | |
226 | <a name=component.rowcolumnheader></a> | |
227 | <dl><dt> <strong>rowcolumnheader | |
228 | </strong></dt><dd> | |
229 | A text widget displayed to the top left of the main text widget, | |
230 | above the row header and to the left of the column header if they | |
231 | exist. The widget is not scrolled automatically. By default, this component is a Tkinter.Text. Its component group is <strong>Header</strong>.</p> | |
232 | ||
233 | ||
234 | </dd></dl> | |
235 | <a name=component.rowheader></a> | |
236 | <dl><dt> <strong>rowheader | |
237 | </strong></dt><dd> | |
238 | A text widget displayed to the left of the main text widget and | |
239 | which scrolls vertically in sync with the vertical scrolling of | |
240 | the main text widget. By default, this component is a Tkinter.Text. Its component group is <strong>Header</strong>.</p> | |
241 | ||
242 | ||
243 | </dd></dl> | |
244 | <a name=component.text></a> | |
245 | <dl><dt> <strong>text | |
246 | </strong></dt><dd> | |
247 | The text widget which is scrolled by the scrollbars. If the | |
248 | <strong>borderframe</strong> option is true, this is created with a borderwidth | |
249 | of <strong>0</strong> to overcome a known problem with text widgets: if a widget | |
250 | inside a text widget extends across one of the edges of the text | |
251 | widget, then the widget obscures the border of the text widget. | |
252 | Therefore, if the text widget has no border, then this overlapping | |
253 | does not occur. By default, this component is a Tkinter.Text.</p> | |
254 | ||
255 | ||
256 | </dd></dl> | |
257 | <a name=component.vertscrollbar></a> | |
258 | <dl><dt> <strong>vertscrollbar | |
259 | </strong></dt><dd> | |
260 | The vertical scrollbar. By default, this component is a Tkinter.Scrollbar. Its component group is <strong>Scrollbar</strong>.</p> | |
261 | ||
262 | ||
263 | </dd></dl> | |
264 | </dd> | |
265 | <a name=methods></a> | |
266 | <dt> <h3>Methods</h3></dt><dd> | |
267 | Only methods specific to this megawidget are described below. | |
268 | For a description of its inherited methods, see the | |
269 | manual for its base class | |
270 | <strong><a href="ScrolledText.html#methods">Pmw.ScrolledText</a></strong>. | |
271 | <p></p> | |
272 | <a name=method.addhistory></a> | |
273 | <dl><dt> <strong>addhistory</strong>()</dt><dd> | |
274 | Append the currently displayed text to the history list.</p> | |
275 | <p> If <strong>compressany</strong> is true, a new entry will be added to the history | |
276 | list only if the currently displayed entry has changed.</p> | |
277 | ||
278 | <p> If <strong>compresstail</strong> is true, a new entry will be added to the | |
279 | history list only if the currently displayed entry has changed | |
280 | <em>or</em> if it is not the last entry in the history list.</p> | |
281 | ||
282 | ||
283 | ||
284 | </dd></dl> | |
285 | <a name=method.gethistory></a> | |
286 | <dl><dt> <strong>gethistory</strong>()</dt><dd> | |
287 | Return the history list. Each entry in the list is a 3-tuple. | |
288 | The first item in a history entry is the original text as added by | |
289 | <code>addhistory()</code>. The second item is the edited text (if the user | |
290 | has modified the entry but <code>addhistory()</code> has not yet been called | |
291 | on the text). The third item specifies whether the entry should | |
292 | currently display the original or modified text.</p> | |
293 | ||
294 | ||
295 | </dd></dl> | |
296 | <a name=method.next></a> | |
297 | <dl><dt> <strong>next</strong>()</dt><dd> | |
298 | Display the next screen in the history list.</p> | |
299 | ||
300 | ||
301 | </dd></dl> | |
302 | <a name=method.prev></a> | |
303 | <dl><dt> <strong>prev</strong>()</dt><dd> | |
304 | Display the previous screen in the history list.</p> | |
305 | ||
306 | ||
307 | </dd></dl> | |
308 | <a name=method.redo></a> | |
309 | <dl><dt> <strong>redo</strong>()</dt><dd> | |
310 | Reverse the effect of <code>undo()</code>.</p> | |
311 | ||
312 | ||
313 | </dd></dl> | |
314 | <a name=method.undo></a> | |
315 | <dl><dt> <strong>undo</strong>()</dt><dd> | |
316 | Undo all changes made since this entry was added to the history | |
317 | list.</p> | |
318 | ||
319 | ||
320 | </dd></dl> | |
321 | </dd> | |
322 | <dt> <h3>Example</h3></dt><dd> | |
323 | The image at the top of this manual is a snapshot | |
324 | of the window (or part of the window) produced | |
325 | by the following code.<p></p> | |
326 | <pre> | |
327 | class Demo: | |
328 | def __init__(self, parent): | |
329 | # Create and pack the PanedWidget to hold the query and result | |
330 | # windows. | |
331 | # !! panedwidget should automatically size to requested size | |
332 | panedWidget = Pmw.PanedWidget(parent, | |
333 | orient = 'vertical', | |
334 | hull_height = 400, | |
335 | hull_width = 550) | |
336 | panedWidget.add('query', min = 0.05, size = 0.2) | |
337 | panedWidget.add('buttons', min = 0.1, max = 0.1) | |
338 | panedWidget.add('results', min = 0.05) | |
339 | panedWidget.pack(fill = 'both', expand = 1) | |
340 | ||
341 | # Create and pack the HistoryText. | |
342 | self.historyText = Pmw.HistoryText(panedWidget.pane('query'), | |
343 | text_wrap = 'none', | |
344 | text_width = 60, | |
345 | text_height = 10, | |
346 | historycommand = self.statechange, | |
347 | ) | |
348 | self.historyText.pack(fill = 'both', expand = 1) | |
349 | self.historyText.component('text').focus() | |
350 | ||
351 | buttonList = ( | |
352 | [20, None], | |
353 | ['Clear', self.clear], | |
354 | ['Undo', self.historyText.undo], | |
355 | ['Redo', self.historyText.redo], | |
356 | [20, None], | |
357 | ['Prev', self.historyText.prev], | |
358 | ['Next', self.historyText.next], | |
359 | [30, None], | |
360 | ['Execute', Pmw.busycallback(self.executeQuery)], | |
361 | ) | |
362 | self.buttonDict = {} | |
363 | ||
364 | buttonFrame = panedWidget.pane('buttons') | |
365 | for text, cmd in buttonList: | |
366 | if type(text) == type(69): | |
367 | frame = Tkinter.Frame(buttonFrame, width = text) | |
368 | frame.pack(side = 'left') | |
369 | else: | |
370 | button = Tkinter.Button(buttonFrame, text = text, command = cmd) | |
371 | button.pack(side = 'left') | |
372 | self.buttonDict[text] = button | |
373 | ||
374 | for text in ('Prev', 'Next'): | |
375 | self.buttonDict[text].configure(state = 'disabled') | |
376 | ||
377 | self.results = Pmw.ScrolledText(panedWidget.pane('results'), text_wrap = 'none') | |
378 | self.results.pack(fill = 'both', expand = 1) | |
379 | ||
380 | def statechange(self, prevstate, nextstate): | |
381 | self.buttonDict['Prev'].configure(state = prevstate) | |
382 | self.buttonDict['Next'].configure(state = nextstate) | |
383 | ||
384 | def clear(self): | |
385 | self.historyText.delete('1.0', 'end') | |
386 | ||
387 | def addnewlines(self, text): | |
388 | if len(text) == 1: | |
389 | text = text + '\n' | |
390 | if text[-1] != '\n': | |
391 | text = text + '\n' | |
392 | if text[-2] != '\n': | |
393 | text = text + '\n' | |
394 | return text | |
395 | ||
396 | def executeQuery(self): | |
397 | sql = self.historyText.get() | |
398 | self.results.insert('end', 'Query:\n' + self.addnewlines(sql)) | |
399 | self.results.see('end') | |
400 | self.results.update_idletasks() | |
401 | self.historyText.addhistory() | |
402 | results = 'Results:\nfoo' | |
403 | if len(results) > 0: | |
404 | self.results.insert('end', self.addnewlines(results)) | |
405 | self.results.see('end') | |
406 | ||
407 | </pre> | |
408 | </dd> | |
409 | </dl> | |
410 | ||
411 | <center><P ALIGN="CENTER"> | |
412 | <IMG SRC = blue_line.gif ALT = "" WIDTH=320 HEIGHT=5> | |
413 | </p></center> | |
414 | ||
415 | ||
416 | <font size=-1> | |
417 | <center><P ALIGN="CENTER"> | |
418 | Pmw 1.2 - | |
419 | 5 Aug 2003 | |
420 | - <a href="index.html">Home</a> | |
421 | <br>Manual page last reviewed: 20 May 2002 | |
422 | </p></center> | |
423 | </font> | |
424 | ||
425 | </body> | |
426 | </html> | |
427 |