nltk.draw.util module

Tools for graphically displaying and interacting with the objects and processing classes defined by the Toolkit. These tools are primarily intended to help students visualize the objects that they create.

The graphical tools are typically built using “canvas widgets”, each of which encapsulates the graphical elements and bindings used to display a complex object on a Tkinter Canvas. For example, NLTK defines canvas widgets for displaying trees and directed graphs, as well as a number of simpler widgets. These canvas widgets make it easier to build new graphical tools and demos. See the class documentation for CanvasWidget for more information.

The nltk.draw module defines the abstract CanvasWidget base class, and a number of simple canvas widgets. The remaining canvas widgets are defined by submodules, such as nltk.draw.tree.

The nltk.draw module also defines CanvasFrame, which encapsulates a Canvas and its scrollbars. It uses a ScrollWatcherWidget to ensure that all canvas widgets contained on its canvas are within the scroll region.

Acknowledgements: Many of the ideas behind the canvas widget system are derived from CLIG, a Tk-based grapher for linguistic data structures. For more information, see the CLIG homepage (http://www.ags.uni-sb.de/~konrad/clig.html).

class nltk.draw.util.AbstractContainerWidget

Bases: CanvasWidget

An abstract class for canvas widgets that contain a single child, such as BoxWidget and OvalWidget. Subclasses must define a constructor, which should create any new graphical elements and then call the AbstractCanvasContainer constructor. Subclasses must also define the _update method and the _tags method; and any subclasses that define attributes should define __setitem__ and __getitem__.

__init__(canvas, child, **attribs)

Create a new container widget. This constructor should only be called by subclass constructors.

Parameters

• canvas (Tkinter.Canvas) – This canvas widget’s canvas.

• child (CanvasWidget) – The container’s child widget. child must not have a parent.

• attribs – The new canvas widget’s attributes.

child()

Returns

The child widget contained by this container widget.

Return type

CanvasWidget

set_child(child)

Change the child widget contained by this container widget.

Parameters

child (CanvasWidget) – The new child widget. child must not have a parent.

Return type

None

class nltk.draw.util.BoxWidget

Bases: AbstractContainerWidget

A canvas widget that places a box around a child widget.

Attributes:

• fill: The color used to fill the interior of the box.

• outline: The color used to draw the outline of the box.

• width: The width of the outline of the box.

• margin: The number of pixels space left between the child and the box.

• draggable: whether the text can be dragged by the user.

__init__(canvas, child, **attribs)

Create a new box widget.

Parameters

• canvas (Tkinter.Canvas) – This canvas widget’s canvas.

• child (CanvasWidget) – The child widget. child must not have a parent.

• attribs – The new canvas widget’s attributes.

class nltk.draw.util.BracketWidget

Bases: AbstractContainerWidget

A canvas widget that places a pair of brackets around a child widget.

Attributes:

• color: The color used to draw the brackets.

• width: The width of the brackets.

• draggable: whether the text can be dragged by the user.

__init__(canvas, child, **attribs)

Create a new bracket widget.

Parameters

• canvas (Tkinter.Canvas) – This canvas widget’s canvas.

• child (CanvasWidget) – The child widget. child must not have a parent.

• attribs – The new canvas widget’s attributes.

class nltk.draw.util.CanvasFrame

Bases: object

A Tkinter frame containing a canvas and scrollbars. CanvasFrame uses a ScrollWatcherWidget to ensure that all of the canvas widgets contained on its canvas are within its scrollregion. In order for CanvasFrame to make these checks, all canvas widgets must be registered with add_widget when they are added to the canvas; and destroyed with destroy_widget when they are no longer needed.

If a CanvasFrame is created with no parent, then it will create its own main window, including a “Done” button and a “Print” button.

__init__(parent=None, **kw)

Create a new CanvasFrame.

Parameters

• parent (Tkinter.BaseWidget or Tkinter.Tk) – The parent Tkinter widget. If no parent is specified, then CanvasFrame will create a new main window.

• kw – Keyword arguments for the new Canvas. See the documentation for Tkinter.Canvas for more information.

add_widget(canvaswidget, x=None, y=None)

Register a canvas widget with this CanvasFrame. The CanvasFrame will ensure that this canvas widget is always within the Canvas’s scrollregion. If no coordinates are given for the canvas widget, then the CanvasFrame will attempt to find a clear area of the canvas for it.

Parameters

• canvaswidget (CanvasWidget) – The new canvas widget. canvaswidget must have been created on this CanvasFrame’s canvas.

• x (int) – The initial x coordinate for the upper left hand corner of canvaswidget, in the canvas’s coordinate space.

• y (int) – The initial y coordinate for the upper left hand corner of canvaswidget, in the canvas’s coordinate space.

canvas()

Returns

The canvas managed by this CanvasFrame.

Return type

Tkinter.Canvas

destroy(*e)

Destroy this CanvasFrame. If this CanvasFrame created a top-level window, then this will close that window.

destroy_widget(canvaswidget)

Remove a canvas widget from this CanvasFrame. This deregisters the canvas widget, and destroys it.

mainloop(*args, **kwargs)

Enter the Tkinter mainloop. This function must be called if this frame is created from a non-interactive program (e.g. from a secript); otherwise, the frame will close as soon as the script completes.

pack(cnf={}, **kw)

Pack this CanvasFrame. See the documentation for Tkinter.Pack for more information.

print_to_file(filename=None)

Print the contents of this CanvasFrame to a postscript file. If no filename is given, then prompt the user for one.

Parameters

filename (str) – The name of the file to print the tree to.

Return type

None

remove_widget(canvaswidget)

scrollregion()

Returns

The current scroll region for the canvas managed by this CanvasFrame.

Return type

4-tuple of int

class nltk.draw.util.CanvasWidget

Bases: object

A collection of graphical elements and bindings used to display a complex object on a Tkinter Canvas. A canvas widget is responsible for managing the Canvas tags and callback bindings necessary to display and interact with the object. Canvas widgets are often organized into hierarchies, where parent canvas widgets control aspects of their child widgets.

Each canvas widget is bound to a single Canvas. This Canvas is specified as the first argument to the CanvasWidget’s constructor.

Attributes. Each canvas widget can support a variety of “attributes”, which control how the canvas widget is displayed. Some typical examples attributes are color, font, and radius. Each attribute has a default value. This default value can be overridden in the constructor, using keyword arguments of the form attribute=value:

>>> from nltk.draw.util import TextWidget
>>> cn = TextWidget(Canvas(), 'test', color='red')  

Attribute values can also be changed after a canvas widget has been constructed, using the __setitem__ operator:

>>> cn['font'] = 'times'  

The current value of an attribute value can be queried using the __getitem__ operator:

>>> cn['color']  
'red'

For a list of the attributes supported by a type of canvas widget, see its class documentation.

Interaction. The attribute 'draggable' controls whether the user can drag a canvas widget around the canvas. By default, canvas widgets are not draggable.

CanvasWidget provides callback support for two types of user interaction: clicking and dragging. The method bind_click registers a callback function that is called whenever the canvas widget is clicked. The method bind_drag registers a callback function that is called after the canvas widget is dragged. If the user clicks or drags a canvas widget with no registered callback function, then the interaction event will propagate to its parent. For each canvas widget, only one callback function may be registered for an interaction event. Callback functions can be deregistered with the unbind_click and unbind_drag methods.

Subclassing. CanvasWidget is an abstract class. Subclasses are required to implement the following methods:

• __init__: Builds a new canvas widget. It must perform the following three tasks (in order):

  • Create any new graphical elements.

  • Call _add_child_widget on each child widget.

  • Call the CanvasWidget constructor.

• _tags: Returns a list of the canvas tags for all graphical elements managed by this canvas widget, not including graphical elements managed by its child widgets.

• _manage: Arranges the child widgets of this canvas widget. This is typically only called when the canvas widget is created.

• _update: Update this canvas widget in response to a change in a single child.

For a CanvasWidget with no child widgets, the default definitions for _manage and _update may be used.

If a subclass defines any attributes, then it should implement __getitem__ and __setitem__. If either of these methods is called with an unknown attribute, then they should propagate the request to CanvasWidget.

Most subclasses implement a number of additional methods that modify the CanvasWidget in some way. These methods must call parent.update(self) after making any changes to the canvas widget’s graphical elements. The canvas widget must also call parent.update(self) after changing any attribute value that affects the shape or position of the canvas widget’s graphical elements.

Variables

• __canvas – This CanvasWidget’s canvas.

• __parent – This CanvasWidget’s hierarchical parent widget.

• __children – This CanvasWidget’s hierarchical child widgets.

• __updating – Is this canvas widget currently performing an update? If it is, then it will ignore any new update requests from child widgets.

• __draggable – Is this canvas widget draggable?

• __press – The ButtonPress event that we’re currently handling.

• __drag_x – Where it’s been moved to (to find dx)

• __drag_y – Where it’s been moved to (to find dy)

• __callbacks – Registered callbacks. Currently, four keys are used: 1, 2, 3, and 'drag'. The values are callback functions. Each callback function takes a single argument, which is the CanvasWidget that triggered the callback.

__init__(canvas, parent=None, **attribs)

Create a new canvas widget. This constructor should only be called by subclass constructors; and it should be called only “after” the subclass has constructed all graphical canvas objects and registered all child widgets.

Parameters

• canvas (Tkinter.Canvas) – This canvas widget’s canvas.

• parent (CanvasWidget) – This canvas widget’s hierarchical parent.

• attribs – The new canvas widget’s attributes.

bbox()

Returns

A bounding box for this CanvasWidget. The bounding box is a tuple of four coordinates, (xmin, ymin, xmax, ymax), for a rectangle which encloses all of the canvas widget’s graphical elements. Bounding box coordinates are specified with respect to the coordinate space of the Canvas.

Return type

tuple(int, int, int, int)

bind_click(callback, button=1)

Register a new callback that will be called whenever this CanvasWidget is clicked on.

Parameters

• callback (function) – The callback function that will be called whenever this CanvasWidget is clicked. This function will be called with this CanvasWidget as its argument.

• button (int) – Which button the user should use to click on this CanvasWidget. Typically, this should be 1 (left button), 3 (right button), or 2 (middle button).

bind_drag(callback)

Register a new callback that will be called after this CanvasWidget is dragged. This implicitly makes this CanvasWidget draggable.

Parameters

callback (function) – The callback function that will be called whenever this CanvasWidget is clicked. This function will be called with this CanvasWidget as its argument.

canvas()

Returns

The canvas that this canvas widget is bound to.

Return type

Tkinter.Canvas

child_widgets()

Returns

A list of the hierarchical children of this canvas widget. These children are considered part of self for purposes of user interaction.

Return type

list of CanvasWidget

destroy()

Remove this CanvasWidget from its Canvas. After a CanvasWidget has been destroyed, it should not be accessed.

Note that you only need to destroy a top-level CanvasWidget; its child widgets will be destroyed automatically. If you destroy a non-top-level CanvasWidget, then the entire top-level widget will be destroyed.

Raises

ValueError – if this CanvasWidget has a parent.

Return type

None

height()

Returns

The height of this canvas widget’s bounding box, in its Canvas’s coordinate space.

Return type

int

hidden()

Returns

True if this canvas widget is hidden.

Return type

bool

hide()

Temporarily hide this canvas widget.

Return type

None

manage()

Arrange this canvas widget and all of its descendants.

Return type

None

move(dx, dy)

Move this canvas widget by a given distance. In particular, shift the canvas widget right by dx pixels, and down by dy pixels. Both dx and dy may be negative, resulting in leftward or upward movement.

Parameters

• dx (int) – The number of pixels to move this canvas widget rightwards.

• dy (int) – The number of pixels to move this canvas widget downwards.

Return type

None

moveto(x, y, anchor='NW')

Move this canvas widget to the given location. In particular, shift the canvas widget such that the corner or side of the bounding box specified by anchor is at location (x, y).

Parameters

• x,y – The location that the canvas widget should be moved to.

• anchor – The corner or side of the canvas widget that should be moved to the specified location. 'N' specifies the top center; 'NE' specifies the top right corner; etc.

parent()

Returns

The hierarchical parent of this canvas widget. self is considered a subpart of its parent for purposes of user interaction.

Return type

CanvasWidget or None

show()

Show a hidden canvas widget.

Return type

None

tags()

Returns

a list of the canvas tags for all graphical elements managed by this canvas widget, including graphical elements managed by its child widgets.

Return type

list of int

unbind_click(button=1)

Remove a callback that was registered with bind_click.

Parameters

button (int) – Which button the user should use to click on this CanvasWidget. Typically, this should be 1 (left button), 3 (right button), or 2 (middle button).

unbind_drag()

Remove a callback that was registered with bind_drag.

update(child)

Update the graphical display of this canvas widget, and all of its ancestors, in response to a change in one of this canvas widget’s children.

Parameters

child (CanvasWidget) – The child widget that changed.

width()

Returns

The width of this canvas widget’s bounding box, in its Canvas’s coordinate space.

Return type

int

class nltk.draw.util.ColorizedList

Bases: object

An abstract base class for displaying a colorized list of items. Subclasses should define:

• _init_colortags, which sets up Text color tags that will be used by the list.

• _item_repr, which returns a list of (text,colortag) tuples that make up the colorized representation of the item.

Note

Typically, you will want to register a callback for 'select' that calls mark on the given item.

__init__(parent, items=[], **options)

Construct a new list.

Parameters

• parent – The Tk widget that contains the colorized list

• items – The initial contents of the colorized list.

• options –

add_callback(event, func)

Register a callback function with the list. This function will be called whenever the given event occurs.

Parameters

• event – The event that will trigger the callback function. Valid events are: click1, click2, click3, space, return, select, up, down, next, prior, move

• func – The function that should be called when the event occurs. func will be called with a single item as its argument. (The item selected or the item moved to).

focus()

get(index=None)

Returns

A list of the items contained by this list.

grid(cnf={}, **kw)

mark(item)

Highlight the given item. :raise ValueError: If item is not contained in the list.

markonly(item)

Remove any current highlighting, and mark the given item. :raise ValueError: If item is not contained in the list.

pack(cnf={}, **kw)

remove_callback(event, func=None)

Deregister a callback function. If func is none, then all callbacks are removed for the given event.

set(items)

Modify the list of items contained by this list.

unmark(item=None)

Remove highlighting from the given item; or from every item, if no item is given. :raise ValueError: If item is not contained in the list. :raise KeyError: If item is not marked.

view(item)

Adjust the view such that the given item is visible. If the item is already visible, then do nothing.

class nltk.draw.util.EntryDialog

Bases: object

A dialog box for entering

__init__(parent, original_text='', instructions='', set_callback=None, title=None)

class nltk.draw.util.MutableOptionMenu

Bases: Menubutton

__init__(master, values, **options)

Construct a widget with the parent widget MASTER, a name WIDGETNAME and appropriate options.

add(value)

destroy()

Destroy this widget and the associated menu.

remove(value)

set(value)

class nltk.draw.util.OvalWidget

Bases: AbstractContainerWidget

A canvas widget that places a oval around a child widget.

Attributes:

• fill: The color used to fill the interior of the oval.

• outline: The color used to draw the outline of the oval.

• width: The width of the outline of the oval.

• margin: The number of pixels space left between the child and the oval.

• draggable: whether the text can be dragged by the user.

• double: If true, then a double-oval is drawn.

RATIO = 1.414213562373095

__init__(canvas, child, **attribs)

Create a new oval widget.

Parameters

• canvas (Tkinter.Canvas) – This canvas widget’s canvas.

• child (CanvasWidget) – The child widget. child must not have a parent.

• attribs – The new canvas widget’s attributes.

class nltk.draw.util.ParenWidget

Bases: AbstractContainerWidget

A canvas widget that places a pair of parenthases around a child widget.

Attributes:

• color: The color used to draw the parenthases.

• width: The width of the parenthases.

• draggable: whether the text can be dragged by the user.

__init__(canvas, child, **attribs)

Create a new parenthasis widget.

Parameters

• canvas (Tkinter.Canvas) – This canvas widget’s canvas.

• child (CanvasWidget) – The child widget. child must not have a parent.

• attribs – The new canvas widget’s attributes.

class nltk.draw.util.ScrollWatcherWidget

Bases: CanvasWidget

A special canvas widget that adjusts its Canvas’s scrollregion to always include the bounding boxes of all of its children. The scroll-watcher widget will only increase the size of the Canvas’s scrollregion; it will never decrease it.

__init__(canvas, *children, **attribs)

Create a new scroll-watcher widget.

Parameters

• canvas (Tkinter.Canvas) – This canvas widget’s canvas.

• children (list(CanvasWidget)) – The canvas widgets watched by the scroll-watcher. The scroll-watcher will ensure that these canvas widgets are always contained in their canvas’s scrollregion.

• attribs – The new canvas widget’s attributes.

add_child(canvaswidget)

Add a new canvas widget to the scroll-watcher. The scroll-watcher will ensure that the new canvas widget is always contained in its canvas’s scrollregion.

Parameters

canvaswidget (CanvasWidget) – The new canvas widget.

Return type

None

remove_child(canvaswidget)

Remove a canvas widget from the scroll-watcher. The scroll-watcher will no longer ensure that the new canvas widget is always contained in its canvas’s scrollregion.

Parameters

canvaswidget (CanvasWidget) – The canvas widget to remove.

Return type

None

class nltk.draw.util.SequenceWidget

Bases: CanvasWidget

A canvas widget that keeps a list of canvas widgets in a horizontal line.

Attributes:

• align: The vertical alignment of the children. Possible values are 'top', 'center', and 'bottom'. By default, children are center-aligned.

• space: The amount of horizontal space to place between children. By default, one pixel of space is used.

• ordered: If true, then keep the children in their original order.

__init__(canvas, *children, **attribs)

Create a new sequence widget.

Parameters

• canvas (Tkinter.Canvas) – This canvas widget’s canvas.

• children (list(CanvasWidget)) – The widgets that should be aligned horizontally. Each child must not have a parent.

• attribs – The new canvas widget’s attributes.

children()

Returns

A list of the hierarchical children of this canvas widget. These children are considered part of self for purposes of user interaction.

Return type

list of CanvasWidget

insert_child(index, child)

Insert a child canvas widget before a given index.

Parameters

• child (CanvasWidget) – The canvas widget that should be inserted.

• index (int) – The index where the child widget should be inserted. In particular, the index of child will be index; and the index of any children whose indices were greater than equal to index before child was inserted will be incremented by one.

remove_child(child)

Remove the given child canvas widget. child’s parent will be set to None.

Parameters

child (CanvasWidget) – The child canvas widget to remove.

replace_child(oldchild, newchild)

Replace the child canvas widget oldchild with newchild. newchild must not have a parent. oldchild’s parent will be set to None.

Parameters

• oldchild (CanvasWidget) – The child canvas widget to remove.

• newchild (CanvasWidget) – The canvas widget that should replace oldchild.

class nltk.draw.util.ShowText

Bases: object

A Tkinter window used to display a text. ShowText is typically used by graphical tools to display help text, or similar information.

__init__(root, title, text, width=None, height=None, **textbox_options)

destroy(*e)

find_dimentions(text, width, height)

mainloop(*args, **kwargs)

Enter the Tkinter mainloop. This function must be called if this window is created from a non-interactive program (e.g. from a secript); otherwise, the window will close as soon as the script completes.

class nltk.draw.util.SpaceWidget

Bases: CanvasWidget

A canvas widget that takes up space but does not display anything. A SpaceWidget can be used to add space between elements. Each space widget is characterized by a width and a height. If you wish to only create horizontal space, then use a height of zero; and if you wish to only create vertical space, use a width of zero.

__init__(canvas, width, height, **attribs)

Create a new space widget.

Parameters

• canvas (Tkinter.Canvas) – This canvas widget’s canvas.

• width (int) – The width of the new space widget.

• height (int) – The height of the new space widget.

• attribs – The new canvas widget’s attributes.

set_height(height)

Change the height of this space widget.

Parameters

height (int) – The new height.

Return type

None

set_width(width)

Change the width of this space widget.

Parameters

width (int) – The new width.

Return type

None

class nltk.draw.util.StackWidget

Bases: CanvasWidget

A canvas widget that keeps a list of canvas widgets in a vertical line.

Attributes:

• align: The horizontal alignment of the children. Possible values are 'left', 'center', and 'right'. By default, children are center-aligned.

• space: The amount of vertical space to place between children. By default, one pixel of space is used.

• ordered: If true, then keep the children in their original order.

__init__(canvas, *children, **attribs)

Create a new stack widget.

Parameters

• canvas (Tkinter.Canvas) – This canvas widget’s canvas.

• children (list(CanvasWidget)) – The widgets that should be aligned vertically. Each child must not have a parent.

• attribs – The new canvas widget’s attributes.

children()

Returns

A list of the hierarchical children of this canvas widget. These children are considered part of self for purposes of user interaction.

Return type

list of CanvasWidget

insert_child(index, child)

Insert a child canvas widget before a given index.

Parameters

• child (CanvasWidget) – The canvas widget that should be inserted.

• index (int) – The index where the child widget should be inserted. In particular, the index of child will be index; and the index of any children whose indices were greater than equal to index before child was inserted will be incremented by one.

remove_child(child)

Remove the given child canvas widget. child’s parent will be set to None.

Parameters

child (CanvasWidget) – The child canvas widget to remove.

replace_child(oldchild, newchild)

Replace the child canvas widget oldchild with newchild. newchild must not have a parent. oldchild’s parent will be set to None.

Parameters

• oldchild (CanvasWidget) – The child canvas widget to remove.

• newchild (CanvasWidget) – The canvas widget that should replace oldchild.

class nltk.draw.util.SymbolWidget

Bases: TextWidget

A canvas widget that displays special symbols, such as the negation sign and the exists operator. Symbols are specified by name. Currently, the following symbol names are defined: neg, disj, conj, lambda, merge, forall, exists, subseteq, subset, notsubset, emptyset, imp, rightarrow, equal, notequal, epsilon.

Attributes:

• color: the color of the text.

• draggable: whether the text can be dragged by the user.

Variables

SYMBOLS – A dictionary mapping from symbols to the character in the symbol font used to render them.

SYMBOLS = {'conj': 'Ù', 'disj': 'Ú', 'emptyset': 'Æ', 'epsilon': 'e', 'equal': '=', 'exists': '$', 'forall': '"', 'imp': 'Þ', 'intersection': 'Ç', 'lambda': 'l', 'merge': 'Ä', 'neg': 'Ø', 'notequal': '¹', 'notsubset': 'Ë', 'rightarrow': 'Þ', 'subset': 'Ì', 'subseteq': 'Í', 'union': 'È'}

__init__(canvas, symbol, **attribs)

Create a new symbol widget.

Parameters

• canvas (Tkinter.Canvas) – This canvas widget’s canvas.

• symbol (str) – The name of the symbol to display.

• attribs – The new canvas widget’s attributes.

set_symbol(symbol)

Change the symbol that is displayed by this symbol widget.

Parameters

symbol (str) – The name of the symbol to display.

symbol()

Returns

the name of the symbol that is displayed by this symbol widget.

Return type

str

static symbolsheet(size=20)

Open a new Tkinter window that displays the entire alphabet for the symbol font. This is useful for constructing the SymbolWidget.SYMBOLS dictionary.

class nltk.draw.util.TextWidget

Bases: CanvasWidget

A canvas widget that displays a single string of text.

Attributes:

• color: the color of the text.

• font: the font used to display the text.

• justify: justification for multi-line texts. Valid values are left, center, and right.

• width: the width of the text. If the text is wider than this width, it will be line-wrapped at whitespace.

• draggable: whether the text can be dragged by the user.

__init__(canvas, text, **attribs)

Create a new text widget.

Parameters

• canvas (Tkinter.Canvas) – This canvas widget’s canvas.

• text (str) – The string of text to display.

• attribs – The new canvas widget’s attributes.

set_text(text)

Change the text that is displayed by this text widget.

Parameters

text (str) – The string of text to display.

Return type

None

text()

Returns

The text displayed by this text widget.

Return type

str

nltk.draw.util.demo()

A simple demonstration showing how to use canvas widgets.