Tk -- The Canvas

Tk -- The Canvas Widget
An Introduction to Tkinter


Methods

The first group of methods are used to create and configure items on a canvas.

create_arc(bbox, options) => id
Create an arc canvas item. Returns the item handle.

create_bitmap(position, options) => id
Create a bitmap canvas item. Returns the item handle.

create_image(position, options) => id
Create an image canvas item. Returns the item handle.

create_line(coords, options) => id
Create a line canvas item. Returns the item handle.

create_oval(bbox, options) => id
Create an oval canvas item. Returns the item handle.

create_polygon(coords, options) => id
Create a polygon canvas item. Returns the item handle.

create_rectangle(bbox, options) => id
Create a rectangle canvas item. Returns the item handle.

create_text(position, options) => id
Create a text canvas item. Returns the item handle.

create_window(position, options) => id
Place a Tkinter widget on the canvas. Returns the item handle.

Note that widgets are drawn on top of the canvas (that is, the canvas acts like a geometry manager). You cannot draw other canvas items on top of a widget.

delete(items)
Delete all matching items. It is not an error to give an item specifier that doesn't match any items.

itemcget(item, option) => string
Get the current value for an option. If item refers to more than one items, this method returns the option value for the first item found.

itemconfig(item, options), itemconfigure(item, options)
Change one or more options for all matching items.

coords(item) => list
Return the coordinates for the given item. If item refers to more than one items, this method returns the coordinates for the first item found.

coords(item, x0, y0, x1, y1, ..., xn, yn)
Change the coordinates for the given item. This method updates all matching items.

bbox(items) => tuple, bbox() => tuple
Returns the bounding box for the given items. If the specifier is omitted, the bounding box for all items are returned. Note that the bounding box is approximate and may differ a few pixels from the real value.

canvasx(screenx) => float, canvasy(screeny) => float
Convert a window coordinate (for example, the x and y coordinates from the structure passed to an event handler) to a canvas coordinate.

tag_bind(item, sequence, callback), tag_bind(item, sequence, callback, "+")
Add an event binding to all matching items. 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 the items, not the tag. For example, if you attach bindings to all items having the movable tag, they will only be attached to any existing items with that tag. If you create new items tagged as movable, they will not get those bindings.

tag_unbind(item, sequence)
Remove the binding, if any, for the given event sequence. This applies to all matching items.

type(item) => string
Return the type of the given item: "arc", "bitmap", "image", "line", "oval", "polygon", "rectangle", "text", or "window". If item refers to more than one items, this method returns the type of the first item found.

lift(item), tkraise(item)
Move the given item to the top of the canvas stack. If multiple items match, they are all moved, with their relative order preserved.

This method doesn't work with window items. To change their order, use lift on the widget instance instead.

lower(item)
Move the given item to the bottom of the canvas stack. If multiple items match, they are all moved, with their relative order preserved.

This method doesn't work with window items. To change their order, use lower on the widget instance instead.

move(item, dx, dy)
Move all items dx canvas units to the right, and dy canvas units downwards. Both coordinates can be negative.

scale(item, xscale, yscale, xoffset, yoffset)
Scale matching items according to the given scale factors. The coordinates for each item are first moved by -offset, then multiplied with the scale factory, and then moved back again. Note that this method modifies the item coordinates; you may loose precision if you use this method several times on the same items.

Printing

postscript(options)
Generate a Postscript rendering of the canvas contents. Images and embedded widgets are not included.

Table 12-1. Postscript Options

Option

Type

Description

colormap

colormode

file

fontmap

height

pageanchor

pageheight

pagewidth

pagex

pagey

rotate

width

x

y

Searching for Items

The following methods are used to find certain groups of items, for later processing. Note that for each find method, there is a corresponding addtag method. Instead of processing the individual items returned by a find method, you can often get better performance by adding a temporary tag to a group of items, process all items with that tag in one go, and then remove the tag.

find_above(item) => item
Returns the item just above the given item.

find_all() => tuple
Return a tuple containing the identity of all items on the canvas, with the topmost item last (that is, if you haven't change the order using lift or lower, the items are returned in the order you created them). This is shortcut for find_withtag(ALL).

find_below(item) => item
Returns the item just below the given item.

find_closest(x, y) => item
Returns the item closest to the given position. Note that the position is given in canvas coordinates, and that this method always succeeds if there's at least one item in the canvas. To find items within a certain distance from a position, use find_overlapping with a small rectangle centered on the position.

find_enclosed(x1, y1, x2, y2) => tuple
Returns a tuple of all items completely enclosed by the rectangle (x1, y1, x2, y2).

find_overlapping(x1, y1, x2, y2) => tuple
Returns a tuple of all items that overlap the given rectangle, or that are completely enclosed by it.

find_withtag(item) => tuple
Returns a tuple of all items having the given specifier.

Manipulating Tags

The following methods are used to manipulate the tags, rather than the items themselves.

addtag_above(newtag, item)
Add newtag to the item just above the given item.

addtag_all(newtag)
Add newtag to all items on the canvas. This is shortcut for addtag_withtag(newtag, ALL).

addtag_below(newtag, item)
Add newtag to the item just below the given item.

addtag_closest(newtag, x, y)
Add newtag to the item closest to the given coordinate. See find_closest for more information.

addtag_enclosed(newtag, x1, y1, x2, y2)
Add newtag to all items enclosed by the given rectangle. See find_enclosed for more information.

addtag_overlapping(newtag, x1, y1, x2, y2)
Add newtag to all items overlapping the given rectangle. See find_overlapping for more information.

addtag_withtag(newtag, tag)
Add newtag to all items having the given tag.

dtag(item, tag)
Remove the given tag from all matching items. If the tag is omitted, all tags are removed from the matching items. It is not an error to give a specifier that doesn't match any items.

gettags(item) => tuple
Return all tags associated with the item.

Special Methods for Text Items

The following methods can be used with text items, as well as with any extension item type that supports a keyboard focus and an insertion cursor.

dchars()
FIXME

focus()
FIXME

icursor()
FIXME

index() => integer
FIXME

insert()
FIXME

select_adjust(item, index)
FIXME

select_clear()
FIXME

select_from(item, index)
FIXME

select_item()
FIXME

select_to(item, index)
FIXME


Scrolling

The following methods are used to scroll the canvas in various ways. The scan methods can be used to implement fast mouse pan/roam operations, while the xview and yview methods are used with standard scrollbars.

scan_mark(x, y)
Set the scanning anchor for fast horizontal scrolling to the given mouse coordinate.

scan_dragto(x, y)
Scrolls the widget contents according to the given mouse coordinate. The contents are moved 10 times the distance between the scanning anchor and the new position.

xview(MOVETO, offset), yview(MOVETO, offset)
Adjust the canvas so that the given offset is at the left (top) edge of the canvas. Offset 0.0 is the beginning of the scrollregion, 1.0 the end. These methods are used by the Scrollbar bindings.

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 canvas horizontally (vertically) by the given amount. The what argument can be either UNITS (lines) or PAGES. These methods are used by the Scrollbar bindings.

These constants are not defined in Python 1.5.2 and earlier. For compatibility, use the strings "scroll", "units", and "pages" instead.