Package nltk :: Package draw :: Class CanvasWidget
[hide private]
[frames] | no frames]

Class CanvasWidget

source code

object --+
         |
        CanvasWidget
Known Subclasses:

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:

>>> cn = CanvasText(c, '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:

For CanvasWidgets 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.

Instance Methods [hide private]
 
__click(self, button)
If this CanvasWidget has a drag callback, then call it; otherwise, find the closest ancestor with a click callback, and call it.
source code
 
__drag(self)
If this CanvasWidget has a drag callback, then call it; otherwise, find the closest ancestor with a drag callback, and call it.
source code
(any)
__getitem__(self, attr)
Returns: the value of the attribute attr.
source code
 
__init__(self, canvas, parent=None, **attribs)
Create a new canvas widget.
source code
 
__motion_cb(self, event)
Handle a motion event:
source code
 
__press_cb(self, event)
Handle a button-press event:
source code
 
__release_cb(self, event)
Handle a release callback:
source code
string
__repr__(self)
Returns: a string representation of this canvas widget.
source code
None
__setitem__(self, attr, value)
Set the value of the attribute attr to value.
source code
 
__start_drag(self, event)
Begin dragging this object:
source code
 
_add_child_widget(self, child)
Register a hierarchical child widget.
source code
None
_manage(self)
Arrange the child widgets of this canvas widget.
source code
 
_remove_child_widget(self, child)
Remove a hierarchical child widget.
source code
list of int
_tags(self)
Returns: a list of canvas tags for all graphical elements managed by this canvas widget, not including graphical elements managed by its child widgets.
source code
None
_update(self, child)
Update this canvas widget in response to a change in one of its children.
source code
4-tuple of ints
bbox(self)
Returns: A bounding box for this CanvasWidget.
source code
 
bind_click(self, callback, button=1)
Register a new callback that will be called whenever this CanvasWidget is clicked on.
source code
 
bind_drag(self, callback)
Register a new callback that will be called after this CanvasWidget is dragged.
source code
Tkinter.Canvas
canvas(self)
Returns: The canvas that this canvas widget is bound to.
source code
list of CanvasWidget
child_widgets(self)
Returns: A list of the hierarchical children of this canvas widget.
source code
None
destroy(self)
Remove this CanvasWidget from its Canvas.
source code
int
height(self)
Returns: The height of this canvas widget's bounding box, in its Canvas's coordinate space.
source code
boolean
hidden(self)
Returns: True if this canvas widget is hidden.
source code
None
hide(self)
Temporarily hide this canvas widget.
source code
None
manage(self)
Arrange this canvas widget and all of its descendants.
source code
None
move(self, dx, dy)
Move this canvas widget by a given distance.
source code
 
moveto(self, x, y, anchor='NW')
Move this canvas widget to the given location.
source code
CanvasWidget or None
parent(self)
Returns: The hierarchical parent of this canvas widget.
source code
None
show(self)
Show a hidden canvas widget.
source code
list of int
tags(self)
Returns: a list of the canvas tags for all graphical elements managed by this canvas widget, including graphical elements managed by its child widgets.
source code
 
unbind_click(self, button=1)
Remove a callback that was registered with bind_click.
source code
 
unbind_drag(self)
Remove a callback that was registered with bind_drag.
source code
 
update(self, 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.
source code
int
width(self)
Returns: The width of this canvas widget's bounding box, in its Canvas's coordinate space.
source code

Inherited from object: __delattr__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __setattr__, __str__

Instance Variables [hide private]
dictionary __callbacks
Registered callbacks.
Tkinter.Canvas __canvas
This CanvasWidget's canvas.
list of CanvasWidget __children
This CanvasWidget's hierarchical child widgets.
int __drag_x
Where it's been moved to (to find dx)
int __drag_y
Where it's been moved to (to find dy)
boolean __draggable
Is this canvas widget draggable?
CanvasWidget or None __parent
This CanvasWidget's hierarchical parent widget.
event __press
The ButtonPress event that we're currently handling.
boolean __updating
Is this canvas widget currently performing an update? If it is, then it will ignore any new update requests from child widgets.
Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__click(self, button)

source code 

If this CanvasWidget has a drag callback, then call it; otherwise, find the closest ancestor with a click callback, and call it. If no ancestors have a click callback, do nothing.

__drag(self)

source code 

If this CanvasWidget has a drag callback, then call it; otherwise, find the closest ancestor with a drag callback, and call it. If no ancestors have a drag callback, do nothing.

__getitem__(self, attr)
(Indexing operator)

source code 
Returns: (any)
the value of the attribute attr. See the class documentation for a list of attributes supported by this canvas widget.

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

source code 

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.
Overrides: object.__init__

__motion_cb(self, event)

source code 

Handle a motion event:

  • move this object to the new location
  • record the new drag coordinates

__press_cb(self, event)

source code 

Handle a button-press event:

  • record the button press event in self.__press
  • register a button-release callback.
  • if this CanvasWidget or any of its ancestors are draggable, then register the appropriate motion callback.

__release_cb(self, event)

source code 

Handle a release callback:

  • unregister motion & button release callbacks.
  • decide whether they clicked, dragged, or cancelled
  • call the appropriate handler.

__repr__(self)
(Representation operator)

source code 

repr(x)

Returns: string
a string representation of this canvas widget.
Overrides: object.__repr__

__setitem__(self, attr, value)
(Index assignment operator)

source code 

Set the value of the attribute attr to value. See the class documentation for a list of attributes supported by this canvas widget.

Returns: None

__start_drag(self, event)

source code 

Begin dragging this object:

  • register a motion callback
  • record the drag coordinates

_add_child_widget(self, child)

source code 

Register a hierarchical child widget. The child will be considered part of this canvas widget for purposes of user interaction. _add_child_widget has two direct effects:

  • It sets child's parent to this canvas widget.
  • It adds child to the list of canvas widgets returned by the child_widgets member function.
Parameters:
  • child (CanvasWidget) - The new child widget. child must not already have a parent.

_manage(self)

source code 

Arrange the child widgets of this canvas widget. This method is called when the canvas widget is initially created. It is also called if the user calls the manage method on this canvas widget or any of its ancestors.

Returns: None

_remove_child_widget(self, child)

source code 

Remove a hierarchical child widget. This child will no longer be considered part of this canvas widget for purposes of user interaction. _add_child_widget has two direct effects:

  • It sets child's parent to None.
  • It removes child from the list of canvas widgets returned by the child_widgets member function.
Parameters:
  • child (CanvasWidget) - The child widget to remove. child must be a child of this canvas widget.

_tags(self)

source code 
Returns: list of int
a list of canvas tags for all graphical elements managed by this canvas widget, not including graphical elements managed by its child widgets.

_update(self, child)

source code 

Update this canvas widget in response to a change in one of its children.

Parameters:
  • child (CanvasWidget) - The child that changed.
Returns: None

bbox(self)

source code 
Returns: 4-tuple of ints
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 Canvas's coordinate space.

bind_click(self, callback, button=1)

source code 

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(self, callback)

source code 

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(self)

source code 
Returns: Tkinter.Canvas
The canvas that this canvas widget is bound to.

child_widgets(self)

source code 
Returns: list of CanvasWidget
A list of the hierarchical children of this canvas widget. These children are considered part of self for purposes of user interaction.

destroy(self)

source code 

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.

Returns: None
Raises:
  • ValueError - if this CanvasWidget has a parent.

height(self)

source code 
Returns: int
The height of this canvas widget's bounding box, in its Canvas's coordinate space.

hidden(self)

source code 
Returns: boolean
True if this canvas widget is hidden.

move(self, dx, dy)

source code 

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.
Returns: None

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

source code 

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(self)

source code 
Returns: CanvasWidget or None
The hierarchical parent of this canvas widget. self is considered a subpart of its parent for purposes of user interaction.

tags(self)

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

unbind_click(self, button=1)

source code 

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).

update(self, child)

source code 

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(self)

source code 
Returns: int
The width of this canvas widget's bounding box, in its Canvas's coordinate space.

Instance Variable Details [hide private]

__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.
Type:
dictionary