Class CanvasWidget
source code
- 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:
-
__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 CanvasWidget
s 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.
|
|
4-tuple of int s
|
|
int
|
width(self)
Returns:
The width of this canvas widget's bounding box, in its
Canvas 's coordinate space. |
source code
|
|
int
|
height(self)
Returns:
The height of this canvas widget's bounding box, in its
Canvas 's coordinate space. |
source code
|
|
CanvasWidget or None
|
|
list of CanvasWidget
|
|
Tkinter.Canvas
|
|
None
|
move(self,
dx,
dy)
Move this canvas widget by a given distance. |
source code
|
|
None
|
|
|
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
|
|
None
|
manage(self)
Arrange this canvas widget and all of its descendants. |
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
|
|
None
|
|
(any)
|
|
string
|
|
None
|
hide(self)
Temporarily hide this canvas widget. |
source code
|
|
None
|
|
boolean
|
|
|
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
|
|
|
|
|
unbind_drag(self)
Remove a callback that was registered with bind_drag . |
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
|
|
|
__click(self,
event)
If this CanvasWidget has a click callback, then call it;
otherwise, find the closest ancestor with a click callback, and call
it. |
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
|
|
None
|
_update(self,
child)
Update this canvas widget in response to a change in one of its
children. |
source code
|
|
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.
|
__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.
|
- Returns:
4-tuple of int s
- 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.
|
- Returns:
int
- The width of this canvas widget's bounding box, in its
Canvas 's coordinate space.
|
- Returns:
int
- The height of this canvas widget's bounding box, in its
Canvas 's coordinate space.
|
- Returns:
CanvasWidget or None
- The hierarchical parent of this canvas widget.
self
is considered a subpart of its parent for purposes of user
interaction.
|
- 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.
|
- Returns:
Tkinter.Canvas
- The canvas that this canvas widget is bound to.
|
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
|
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.
|
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.
|
- 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.
|
__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
|
__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.
|
- Returns:
string
- a string representation of this canvas widget.
|
- Returns:
boolean
- True if this canvas widget is hidden.
|
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 the event and this CanvasWidget as its
argument. (dp: added the event as 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).
|
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.
|
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).
|
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.
|
Begin dragging this object:
-
register a motion callback
-
record the drag coordinates
|
Handle a motion event:
-
move this object to the new location
-
record the new drag coordinates
|
Handle a release callback:
-
unregister motion & button release callbacks.
-
decide whether they clicked, dragged, or cancelled
-
call the appropriate handler.
|
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.
|
If this CanvasWidget has a click 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.
|
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.
|
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.
|
- 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.
|
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
|
Update this canvas widget in response to a change in one of its
children.
- Parameters:
child (CanvasWidget ) - The child that changed.
- Returns:
None
|
__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
|