Pmw/Pmw_1_2/doc/HistoryText.html

   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) &gt; 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