6.2. Methods on Canvas objects

6.2. Methods on `Canvas` objects

All Canvas objects support these methods:

.addtag_above ( newTag, tagOrId )

Attaches a new tag to the object just above the one specified by tagOrId in the display list. The newTag argument is the tag you want to attach, as a string.

.addtag_all ( newTag )

Attaches the given tag newTag to all the objects on the canvas.

.addtag_below ( newTag, tagOrID )

Attaches a new tag to the object just below the one specified by tagOrId in the display list. The newTag argument is a tag string.

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

If an object ID is passed in the start argument, this method tags the highest qualifying object that is below start in the display list. This allows you to search through all the overlapping objects sequentially.

.addtag_enclosed ( newTag, x1, y1, x2, y2)

Add tag newTag to all objects that occur completely within the rectangle whose top left corner is (x1, y1) and whose bottom right corner is (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 newTag to the object or objects specified by tagOrId.

.bbox ( tagOrId=None )

Returns a tuple (x₁, y₁, x₂, y₂) describing a rectangle that encloses all the objects specified by tagOrId. If the argument is omitted, returns a rectangle enclosing all objects on the canvas. The top left corner of the rectangle is (x₁, y₁) and the bottom right corner is (x₂, y₂).

.canvasx ( screenx, gridspacing=None )

Translates a window x coordinate screenx to a canvas coordinate. If gridspacing is supplied, the canvas coordinate is rounded to the nearest multiple of that value.

.canvasy ( screenx, gridspacing=None )

Translates a window y coordinate screeny to a canvas coordinate. If 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 tagOrId 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 (x₁, y₁, x₂, y₂) describing the bounding box of the object.

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 are deleted, where those values can be integer indices or the string "end" to mean the end of the text.

.delete ( tagOrId )

Deletes the object or objects selected by tagOrId.

.dtag ( tagOrId, tagToDelete )

Removes the tag specified by tagToDelete from the object or objects specified by tagOrId.

.find_above ( tagOrId )

Returns the ID number of the object just above the object specified by tagOrId. If multiple objects match, you get the highest one.

.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 tagOrId. If multiple objects match, you get the lowest one.

.find_closest ( x, y, halo=None, start=None )

Returns a singleton tuple containing the object ID of the object closest to point (x, y). If there are no qualifying objects, returns an empty tuple.

Use the halo argument to increase the effective size of the point. For example, halo=5 would treat any object within 5 pixels of (x, y) as overlapping.

If an object ID is passed as the start argument, this method returns the highest qualifying object that is below start in the display list.

.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 (x1, y1) and bottom right corner is (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 tagOrId. 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.

If the argument is omitted, returns the ID of the object that has focus, or "" if none of them do.

.gettags ( tagOrId )

If tagOrId 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.

.icursor ( tagOrId, index )

Assuming that the selected item allows text insertion and has the focus, sets the insertion cursor to index, which may be either an integer index or the string "end". Has no effect otherwise.

.index ( tagOrId, index )

Returns the integer index of the given index in the object specified by tagOrId (the lowest one that allows text insertion, if tagOrId specifies multiple objects). The index argument is an integer or the string "end".

.insert ( tagOrId, beforeThis, text )

Inserts the given string in the object or objects specified by tagOrId, before index beforethis (which can be an integer or the string "end").

.itemcget ( tagOrId, option )

Returns the value of the given configuration option in the selected object (or the lowest object if tagOrId specifies more than one). This is similar to the .cget() method for Tkinter objects.

.itemconfigure ( tagOrId, option, ... )

If no option arguments are supplied, returns a dictionary whose keys are the options of the object specified by tagOrId (the lowest one, if tagOrId specifies multiple objects).

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 tagOrId by adding xAmount to their x coordinates and yAmount to their y coordinates.

.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 all.
`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 all.

.scale ( tagOrId, xOrigin, yOrigin, xScale, yScale )

Scale all objects according to their distance from a point P=(xOrigin, yOrigin). The scale factors xScale and yScale are based on a value of 1.0, which means no scaling. Every point in the objects selected by tagOrId is moved so that its x distance from P is multiplied by xScale and its y distance is multiplied by yScale.

.tag_bind ( tagOrId, sequence=None, function=None, add=None )

Binds events to objects on the canvas. For the object or objects selected by tagOrId, associates the handler function with the event sequence. If the add argument is a string starting with "+", the new binding is added to existing bindings for the given sequence, otherwise the new binding replaces that for the given sequence.

For general information on event bindings, see Section 24, “Events”.

.tag_lower ( tagOrId, belowThis )

Moves the object or objects selected by tagOrId within the display list to a position just below the first or only object specied by the tag or ID belowThis.

.tag_raise ( tagOrId, aboveThis )

Moves the object or objects selected by tagOrId within the display list to a position just above the first or only object specied by the tag or ID aboveThis.

.tag_unbind ( tagOrId, sequence, funcId=None )

Removes bindings for handler funcId and event sequence from the canvas object or objects specified by tagOrId. See Section 24, “Events”.

.type ( tagOrId )

Returns the type of the first or only object specified by tagOrId. The return value will be one of the strings "arc", "bitmap", "image", "line", "oval", "polygon", "rectangle", "text", or "window".

.xview ( 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 offset, where 0.0 moves the canvas to its leftmost position and 1.0 to its rightmost position.

.xview ( SCROLL, n, what )

This method moves the canvas left or right: the what argument specifies how much to move and can be either UNITS or PAGES, and n tells how many units to move the canvas to the right relative to its image (or left, if negative).

The size of the move for UNITS is given by the value of the canvas's xscrollincrement option; see Section 16, “The Scrollbar widget”.

For movements by PAGES, n is multiplied by nine-tenths of the width of the canvas.

.xview_moveto ( fraction )

This method scrolls the canvas in the same way as .xview(MOVETO, fraction).

.xview_scroll ( n, what )

Same as .xview(SCROLL, n, what).

.yview ( MOVETO, fraction )

The vertical scrolling equivalent of .xview(MOVETO,…).

.yview ( SCROLL, n, what )

The vertical scrolling equivalent of .xview(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().

Tkinter reference: a GUI for Python

6.2. Methods on Canvas objects

6.2. Methods on `Canvas` objects