1. Abstract

In my continuing efforts to make the Text widget more useable I have created EnhancedText. This widget is a subclass of Text which reimplements all of the event handling of the text widget to correct for some minor problems. This widget is intended to work as a drop-in replacement for Text.

2. The Problem

The Text widget as supplied by Tkinter is an amazingly powerful widget. Yet once you begin to use it, you discover that it has some quirks. These quirks are minor in the sense that they aren't bugs, your data won't be corrupted. However, they are major enough to actually make you reconsider using the widget altogether. These involve navigation on the part of the user. Much like a word processor, the text widget is paragraph oriented rather than line oriented. This means that the widget will handle such things as line wrapping and justification. However, if you attempt to move the carrot (the editing cursor) around the contents of the widget using the arrow keys, something very annoying will quickly become apparent. When moving up or down, the carrot jumps from paragraph to paragraph rather than display-line to display-line. This can be a problem with long paragraphs because it can take some time to navigate to a desired location without the use of a mouse. In this same theme, the 'Home' and 'End' keys don't move the carrot to the beginning and end of a display-line but the beginning and end of a paragraph. EnhancedText is an attempt to correct this.

This fix applies to Tkinter for Tk 8.4 and before. To my knowledge these problems are corrected in Tk 8.5.

3. Enhanced API

EnhancedText is a subclass of Text and all superclass methods are safe to use unchanged. EnhancedText also introduces four new methods. t.dline_prev( index ), t.dline_next( index ), t.dline_start( index ) and t.dline_end( index ). Each returns an index to a location relative to the index provided. _prev returns the index one display-line up from the argument _next returns the index one display-line down. _start returns the index of the first character on the display-line of the argument _end returns the index of the last character on the display line of the argument. The _prev and _next methods include an additional useThisX argument. If provided, the returned index with be based upon the X coordinate provided (pixels from the left edge). If omitted, the x returned from calling bbox on the index argument will be used.

The remaining methods in the class are intended to support the implementation though should be usable with little fear of corrupting the object's state.

4. Known Issues

* Pressing 'End' or calling dline_end will return the index of the last character on a display line. Consequently, the carror, being repositioned using the 'End' key is actually placed before the last character of the display line. For some, currently unknown reason, setting EnhancedText's wrap option to WORD produces the expected behavior, the carrot moves after the last character on the display line.

* This widget has only been tested on Windows XP.

5. Acknowledgements

* The Controller class and bind decorator function come directly from Fredrik Lundh's

Tkinter Controller Module. Thanks Fredrik!

6. Code

   1 
  2 
  3 
  4 
  5 
  6 
  7 
  8 
  9 
 10 
 11 
 12 
 13 
 14 
 15 
 16 
 17 
 18 
 19 
 20 
 21 
 22 
 23 
 24 
 25 
 26 
 27 
 28 
 29 
 30 
 31 
 32 
 33 
 34 
 35 
 36 
 37 
 38 
 39 
 40 
 41 
 42 
 43 
 44 
 45 
 46 
 47 
 48 
 49 
 50 
 51 
 52 
 53 
 54 
 55 
 56 
 57 
 58 
 59 
 60 
 61 
 62 
 63 
 64 
 65 
 66 
 67 
 68 
 69 
 70 
 71 
 72 
 73 
 74 
 75 
 76 
 77 
 78 
 79 
 80 
 81 
 82 
 83 
 84 
 85 
 86 
 87 
 88 
 89 
 90 
 91 
 92 
 93 
 94 
 95 
 96 
 97 
 98 
 99 
100 
101 
102 
103 
104 
105 
106 
107 
108 
109 
110 
111 
112 
113 
114 
115 
116 
117 
118 
119 
120 
121 
122 
123 
124 
125 
126 
127 
128 
129 
130 
131 
132 
133 
134 
135 
136 
137 
138 
139 
140 
141 
142 
143 
144 
145 
146 
147 
148 
149 
150 
151 
152 
153 
154 
155 
156 
157 
158 
159 
160 
161 
162 
163 
164 
165 
166 
167 
168 
169 
170 
171 
172 
173 
174 
175 
176 
177 
178 
179 
180 
181 
182 
183 
184 
185 
186 
187 
188 
189 
190 
191 
192 
193 
194 
195 
196 
197 
198 
199 
200 
201 
202 
203 
204 
205 
206 
207 
208 
209 
210 
211 
212 
213 
214 
215 
216 
217 
218 
219 
220 
221 
222 
223 
224 
225 
226 
227 
228 
229 
230 
231 
232 
233 
234 
235 
236 
237 
238 
239 
240 
241 
242 
243 
244 
245 
246 
247 
248 
249 
250 
251 
252 
253 
254 
255 
256 
257 
258 
259 
260 
261 
262 
263 
264 
265 
266 
267 
268 
269 
270 
271 
272 
273 
274 
275 
276 
277 
278 
279 
280 
281 
282 
283 
284 
285 
286 
287 
288 
289 
290 
291 
292 
293 
294 
295 
296 
297 
298 
299 
300 
301 
302 
303 
304 
305 
306 
307 
308 
309 
310 
311 
312 
313 
314 
315 
316 
317 
318 
319 
320 
321 
322 
323 
324 
325 
326 
327 
328 
329 
330 
331 
332 
333 
334 
335 
336 
337 
338 
339 
340 
341 
342 
343 
344 
345 
346 
347 
348 
349 
350 
351 
352 
353 
354 
355 
356 
357 
358 
359 
360 
361 
362 
363 
364 
365 
366 
367 
368 
369 
370 
371 
372 
373 
374 
375 
376 
377 
378 
379 
380 
381 
382 
383 
384 
385 
386 
387 
388 
389 
390 
391 
392 
393 
394 
395 
396 
397 
398 
399 
400 
401 
402 
403 
404 
405 
406 
407 
408 
409 
410 
411 
412 
413 
414 
415 
416 
417 
418 
419 
420 
421 
422 
423 
424 
425 
426 
427 
428 
429 
430 
431 
432 
433 
434 
435 
436 
437 
438 
439 
440 
441 
442 
443 
444 
445 
446 
447 
448 
449 
450 
451 
452 
453 
454 
455 
456 
457 
458 
459 
460 
461 
462 
463 
464 
465 
466 
467 
468 
469 
470 
471 
472 
473 
474 
475 
476 
477 
478 
479 
480 
481 
482 
483 
484 
import Tkinter

PREFIX = "tkController"

class Controller(object):
   def __init__(self, master=None):
      if master is None:
         master = Tkinter._default_root
      assert master is not None
      self.tag = PREFIX + str(id(self))
      def bind(event, handler):
         master.bind_class(self.tag, event, handler)
      self.create(bind)

   def install(self, widget):
      widgetclass = widget.winfo_class()
      # remove widget class bindings and other controllers
      tags = [self.tag]
      for tag in widget.bindtags():
         if tag != widgetclass and tag[:len(PREFIX)] != PREFIX:
            tags.append(tag)
      widget.bindtags(tuple(tags))

   def create(self, handle):
      # override if necessary
      # the default implementation looks for decorated methods
      for key in dir(self):
         method = getattr(self, key)
         if hasattr(method, "tkevent") and callable(method):
            for eventSequence in method.tkevent:
               handle(eventSequence, method)

def bind(*events):
   def decorator(func):
      func.tkevent = events
      return func
   return decorator

class KBController( Controller ):
   '''This class watches keypress events and records presses and releases of 
   keys used for key combinations (shift, alt, control, etc.).  When one of
   these keys is held down, this class's corresponding state variable is set
   to True.'''
   def __init__( self ):
      Controller.__init__( self )
      self._alt     = False
      self._control = False
      self._lock    = False
      self._meta    = False
      self._shift   = False

   @bind("<KeyPress>")      # type 2
   def KeyPress(self, event):
      if event.keysym in ('Alt_L', 'Alt_R'):
         self._alt = True
      elif event.keysym in ('Control_L', 'Control_R'):
         self._control = True
      elif event.keysym == 'Caps_Lock':
         self._lock = True
      elif event.keysym in ('Meta_L', 'Meta_R'):
         self._meta = True
      elif event.keysym in ( 'Shift_L', 'Shift_R'):
         self._shift = True
      elif (len(event.char) > 0) and (32 <= ord(event.char) <= 127):
         self.onTypedCharacterKey( event )
      else:
         self.onTypedSpecialKey( event )

   @bind("<KeyRelease>")   # type 3
   def KeyRelease( self, event ):
      if event.keysym in ('Alt_L', 'Alt_R'):
         self._alt = False
      elif event.keysym in ('Control_L', 'Control_R'):
         self._control = False
      elif event.keysym == 'Caps_Lock':
         self._lock = False
      elif event.keysym in ('Meta_L', 'Meta_R'):
         self._meta = False
      elif event.keysym in ('Shift_L', 'Shift_R'):
         self._shift = False

   def onTypedCharacterKey( self, event ):
      '''Override to handle typing of any printable keyboard character,
      The typed character is in event.char (which accounts for shift).'''
      pass

   def onTypedSpecialKey( self, event ):
      '''Override to handle typing of any special characters (tab, \n, backspace,
      delete, home, prior, insert, etc.  And any key combinations involving
      Alt or Control.'''
      pass


class EnhancedTextController( KBController ):
   def __init__( self ):
      KBController.__init__( self )
      self._insert_x_pos    = None

   def onTypedCharacterKey( self, event ):
      try:
         event.widget.sel_delete( )
      except:
         pass

      event.widget.insert( 'insert', event.char )
      event.widget.sel_clear( )

      self._insert_x_pos = event.widget.bbox( 'insert' )[0]

   def moveCarrot( self, event ):
      widget = event.widget

      if self._shift:
         if not widget.sel_isAnchorSet():
            widget.sel_setAnchor( 'insert' )
      else:
         widget.sel_clear( )

      if event.keysym in ( 'Home', 'KP_Home' ):
         if self._control:
            # Move to beginning of text
            widget.mark_set( 'insert', '1.0' )
         else:
            # Move to front of line
            widget.mark_set( 'insert', widget.dline_start('insert') )
      elif event.keysym in ( 'End', 'KP_End' ):
         if self._control:
            # Move to end of text
            widget.mark_set( 'insert', 'end' )
         else:
            # Move to end of line
            widget.mark_set( 'insert', widget.dline_end('insert') )
      elif event.keysym == 'Right':
         if self._control:
            # Move by word
            currentPos = widget.index( 'insert' )
            maxPos     = widget.index( 'end wordstart' )

            if currentPos == maxPos:
               return

            offset = 1
            while widget.compare( currentPos, '==', widget.index('insert') ):
               widget.mark_set( 'insert', 'insert wordend +%dc wordstart' % offset )
               offset += 1
         else:
            # Move by character
            widget.mark_set( 'insert', 'insert +1 chars' )
      elif event.keysym == 'Left':
         if self._control:
            # Move by word
            currentPos = widget.index( 'insert' )
            minPos     = widget.index( '1.0 wordstart' )

            if currentPos == minPos:
               return

            offset = 2
            widget.mark_set( 'insert', 'insert wordstart' )
            while widget.compare( currentPos, '==', widget.index('insert') ):
               widget.mark_set( 'insert', 'insert -%dc wordstart' % offset )
               offset += 1
         else:
            # Move by character
            widget.mark_set( 'insert', 'insert -1 chars' )
      elif event.keysym == 'Down':
         if self._control:
            # Move by Paragraph
            widget.mark_set( 'insert', 'insert +1 lines' )
         else:
            # Move by line
            widget.mark_set( 'insert', widget.dline_next( 'insert', useThisX=self._insert_x_pos ) )
      elif event.keysym == 'Up':
         if self._control:
            # Move by Paragraph
            widget.mark_set( 'insert', 'insert -1 lines' )
            pass
         else:
            # Move by line
            widget.mark_set( 'insert', widget.dline_prev( 'insert', useThisX=self._insert_x_pos ) )
      elif event.keysym == 'Prior':
         if self._control:
            pass
         else:
            # Move by page
            event.widget.yview_scroll( -1, 'pages' )
      elif event.keysym == 'Next':
         if self._control:
            pass
         else:
            # Move by page
            event.widget.yview_scroll( 1, 'pages' )

      widget.see( 'insert' )

      if event.keysym not in ('Up','Down'):
         self._insert_x_pos = event.widget.bbox( 'insert' )[0]

   def typeSpecial( self, event ):
      widget = event.widget

      if event.keysym in ( 'Return', 'Enter', 'KP_Enter' ):
         try:
            widget.sel_delete( )
         finally:
            widget.insert( 'insert', '\n' )
      elif event.keysym == 'Tab':
         widget.insert( 'insert', '\t' )
      elif event.keysym == 'BackSpace':
         try:
            widget.delete( 'sel.first', 'sel.last' )
         except:
            widget.delete( 'insert -1 chars', 'insert' )
      elif event.keysym in ( 'Delete', 'KP_Delete' ):
         try:
            widget.delete( 'sel.first', 'sel.last' )
         except:
            widget.delete( 'insert', 'insert +1 chars' )

      widget.sel_clear()
      self._insert_x_pos = event.widget.bbox( 'insert' )[0]

   def onTypedSpecialKey( self, event ):
      widget = event.widget

      if event.keysym in ( 'Return','Enter','KP_Enter','Tab','BackSpace','Delete','Insert' ):
         self.typeSpecial( event )

      elif event.keysym in ( 'Up', 'Down', 'Left', 'Right', 'Home', 'End', 'Prior', 'Next'
                             'KP_Up', 'KP_Down', 'KP_Left', 'KP_Right', 'KP_Home', 'KP_End', 'KP_Prior', 'KP_Next' ):
         self.moveCarrot( event )

      elif self._control:
         if event.keysym == 'a':
            # select all
            self._selectionAnchor = '1.0'
            widget.mark_set( 'insert', 'end' )
         elif event.keysym == 'c':
            # copy
            try:
               widget.clipboard_append( widget.get( 'sel.first', 'sel.last' ) )
            except:
               pass
         elif event.keysym == 'r':
            # Redo
            try:
               widget.edit_redo( )
            except:
               pass
            widget.sel_clear( )
         elif event.keysym == 'v':
            # paste
            try:
               widget.mark_set( 'insert', 'sel.first' )
               widget.delete( 'sel.first', 'sel.last' )
            except:
               pass

            widget.insert( 'insert', widget.clipboard_get( ) )
            self.sel_clear( )
         elif event.keysym == 'x':
            # cut
            try:
               widget.clipboard_append( widget.get( 'sel.first', 'sel.last' ) )
               widget.delete( 'sel.first', 'sel.last' )
               widget.ins_updateTags( )
            except:
               pass
            widget.sel_clear( )
         elif event.keysym == 'z':
            # Undo
            try:
               widget.edit_undo( )
            except:
               pass
            widget.sel_clear( )

         self._insert_x_pos = event.widget.bbox( 'insert' )[0]

   @bind( '<ButtonPress-1>' )
   def click( self, event ):
      event.widget.focus_set( )

      if not self._shift and not self._control:
         event.widget.sel_clear( )
         event.widget.sel_setAnchor( 'current' )

      self._insert_x_pos = event.x

   @bind( '<B1-Motion>', '<Shift-Button1-Motion>' )
   def dragSelection( self, event ):
      widget = event.widget

      if event.y < 0:
         widget.yview_scroll( -1, 'units' )
      elif event.y >= widget.winfo_height():
         widget.yview_scroll( 1, 'units' )

      if not widget.sel_isAnchorSet( ):
         widget.self_setAnchor( '@%d,%d' % (event.x+2, event.y) )

      widget.mark_set( 'insert', '@%d,%d' % (event.x+2, event.y) )
      self._insert_x_pos = event.x

   @bind( '<ButtonRelease-1>' )
   def moveCarrot_deselect( self, event ):
      widget = event.widget

      widget.grab_release()
      widget.mark_set( 'insert', 'current' )
      self._insert_x_pos = event.x

   @bind( '<Double-ButtonPress-1>' )
   def selectWord( self, event ):
      event.widget.sel_setAnchor( 'insert wordstart' )
      event.widget.mark_set( 'insert', 'insert wordend' )
      self._insert_x_pos = event.x

   @bind( '<Triple-ButtonPress-1>' )
   def selectLine( self, event ):
      event.widget.sel_setAnchor( 'insert linestart' )
      event.widget.mark_set( 'insert', 'insert lineend' )
      self._insert_x_pos = event.x

   @bind( '<Button1-Leave>' )
   def scrollView( self, event ):
      widget = event.widget

      if event.y < 0:
         widget.yview_scroll( -1, 'units' )
      elif event.y >= widget.winfo_height():
         widget.yview_scroll( 1, 'units' )

      widget.grab_set( )

   @bind( '<MouseWheel>' )
   def wheelScroll( self, event ):
      widget = event.widget

      if event.delta < 0:
         widget.yview_scroll( 1, 'units' )
      else:
         widget.yview_scroll( -1, 'units' )


class EnhancedText( Tkinter.Text ):
   def __init__( self, parent, **options ):
      Tkinter.Text.__init__( self, parent, **options )

      controller = EnhancedTextController( )
      controller.install( self )

   # Selection Operations
   def sel_clear( self ):
      try:
         self.tag_remove( 'sel', '1.0', 'end' )
      except:
         pass

      try:
         self.mark_unset( 'sel.anchor', 'sel.first', 'sel.last' )
      except:
         pass

   def sel_setAnchor( self, index ):
      self.mark_set( 'sel.anchor', index )

   def sel_isAnchorSet( self ):
      try:
         self.index( 'sel.anchor' )
         return True
      except:
         return False

   def sel_isSelection( self ):
      try:
         self.index( 'sel.first' )
         return True
      except:
         return False

   def sel_update( self ):
      if widget.compare( 'sel.anchor', '<', 'insert' ):
         widget.mark_set( 'sel.first', 'sel.anchor' )
         widget.mark_set( 'sel.last', 'insert' )
      elif widget.compare( 'sel.anchor', '>', 'insert' ):
         widget.mark_set( 'sel.first', 'insert' )
         widget.mark_set( 'sel.last', 'sel.anchor' )
      else:
         return

      widget.tag_remove( 'sel', '1.0', 'end' )
      widget.tag_add( 'sel', 'sel.first', 'sel.last' )

   def sel_delete( self ):
      try:
         Tkinter.Text.delete( self, 'sel.first', 'sel.last' )
      except:
         pass
      self.sel_clear( )

   # Display Lines
   def dline_prev( self, index, useThisX=None ):
      delta = 10
      spacing = self.bbox( self.index( '@1,1' ) )[1]
      minY = delta + spacing

      x,y,width,height = self.bbox( index )

      if useThisX:
         x = useThisX

      insertIndex = self.index( index )
      newIndex = self.index( '@%d,%d' % ( x, y ) )
      while (self.compare( newIndex, '==', insertIndex)) and (self.compare( newIndex, '>', '1.0' )):
         if y < delta:
            self.yview_scroll( -1, 'units' )
            x,y,width,height = self.bbox( insertIndex )
         y -= delta
         newIndex = self.index( '@%d,%d' % ( x, y ) )

         if self.index('@1,1') == '1.0':
            lastIndexOnTopDisplayLine = self.dline_end( '1.0' )
            if self.compare( newIndex, '<=', lastIndexOnTopDisplayLine ):
               break

      return newIndex

   def dline_next( self, index, useThisX=None ):
      delta = 10

      x,y,width,height = self.bbox( index )
      insertIndex = self.index( index )

      if useThisX:
         x = useThisX

      newIndex = self.index( '@%d,%d' % ( x, y ) )
      while (self.compare( newIndex, '==', insertIndex)) and (self.compare( newIndex, '<', 'end -1 chars' )):
         y += delta
         newIndex = self.index( '@%d,%d' % ( x, y ) )

      return newIndex

   def dline_start( self, index ):
      x,y,width,height = self.bbox( index )
      return self.index( '@%d,%d' % (0, y) )

   def dline_end( self, index ):
      x,y,width,height = self.bbox( index )
      return self.index( '@%d,%d' % ( self.winfo_width(), y ) )

   # Overloads
   def mark_set( self, name, index ):
      Tkinter.Text.mark_set( self, name, index )

      if name == 'insert':
         try:
            if self.compare( 'sel.anchor', '<', 'insert' ):
               self.mark_set( 'sel.first', 'sel.anchor' )
               self.mark_set( 'sel.last', 'insert' )
            elif self.compare( 'sel.anchor', '>', 'insert' ):
               self.mark_set( 'sel.first', 'insert' )
               self.mark_set( 'sel.last', 'sel.anchor' )
            else:
               return

            self.tag_remove( 'sel', '1.0', 'end' )
            self.tag_add( 'sel', 'sel.first', 'sel.last' )
         except:
            pass


sample = '''zero one two three four five six seven eight nine ten eleven twelve thirteen fourteen fifteen sixteen seventeen eighteen nineteen twenty.
twenty-one twenty-two twenty-three twenty-four twenty-five twenty-six twenty-seven.
thirty-one thirty-two thirty-three thirty-four thirty-five thirty-six thirty-seven thirty-eight.'''

root = Tkinter.Tk()
text = EnhancedText( root )
text.pack()

text.insert( 'end', sample )

root.mainloop()