9.5. Canvas Options
The options listed in this section affect the entire Canvas widget
and the items within it (such as circles, lines, rectangles, text, or
other widgets). The following options act as you would expect (as
explained in Chapter 4, "
Button, Checkbutton, and Radiobutton Widgets" for most options and in
Chapter 6, "The Scrollbar Widget" for the Scrollbar options):
There are also several options that
are unique to the Canvas widget. When selecting items in the Canvas
with the mouse cursor, the Canvas widget does calculations to
determine if the mouse cursor is inside or outside the item. The
-closeenough option controls
how close the mouse must be to the item before it is considered
inside the item. The default value for
-closeenough is "1.0", which is
1.0 pixels away. Any floating-point number is a valid value (and will
always be in pixels) for -closeenough.
discussed the -scrollregion option briefly in
Section 9.3, "The Scrollable Region" earlier in this chapter. It takes
an array reference, which must contain four coordinates. The
coordinates indicate a bounding region for the scrollable area in the
Canvas. The coordinates are in this order: [
maxy ]. You can also
think of the coordinates as if they were defining the [
left, top, right, bottom ] edges of the scrollable region.
Canvas widget limits the user to seeing only the area defined by the
-scrollregion option. You can
allow the user to scroll beyond this area by using -confine
=> 0. The default for -confine is 1.
9.5.1. Common Canvas Dash, Stipple, and Tile Options
Jan Nijtman's "dash and
image" patches have been incorporated into Perl/Tk. In Chapter 17, "Images and Animations" we investigate the basic features of stipples
and Jan's tiles. Here we introduce his Canvas "dash and
tile" options. They are applicable to most Canvas items,
although only -state and
-updatecommand apply to embedded widgets.
The following describes a dashSpec and
specifies how a dashed line is drawn.
- -activedash => dashSpec
the dash pattern of an active item.
- -activefill => color
the fill color of an active item.
- -activeoutline => color
Specifies the outline color of an active item.
- -activeoutlinestipple => bitmap
Specifies the outline stipple of an
- -activeoutlinetile => image
Specifies the outline tile of an active
- -activestipple => bitmap
Specifies the stipple of an active item.
- -activewidth => outlineWidth
Specifies the outline width of an active
- -dash => dashSpec
list of integers representing the number of pixels of a line segment
(odd segments are the outline color; even segments are transparent)
or a character list containing only the five characters .,-_
-dash => '.' = -dash => [2,4]
-dash => '-' = -dash => [6,4]
-dash => '-.' = -dash => [6,4,2,4]
-dash => '-..' = -dash => [6,4,2,4,2,4]
-dash => '. ' = -dash => [2,8]
-dash => ',' = -dash => [4,4]
- -dashoffset => integer
the offset in the dash list where the drawing starts.
- -disableddash => dashSpec
Specifies the dash pattern for a disabled
- -disabledfill => color
Specifies the fill color of a disabled
- -disableoutline => color
Specifies the outline color of a disabled
- -disabledoutlinestipple => bitmap
Specifies the outline stipple of a
- -disabledoutlinetile => image
Specifies the outline tile of a disabled
- -disabledstipple => bitmap
Specifies the stipple of a disabled item.
- -disabledwidth => outlineWidth
Specifies the outline width of a disabled
- -outline => color
Specifies the outline color of an
- -outlinestipple => bitmap
Specifies the outline stipple of an item.
- -outlinetile => image
Specifies the outline tile of an item.
- -state => normal | disabled | hidden
Specifies the state of the Canvas item.
Overrides the Canvas' global -state option.
- -stipple => bitmap
Specifies the stipple of an item.
- -updatecommand => callback
Specifies the callback invoked when an
item is updated on the display.
- -width => outlineWidth
Specifies the outline width of an item.
9.5.2. Additional Scrolling Options
and -yscrollcommand options both work as described
in Chapter 6, "The Scrollbar Widget", but there are two additional options
that affect how the Canvas scrolls its contents:
-yscrollincrement. Each option takes a valid
screen distance for a value. This distance is the unit the Canvas
will use to scroll in the associated direction. For instance, if you
specify -xscrollincrement =>
10, each time you click an arrow on the horizontal
Scrollbar, the contents of the Canvas will shift so the left edge of
the contents is an even multiple of 10. Essentially, the Canvas will
shift the contents 10 pixels in the arrow's direction.
If the value associated with -xscrollincrement or
-yscrollincrement is 0 or less, scrolling is done
in normal increments.
9.5.3. Canvas Widget Option List
These options all are used with the
- -background => color
Sets the background of the
Canvas to color.
- -borderwidth => amount
Changes the width of the edges of the
Canvas to amount.
- -closeenough => float_amount
Sets the amount of distance from the item
when the cursor is considered inside the item.
- -confine => 1 | 0
that the Canvas will limit itself to the area defined by
-scrollregion if set to 1.
- -cursor => cursorname
Indicates that the cursor will change to
cursorname when it is over the Canvas.
- -height => amount
Sets the height of the Canvas to
- -highlightbackground => color
the color the highlight rectangle should be when the Canvas does not
have the keyboard focus.
- -highlightcolor => color
Sets the color the highlight
rectangle should be when the Canvas has the keyboard focus.
- -highlightthickness => amount
the thickness of the highlight rectangle. Default is 2.
- -insertbackground => color
the color of the area behind the text insert cursor.
- -insertborderwidth => amount
Sets the width of the borders on the insert cursor.
- -insertofftime => milliseconds
Sets the amount of time the cursor disappears from the screen when it
is blinking off.
- -insertontime => milliseconds
the amount of time the cursor appears on the screen when it is
- -insertwidth => amount
Sets the width of the insert cursor.
- -relief => 'flat'|'groove'|'raised'|'ridge'|'sunken'|'solid'
Indicates the way the edges of the Canvas
- -scrollregion => [ left, top, right, bottom ]
the area the user is allowed to scroll.
- -selectbackground => color
Sets the color of the area behind any
- -selectborderwidth => amount
Sets the width of the border of the
- -selectforeground => color
Sets the color of the selected text.
- -takefocus => 0 | 1 | undef
Determines whether or not the Canvas can
get keyboard focus. Default is for the application to decide.
- -width => amount
Sets the width of the Canvas to amount.
- -xscrollcommand => callback
Determines the callback used when the Canvas is scrolled horizontally
(automatically set to the correct callback when the
Scrolled method is used).
- -xscrollincrement => amount
Sets the distance the Canvas contents
move when the arrow on the horizontal Scrollbar is clicked.
- -yscrollcommand => callback
Determines the callback used when the Canvas is scrolled vertically.
- -yscrollincrement => amount
Sets the distance the Canvas contents
move when the arrow on the vertical Scrollbar is clicked.