Canvas Options (Mastering Perl/Tk)

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.