This is an unofficial mirror of Tkinter reference documentation (based on Python 2.7 and Tk 8.5) created by the late John Shipman.
It was last updated in 2013 and is unmaintained. [More info]
All Canvas
objects support these methods:
.addtag_above(newTag
, tagOrId
)
Attaches a new tag to the object just above the one
specified by
in the display list. The tagOrId
argument is the tag you want to attach, as a
string.
newTag
.addtag_all(newTag
)
Attaches the given tag
to all the objects on the canvas.
newTag
.addtag_below(newTag
,
tagOrID
)
Attaches a new tag
to the object just below the one specified by
in the
display list. The
tagOrId
argument is a tag string.
newTag
.addtag_closest(newTag
, x
, y
, halo
=None, start
=None)
Adds a tag to the object closest to screen coordinate (x,y). If there are two or more objects at the same distance, the one higher in the display list is selected.
Use the
argument to increase the effective size of the
point. For example, a value of 5 would treat any
object within 5 pixels of (x,y) as
overlapping.
halo
If an object
ID is passed in the
argument, this method tags the highest qualifying
object that is below
start
in the display list.
start
.addtag_enclosed(newTag
,
x1
,
y1
,
x2
,
y2
)
Add tag
to all objects that occur completely within the
rectangle whose top left corner is
(newTag
,
x1
) and
whose bottom right corner is
(y1
,
x2
).
y2
.addtag_overlapping(newTag
,
x1
,
y1
,
x2
,
y2
)
Like the previous method, but affects all objects that share at least one point with the given rectangle.
.addtag_withtag(newTag
, tagOrId
)
Adds tag
to the object or objects specified by
newTag
.
tagOrId
.bbox(tagOrId=None)
Returns a tuple (x1,
y1,
x2,
y2) describing a rectangle
that encloses all the objects specified by
. If the
argument is omitted, returns a rectangle enclosing
all objects on the canvas. The top left corner of
the rectangle is (x1,
y1) and the bottom right
corner is (x2,
y2).
tagOrId
.canvasx(screenx
,
gridspacing=None)
Translates a window x coordinate
to a canvas coordinate. If
screenx
gridspacing
is supplied, the canvas coordinate is rounded to
the nearest multiple of that value.
.canvasy(screeny
,
gridspacing=None)
Translates a window y coordinate
to a canvas coordinate. If
screeny
gridspacing
is supplied, the canvas coordinate is rounded to
the nearest multiple of that value.
.coords(tagOrId
,
x0
,
y0
,
x1
,
y1
, ...,
xn
,
yn
)
If you pass only the
argument,
returns a tuple of the coordinates of the lowest or
only object specified by that argument. The number
of coordinates depends on the type of object. In
most cases it will be a 4-tuple
(x1,
y1,
x2,
y2) describing the bounding
box of the object.
tagOrId
You can move an object by passing in new coordinates.
.dchars(tagOrId
,
first=0, last=first)
Deletes characters from a text item or items.
Characters between first
and last
inclusive are
deleted, where those values can be integer indices
or the string 'end'
to mean the end
of the text. For example, for a canvas
and an item
C
,
I
will remove the second character.
C
.dchars(I
, 1,
1)
.delete(tagOrId
)
Deletes the object or objects selected by
. It is not
considered an error if no items match tagOrId
.
tagOrId
.dtag(tagOrId, tagToDelete)
Removes the tag
specified by
from the object or objects specified by
tagToDelete
.
tagOrId
.find_above(tagOrId)
Returns the ID number of the object just above the
object specified by
. If multiple
objects match, you get the highest one. Returns an
empty tuple if you pass it the object ID of the
highest object.
tagOrId
.find_all()
Returns a list of the object ID numbers for all objects on the canvas, from lowest to highest.
.find_below(tagOrId
)
Returns the object
ID of the object just below the one
specified by
. If multiple
objects match, you get the lowest one. Returns an
empty tuple if you pass it the object ID of the
lowest object.
tagOrId
.find_closest(x
,
y
,
halo
=None,
start
=None)
Returns a singleton tuple containing the object ID of the object
closest to point (
. If there
are no qualifying objects, returns an empty tuple.
x
,
y
)
Use the
argument
to increase the effective size of the point. For
example, halo
halo=5
would treat any
object within 5 pixels of (
as
overlapping.
x
,
y
)
If an object ID is passed as the
argument, this method returns the highest
qualifying object that is below
start
in
the display
list.
start
.find_enclosed(x1
,
y1
,
x2
,
y2
)
Returns a list of the object IDs of all
objects that occur completely within the rectangle
whose top left corner is
(
and
bottom right corner is
x1
,
y1
)(
.
x2
,
y2
)
.find_overlapping(x1
,
y1
,
x2
,
y2
)
Like the previous method, but returns a list of the object IDs of all the objects that share at least one point with the given rectangle.
.find_withtag(tagOrId
)
Returns a list of the object IDs of the
object or objects specified by
.
tagOrId
.focus(tagOrId
=None)
Moves the focus to the object specified by
. If
there are multiple such objects, moves the focus to
the first one in the display list that
allows an insertion cursor. If there are no
qualifying items, or the canvas does not have
focus, focus does not move.
tagOrId
If the argument is omitted, returns the ID of
the object that has focus, or
''
if none of them
do.
.gettags(tagOrId
)
If
is an
object ID, returns a list of all the tags
associated with that object. If the argument is a
tag, returns all
the tags for the lowest object that has that
tag.
tagOrId
.icursor(tagOrId
,
index
)
Assuming that the selected item allows text
insertion and has the focus, sets the insertion
cursor to
,
which may be either an integer index or the string
index
'end'
. Has no effect
otherwise.
.index(tagOrId
,
specifier
)
Returns the integer index of the given
in
the text item specified by specifier
(the lowest
one that, if tagOrId
specifies multiple objects). The return value is
the corresponding position as an integer, with the
usual Python convention, where 0 is the position
before the first character.
tagOrId
The
argument may be any of:
specifier
tk.INSERT
, to return the current
position of the insertion cursor.
tk.END
, to return the position
after the last character of the item.
tk.SEL_FIRST
, to return the
position of the start of the current text
selection. Tkinter will raise a tk.TclError
exception if the text item
does not currently contain the text selection.
tk.SEL_LAST
, to return the position
after the end of the current text selection, or
raise tk.TclError
if the item does
not currently contain the selection.
A string of the form “@
”, to return
the character of the character containing
canvas coordinates x
,y
(
. If those coordinates are above or
to the left of the text item, the method
returns 0; if the coordinates are to the right
of or below the item, the method returns the
index of the end of the item.
x
, y
)
.insert(tagOrId
,
specifier
,
text
)
Inserts the given
into the
object or objects specified by string
, at the
position given by the tagOrId
argument.
specifier
The
values may be:
specifier
Any of the keywords tk.INSERT
,
tk.END
, tk.SEL_FIRST
,
or tk.SEL_LAST
. Refer to the
description of the index
method
above for the interpretation of these codes.
The position of the desired insertion, using the normal Python convention for positions in strings.
.itemcget(tagOrId
,
option
)
Returns the value of the given configuration
in the
selected object (or the lowest object if option
specifies
more than one). This is similar to the tagOrId
.cget()
method for Tkinter objects.
.itemconfigure(tagOrId
, option
, ...)
If no
arguments are supplied, returns a dictionary whose
keys are the options of the object specified by
option
(the
lowest one, if
tagOrId
specifies multiple objects).
tagOrId
To change the configuration option of the specified
item, supply one or more keyword arguments of the
form
.
option
=value
.move(tagOrId
,
xAmount
,
yAmount
)
Moves the items specified by
by adding
tagOrId
to their x coordinates and
xAmount
to their y coordinates.
yAmount
.postscript(option
,
...)
Generates an Encapsulated PostScript representation of the canvas's current contents. The options include:
colormode |
Use 'color' for color
output, 'gray' for
grayscale, or 'mono' for
black and white.
|
file | If supplied, names a file where the PostScript will be written. If this option is not given, the PostScript is returned as a string. |
height | How much of the Y size of the canvas to print. Default is the entire visible height of the canvas. |
rotate | If false, the page will be rendered in portrait orientation; if true, in landscape. |
x | Leftmost canvas coordinate of the area to print. |
y | Topmost canvas coordinate of the area to print. |
width | How much of the X size of the canvas to print. Default is the visible width of the canvas. |
.scale(tagOrId
,
xOffset
,
yOffset
,
xScale
,
yScale
)
Scale all objects according to their distance from
a point P=(
, xOffset
). The
scale factors yOffset
and
xScale
are based on a value of 1.0, which means no
scaling. Every point in the objects selected by
yScale
is moved so
that its x distance from P is multiplied by tagOrId
and its
y distance is multiplied by xScale
.
yScale
This method will not change the size of a text item, but may move it.
.scan_dragto(x
,
y
, gain
=10.0)
See the .scan_mark()
method below.
.scan_mark(x
,
y
)
This method is used to implement fast scrolling of a canvas. The intent is that the user will press and hold a mouse button, then move the mouse up to scan (scroll) the canvas horizontally and vertically in that direction at a rate that depends on how far the mouse has moved since the mouse button was depressed.
To implement this feature, bind the mouse's
button-down event to a handler that calls scan_mark(
where x
,
y
)
and x
are the
current mouse coordinates. Bind the y
<Motion>
event to a handler that,
assuming the mouse button is still down, calls
scan_dragto(
where x
,
y
, gain
)
and x
are the
current mouse coordinates.
y
The
argument controls the rate of scanning. This
argument has a default value of 10.0. Use larger
numbers for faster scanning.
gain
.select_adjust(oid
, specifier
)
Adjusts the boundaries of the current text
selection to include the position given by the
argument, in the text item with the object ID specifier
.
oid
The current selection anchor is also set to the
specified position. For a discussion of the
selection anchor, see the canvas select_from
method below.
For the values of
, see the canvas
specifier
insert
method above.
.select_clear()
Removes the current text selection, if it is set. If there is no current selection, does nothing.
.select_from(oid
, specifier
)
This method sets the selection
anchor to the position given by the
argument, within the text item whose object ID is given by
specifier
.
oid
The currently selected text on a given canvas is specified by three positions: the start position, the end position, and the selection anchor, which may be anywhere within those two positions.
To change the position of the currently selected
text, use this method in combination with the select_adjust
, select_from
,
and select_to
canvas methods (q.v.).
.select_item()
If there is a current text selection on this
canvas, return the object ID of the text
item containing the selection. If there is no
current selection, this method returns None
.
.select_to(oid
,
specifier
This method changes the current text selection so
that it includes the select anchor and the position
given by
within the text
item whose object
ID is given by specifier
. For the values of
oid
, see the canvas specifier
insert
method
above.
.tag_bind(tagOrId
,
sequence
=None, function=None,
add=None)
Binds events to objects on the canvas. For the
object or objects selected by
,
associates the handler
tagOrId
with the event
function
.
If the
sequence
argument is a string starting with
add
'+'
, the new binding is
added to existing bindings for the given
,
otherwise the new binding replaces that for the
given
sequence
.
sequence
For general information on event bindings, see Section 54, “Events”.
Note that the bindings are applied to items that
have this tag at the time of the tag_bind
method call. If tags are later
removed from those items, the bindings will persist
on those items. If the tag you specify is later
applied to items that did not have that tag when
you called tag_bind
, that binding
will not be applied to the
newly tagged items.
.tag_lower(tagOrId
,
belowThis
)
Moves the object or objects selected by
within the
display list to
a position just below the first or only object
specied by the tag or ID tagOrId
.
belowThis
If there are multiple items with tag
,
their relative stacking order is preserved.
tagOrId
This method does not affect canvas window items.
To change a window item's stacking order, use a
lower
or lift
method
on the window.
.tag_raise(tagOrId
,
aboveThis
)
Moves the object or objects selected by
within the
display list to
a position just above the first or only object
specied by the tag or ID tagOrId
.
aboveThis
If there are multiple items with tag
,
their relative stacking order is preserved.
tagOrId
This method does not affect canvas window items.
To change a window item's stacking order, use a
lower
or lift
method
on the window.
.tag_unbind(tagOrId
,
sequence
, funcId
=None)
Removes bindings for handler
and
event funcId
from
the canvas object or objects specified by sequence
. See Section 54, “Events”.
tagOrId
.type(tagOrId
)
Returns the type of the first or only object
specified by
. The
return value will be one of the strings
tagOrId
'arc'
,
'bitmap'
,
'image'
,
'line'
,
'oval'
,
'polygon'
,
'rectangle'
,
'text'
, or
'window'
.
.xview(tk.MOVETO,
fraction
)
This method scrolls the canvas relative to its
image, and is intended for binding to the command
option of a related scrollbar.
The canvas is scrolled horizontally to a position
given by
, where
0.0 moves the canvas to its leftmost position and
1.0 to its rightmost position.
offset
.xview(tk.SCROLL, n
,
what
)
This method moves the canvas left or right: the
argument specifies how much to move and can be
either what
tk.UNITS
or tk.PAGES
, and
tells how many units to move the canvas to the
right relative to its image (or left, if negative).
n
The size of the move for tk.UNITS
is
given by the value of the canvas's xscrollincrement
option; see Section 22, “The Scrollbar
widget”.
For movements by tk.PAGES,
is multiplied
by nine-tenths of the width of the canvas.
n
.xview_moveto(fraction
)
This method scrolls the canvas in the same way as
.xview(tk.MOVETO,
.
fraction
)
.xview_scroll(n
,
what
)
Same as .xview(tk.SCROLL,
.
n
,
what
)
.yview(tk.MOVETO,
fraction
)
The vertical scrolling equivalent of
.xview(tk.MOVETO,…)
.
.yview(tk.SCROLL, n
,
what
)
The vertical scrolling equivalent of
.xview(tk.SCROLL,…)
.
.yview_moveto(fraction
)
The vertical scrolling equivalent of .xview()
.
.yview_scroll(n
,
what
)
The vertical scrolling equivalents of .xview()
, .xview_moveto()
,
and .xview_scroll()
.