Book HomeMastering Perl/TkSearch this book

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.



Library Navigation Links

Copyright © 2002 O'Reilly & Associates. All rights reserved.