|pythonware.com||products ::: library ::: search ::: daily Python-URL!|
The Text widget supports the standard Tkinter Widget interface, plus the following methods:
The following methods are used to manipulate builtin as well as user-defined marks.
The Text widget allows you to embed windows into the widget. Embedded windows occupy a single character position, and moves with the text flow.
Table 42-2. Text Window Options
The Text widget allows you to embed images into the widget. Embedded images occupy a single character position, and moves with the text flow.
Note that the image interface is not available in early version of Tkinter (it's not implemented by Tk versions before 8.0). For such platforms, you can display images by embedding Label widgets instead.
image_create(index, options...). Insert an image at the given position. The image is given by the image option, and must be a Tkinter PhotoImage or BitmapImage instance (or an instance of the corresponding PIL classes).
This method doesn't work with Tk versions before 8.0.
Table 42-3. Text Image Options
index(image). Return the line/column position corresponding to the given image (or any other index specifier; see above).
delete(image). Remove the given image from the text widget, and destroy it.
image_cget(index, option). Return the current value of the given option. If there's no image on the given position, this method raises a TclError exception. Not implemented in Python 1.5.2 and earlier.
image_config(index, options...), image_configure(index, options...). Modifies one or more options. If there's no image on the given position, this method raises a TclError exception. Not implemented in Python 1.5.2 and earlier.
image_names(). Return a tuple containing the names of all images embedded in the text widget. Tkinter doesn't provide a way to get the corresponding PhotoImage or BitmapImage objects, but you can keep track of those yourself using a dictionary (using str(image) as the key).
This method is not implemented in Python 1.5.2 and earlier.
The following methods are used to manipulate tags and tag ranges.
tag_add(tag, index), tag_add(tag, start, top). Add tag to the character at the given position, or to the given range.
tag_remove(tag, index), tag_remove(tag, start, stop). Remove the tag from the character at the given position, or from the given range. The information associated with the tag is not removed (not even if you use tag_remove(1.0, END)).
tag_delete(tag), tag_delete(tags...). Remove the given tags from the widget. All style and binding information associated with the tags are also removed.
tag_config(tag, options...), tag_configure(tag, options...). Set style options for the given tag. If the tag doesn't exist, it is created.
Note that the style options are associated with tags, not text ranges. Any text having a given tag will be rendered according to its style options, even if it didn't exist when the binding was created. If a text range has several tags associated with it, the Text widget combines the style options for all tags. Tags towards the top of the tag stack (created later, or raised using tag_raise) have precedence.
tag_cget(tag, option). Get the current value for the given option.
tag_bind(tag, sequence, func), tag_bind(tag, sequence, func, "+"). Add an event binding to the given tag. Tag bindings can use mouse- and keyboard-related events, plus <Enter> and <Leave>. If the tag doesn't exist, it is created. Usually, the new binding replaces any existing binding for the same event sequence. The second form can be used to add the new callback to the existing binding.
Note that the new bindings are associated with tags, not text ranges. Any text having the tag will fire events, even if it didn't exist when the binding was created. To remove bindings, use tag_remove or tag_unbind.
tag_unbind(tag, sequence). Remove the binding, if any, for the given tag and event sequence combination.
tag_names(). Return a tuple containing all tags used in the widget. This includes the SEL selection tag.
tag_names(index). Return a tuple containing all tags used by the character at the given position.
tag_nextrange(tag, index), tag_nextrange(tag, start, stop). Find the next occurence of the given tag, starting at the given index. If two indexes are given, search only from start to stop. Note that this method looks for the start of a range, so if you happen to start on a character that has the given tag, this method will return that range only if that character is the first in the range. Otherwise, the current range is skipped.
tag_prevrange(tag, index), tag_prevrange(tag, start, stop). Find the next occurence of the given tag, starting at the given index and searching towards the beginning of the text. If two indexes are given, search from start to stop. As for nextrange, this method looks for the start of a range, beginning at the start index. So if you start on a character that has the given tag, this method will return that range unless the search started on the first character in that tag range.
tag_lower(tag), tag_lower(tag, below). Move the given tag to the bottom of the tag stack (or place it just under the below tag). If multiple tags are defined for a range of text, options defined by tags towards the top of the stack have precedence.
tag_raise(tag), tag_raise(tag, above). Move the given tag to the top of the tag stack (or place it just over the above tag).
tag_ranges(tag). Return a tuple with start- and stop-indexes for each occurence of the given tag. If the tag doesn't exist, this method returns an empty tuple. Note that the tuple contains two items for each range.
To manipulate the selection, use tag methods like tag_add and tag_remove on the SEL tag. There are no selection-specific methods provided by the Text widget.
But if you insist, here's how how to emulate the Entry widget selection methods:
def selection_clear(text): text.tag_remove(SEL, 1.0, END) def selection_from(text, index): text._anchor = index def selection_present(text): return len(text.tag_ranges(SEL)) != 0 def selection_range(text, start, end): text.tag_remove(SEL, 1.0, start) text.tag_add(SEL, start, end) text.tag_remove(SEL, end, END) def selection_to(text, index): if text.compare(index, "<", text._anchor): selection_range(text, index, text._anchor) else: selection_range(text, text._anchor, index)
The following methods only work if the text widget is updated. To make sure this is the case, call the update_idletasks method before you use any of these.
bbox(index). Returns the bounding box for the given character, as a 4-tuple: (x, y, width, height). If the character is not visible, this method returns None.
dlineinfo(index). Returns the bounding box for the line containing the given character, as a 5-tuple: (x, y, width, height, offset). The last tuple member is the offset from the top of the line to the baseline. If the line is not visible, this method returns None.
The Text widget doesn't contain any builtin support for printing. To print the contents, use get or dump and pass the resulting text to a suitable output device.
If you have a Postscript printer, you can use PIL's PSDraw module.
search(pattern, index, options...). Search for text in the widget. Returns the first matching position if successful, or an empty string if there was no match.
Table 42-4. Text Search Options
These methods are used to scroll the text widget in various ways. The scan methods can be used to implement fast mouse pan/roam operations (they are bound to the middle mouse button, if available), while the xview and yview methods are used with standard scrollbars.
scan_mark(x, y), scan_dragto(x, y). scan_mark sets the scanning anchor for fast horizontal scrolling to the given mouse coordinate. scan_dragto scrolls the widget contents sideways according to the given mouse coordinate. The text is moved 10 times the distance between the scanning anchor and the new position.
xview(), yview(). Returns a tuple containing two values; the first value corresponds to the relative offset of the first visible line (column), and the second corresponds to the relative offset of the line (column) just after the last one visible on the screen. Offset 0.0 is the beginning of the text, 1.0 the end.
xview(MOVETO, offset), yview(MOVETO, offset). Adjust the text widget so that the given offset is at the left (top) edge of the text. Offset 0.0 is the beginning of the text, 1.0 the end. These methods are used by the Scrollbar bindings when the user drags the scrollbar slider.
The MOVETO constant is not defined in Python 1.5.2 and earlier. For compatibility, use the string "moveto" instead.
xview(SCROLL, step, what), yview(SCROLL, step, what). Scroll the text widget horizontally (vertically) by the given amount. The what argument can be either UNITS (lines, characters) or PAGES. These methods are used by the Scrollbar bindings when the user clicks at a scrollbar arrow or in the trough.
These constants are not defined in Python 1.5.2 and earlier. For compatibility, use the strings "scroll", "units", and "pages" instead.
yview_pickplace(index). Same as see, but only handles the vertical position correctly. New code should use see instead.