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):
-background, -borderwidth,
-cursor, -height,-highlightbackground,
-highlightcolor,
-highlightthickness, -relief,
-takefocus, -width,
-xscrollcommand, and
-yscrollcommand.
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.
We
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: [
minx,
miny,
maxx,
maxy ]. You can also
think of the coordinates as if they were defining the [
left, top, right, bottom ] edges of the scrollable region.
Normally the
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
-
Specifies
the dash pattern of an active item.
- -activefill => color
-
Specifies
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
active item.
- -activeoutlinetile => image
-
Specifies the outline tile of an active
item.
- -activestipple => bitmap
-
Specifies the stipple of an active item.
- -activewidth => outlineWidth
-
Specifies the outline width of an active
item.
- -dash => dashSpec
-
Specifies a
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 .,-_
>.For example:
-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
-
Specifies
the offset in the dash list where the drawing starts.
- -disableddash => dashSpec
-
Specifies the dash pattern for a disabled
item.
- -disabledfill => color
-
Specifies the fill color of a disabled
item.
- -disableoutline => color
-
Specifies the outline color of a disabled
item.
- -disabledoutlinestipple => bitmap
-
Specifies the outline stipple of a
disabled item.
- -disabledoutlinetile => image
-
Specifies the outline tile of a disabled
item.
- -disabledstipple => bitmap
-
Specifies the stipple of a disabled item.
- -disabledwidth => outlineWidth
-
Specifies the outline width of a disabled
item.
- -outline => color
-
Specifies the outline color of an
item.
- -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
The -xscrollcommand
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:
-xscrollincrement and
-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
Canvas method:
- -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
-
Indicates
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
amount.
- -highlightbackground => color
-
Sets
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
-
Sets
the thickness of the highlight rectangle. Default is 2.
- -insertbackground => color
-
Sets
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
-
Sets
the amount of time the cursor appears on the screen when it is
blinking on.
- -insertwidth => amount
-
Sets the width of the insert cursor.
- -relief => 'flat'|'groove'|'raised'|'ridge'|'sunken'|'solid'
-
Indicates the way the edges of the Canvas
are drawn.
- -scrollregion => [ left, top, right, bottom ]
-
Defines
the area the user is allowed to scroll.
- -selectbackground => color
-
Sets the color of the area behind any
selected text.
- -selectborderwidth => amount
-
Sets the width of the border of the
selected area.
- -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.
 |  |  |
| 9.4. Using bind with a Canvas |  | 9.6. Creating Items in a Canvas |
Copyright © 2002 O'Reilly & Associates. All rights reserved.