Next / Previous / Contents / Shipman's homepage

8. The Canvas widget

A canvas is a rectangular area intended for drawing pictures or other complex layouts. On it you can place graphics, text, widgets, or frames. See the following sections for methods that create objects on canvases:

To create a Canvas object:

    w = tk.Canvas(parent, option=value, ...)

The constructor returns the new Canvas widget. Supported options include:

Table 6. Canvas widget options

bd or borderwidth Width of the border around the outside of the canvas; see Section 5.1, “Dimensions”. The default is two pixels.
bg or background Background color of the canvas. Default is a light gray, about '#E4E4E4'.
closeenough A float that specifies how close the mouse must be to an item to be considered inside it. Default is 1.0.
confine If true (the default), the canvas cannot be scrolled outside of the scrollregion (see below).
cursor Cursor used in the canvas. See Section 5.8, “Cursors”.
height Size of the canvas in the Y dimension. See Section 5.1, “Dimensions”.
highlightbackground Color of the focus highlight when the widget does not have focus. See Section 53, “Focus: routing keyboard input”.
highlightcolor Color shown in the focus highlight.
highlightthickness Thickness of the focus highlight. The default value is 1.
relief The relief style of the canvas. Default is tk.FLAT. See Section 5.6, “Relief styles”.
scrollregion A tuple (w, n, e, s) that defines over how large an area the canvas can be scrolled, where w is the left side, n the top, e the right side, and s the bottom.
selectbackground The background color to use displaying selected items.
selectborderwidth The width of the border to use around selected items.
selectforeground The foreground color to use displaying selected items.
takefocus Normally, focus (see Section 53, “Focus: routing keyboard input”) will cycle through this widget with the tab key only if there are keyboard bindings set for it (see Section 54, “Events” for an overview of keyboard bindings). If you set this option to 1, focus will always visit this widget. Set it to '' to get the default behavior.
width Size of the canvas in the X dimension. See Section 5.1, “Dimensions”.
xscrollincrement Normally, canvases can be scrolled horizontally to any position. You can get this behavior by setting xscrollincrement to zero. If you set this option to some positive dimension, the canvas can be positioned only on multiples of that distance, and the value will be used for scrolling by scrolling units, such as when the user clicks on the arrows at the ends of a scrollbar. For more information on scrolling units, see Section 22, “The Scrollbar widget”.
xscrollcommand If the canvas is scrollable, set this option to the .set() method of the horizontal scrollbar.
yscrollincrement Works like xscrollincrement, but governs vertical movement.
yscrollcommand If the canvas is scrollable, this option should be the .set() method of the vertical scrollbar.

8.1. Canvas coordinates

Because the canvas may be larger than the window, and equipped with scrollbars to move the overall canvas around in the window, there are two coordinate systems for each canvas:

  • The window coordinates of a point are relative to the top left corner of the area on the display where the canvas appears.

  • The canvas coordinates of a point are relative to the top left corner of the total canvas.