Canvas#

Canvas is tkinter’s drawing surface (tk.Canvas) — a 2-D area that holds items (lines, shapes, text, images, embedded widgets) you create, move, restyle, and delete by id or tag. It is themed by ttkbootstrap. This page is the complete reference for its own options and methods; the shared widget methods are under Capabilities.

Items, ids, and tags#

create_* returns an integer id that names one item. You can also attach tags (string labels) to items, and any method that takes tagOrId acts on a single id or on every item carrying a tag — so "all" (a predefined tag) addresses the whole canvas. Coordinates are in canvas space, which the scrollregion and the xview/yview methods pan over.

Options#

Option

Type

Description

autostyle

bool

Constructor only. True (default) paints the canvas with the active theme and repaints on a theme switch; False opts out. This is ttkbootstrap’s one addition — everything below is native tk.

background (bg)

str

The surface color.

width

int

The requested width in pixels.

height

int

The requested height in pixels.

borderwidth (bd)

int

The 3-D border width in pixels.

relief

str

The border style: "flat", "raised", "sunken", "groove", "ridge", or "solid".

highlightthickness

int

The width of the focus highlight around the widget.

highlightcolor

str

The focus-highlight color when the widget has focus.

highlightbackground

str

The focus-highlight color when the widget does not have focus.

scrollregion

tuple

The scrollable area as (left, top, right, bottom) in canvas coordinates.

confine

bool

Whether to keep the view inside scrollregion.

xscrollcommand

callable

A callback connecting the canvas to a horizontal scrollbar.

yscrollcommand

callable

A callback connecting the canvas to a vertical scrollbar.

xscrollincrement

int

The step size for horizontal “unit” scrolling, in pixels.

yscrollincrement

int

The step size for vertical “unit” scrolling, in pixels.

selectbackground

str

The background of selected text within an editable text item.

selectforeground

str

The foreground of selected text within an editable text item.

selectborderwidth

int

The border width of the selection, in pixels.

insertbackground

str

The color of the text insert cursor.

insertwidth

int

The width of the insert cursor, in pixels.

insertborderwidth

int

The border width of the insert cursor, in pixels.

insertontime

int

The insert-cursor blink on-time, in milliseconds.

insertofftime

int

The insert-cursor blink off-time, in milliseconds.

state

str

The default item state: "normal", "disabled", or "hidden".

closeenough

float

How near (in pixels) the pointer must be to count as “over” an item.

offset

str

The origin for tiled stipple/fill patterns.

cursor

str

The mouse cursor over the canvas (see Cursors).

takefocus

bool

Whether the canvas accepts keyboard focus.

Methods#

Creating items#

Each create_* takes the item’s coordinates followed by keyword options and returns the new item’s integer id. Common options: fill, outline, width, stipple, dash, state, and tags.

create_line(x0, y0, x1, y1, ..., **options)

Draw a line (or multi-point path) through the given points.

Parameters:

options – fill, width, dash, arrow ("first"/"last"/"both"), smooth, capstyle, joinstyle, tags.

Returns:

the new item id.

Return type:

int

create_rectangle(x0, y0, x1, y1, **options)

Draw a rectangle from two opposite corners.

Parameters:

options – fill, outline, width, dash, state, tags.

Returns:

the new item id.

Return type:

int

create_oval(x0, y0, x1, y1, **options)

Draw an ellipse bounded by the given rectangle.

Returns:

the new item id.

Return type:

int

create_polygon(x0, y0, x1, y1, ..., **options)

Draw a closed polygon through three or more points.

Parameters:

options – fill, outline, width, smooth, tags.

Returns:

the new item id.

Return type:

int

create_arc(x0, y0, x1, y1, **options)

Draw an arc, chord, or pie slice within the bounding rectangle.

Parameters:

options – start (degrees), extent (degrees), style ("pieslice"/"chord"/"arc"), fill, outline, tags.

Returns:

the new item id.

Return type:

int

create_text(x, y, **options)

Place a string of text at a point.

Parameters:

options – text, font, fill, anchor, justify, width (wrap), angle, tags.

Returns:

the new item id.

Return type:

int

create_image(x, y, **options)

Place an image at a point.

Parameters:

options – image (a PhotoImage), anchor, state, tags.

Returns:

the new item id.

Return type:

int

create_bitmap(x, y, **options)

Place a bitmap at a point.

Parameters:

options – bitmap, anchor, foreground, background, tags.

Returns:

the new item id.

Return type:

int

create_window(x, y, **options)

Embed a child widget on the canvas at a point.

Parameters:

options – window (an existing widget), anchor, width, height, tags.

Returns:

the new item id.

Return type:

int

Coordinates and geometry#

coords(tagOrId, *coords)

Get or set an item’s coordinates.

Parameters:

  • tagOrId – the item to address.

  • coords – new coordinates to set; omit to query.

Returns:

the current coordinates (flat list) when queried, else None.

Return type:

list | None

move(tagOrId, dx, dy)

Shift matching items by an offset.

Parameters:

  • dx – horizontal delta, in pixels.

  • dy – vertical delta, in pixels.

Returns:

None.

moveto(tagOrId, x='', y='')

Move matching items so their top-left is at an absolute position.

Returns:

None.

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

Scale matching items about an origin point.

Parameters:

  • xScale – horizontal scale factor.

  • yScale – vertical scale factor.

Returns:

None.

bbox(*tagsOrIds)

Return the bounding box that encloses the matching items.

Returns:

(x1, y1, x2, y2) in pixels, or None if nothing matches.

Return type:

tuple | None

canvasx(screenx, gridspacing=None)

Convert a window x coordinate to a canvas x coordinate (accounting for scrolling), optionally snapped to a grid.

Return type:

float

canvasy(screeny, gridspacing=None)

Vertical counterpart of canvasx().

Return type:

float

Configuring items#

itemconfigure(tagOrId, **options)

Set (or query) options on matching items. Alias: itemconfig.

Parameters:

  • tagOrId – the item(s) to change.

  • options – any options valid for the item type (fill, outline, width, text, state, tags, …).

Returns:

the option spec when queried with a single option name, else None.

itemcget(tagOrId, option)

Return one option of the first matching item.

type(tagOrId)

Return the type of the first matching item.

Returns:

"line", "rectangle", "oval", "polygon", "arc", "text", "image", "bitmap", or "window".

Return type:

str

Finding items#

find_all()

Return the ids of every item, in stacking order.

Return type:

tuple[int, …]

find_withtag(tagOrId)

Return the ids of items matching a tag or id.

Return type:

tuple[int, …]

find_above(tagOrId)

Return the id of the item just above the topmost matching item in the stacking order. find_below(tagOrId) is the downward counterpart.

Return type:

tuple[int, …]

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

Return the single item nearest a point (topmost on ties).

Parameters:

  • halo – treat items within this many pixels as touching the point.

  • start – search below this item in the stacking order.

Return type:

tuple[int]

find_overlapping(x1, y1, x2, y2)

Return the ids of items that overlap the given rectangle.

Return type:

tuple[int, …]

find_enclosed(x1, y1, x2, y2)

Return the ids of items completely enclosed by the given rectangle.

Return type:

tuple[int, …]

Tagging#

gettags(tagOrId)

Return the tags on the first matching item.

Return type:

tuple[str, …]

addtag_withtag(newtag, tagOrId)

Add a tag to every item matching tagOrId. (Companions select by position: addtag_above/_below/_closest/_enclosed/_overlapping/ _all.)

Returns:

None.

dtag(tagOrId, tagToDelete=None)

Remove a tag from matching items (the items themselves remain).

Returns:

None.

Deleting#

delete(*tagsOrIds)

Delete every matching item from the canvas.

Returns:

None.

Item events and stacking#

tag_bind(tagOrId, sequence=None, func=None, add=None)

Bind an event to items — the way to make canvas items clickable/hoverable.

Parameters:

  • sequence – an event sequence, e.g. "<Button-1>".

  • func – the callback, receiving the event object.

  • add – "+" to add rather than replace.

Returns:

a binding id.

Return type:

str

tag_unbind(tagOrId, sequence, funcid=None)

Remove an item binding.

Returns:

None.

tag_raise(tagOrId, aboveThis=None)

Raise matching items in the stacking order (drawn on top). Alias: lift.

Returns:

None.

tag_lower(tagOrId, belowThis=None)

Lower matching items in the stacking order. Alias: lower.

Returns:

None.

Editing text items#

These act on editable text (and window) items, using a character index or the special indices "insert", "end", "sel.first"/"sel.last".

insert(tagOrId, index, string)

Insert text into an item at a character index.

Returns:

None.

dchars(tagOrId, first, last=None)

Delete characters from an item between two indices.

Returns:

None.

index(tagOrId, index)

Resolve a text-item index expression to an integer character position.

Return type:

int

icursor(tagOrId, index)

Move the insert cursor within a text item.

Returns:

None.

select_from(tagOrId, index)

Anchor the selection inside a text item at index; extend it with select_to(tagOrId, index) and select_adjust(tagOrId, index). select_clear() removes the selection, and select_item() returns the id of the item holding it (or None).

Returns:

None.

Scrolling#

xview(*args)

Query or set the horizontal view; usually wired to a scrollbar via xscrollcommand. yview is the vertical counterpart, and both have *_moveto(fraction) and *_scroll(number, what) variants.

Returns:

with no args, the visible fraction (first, last); else None.

Return type:

tuple | None

scan_mark(x, y)

Record a starting point for a fast drag-scroll (paired with scan_dragto).

Returns:

None.

scan_dragto(x, y, gain=10)

Scroll the view relative to the scan_mark point, multiplied by gain.

Returns:

None.

Export#

postscript(**options)

Render the canvas (or a region of it) to PostScript.

Parameters:

options – file= a path or None to return the text; x/y/ width/height for a region; colormode ("color"/"gray"/"mono"); pagewidth/pageheight.

Returns:

the PostScript text when no file is given, else None.

Return type:

str | None

Shared capabilities#

Canvas also has the methods every widget inherits — configuration, placement, event binding, lifecycle, focus, and introspection. These are documented under Capabilities.

See also#