21.12. The Canvas Widget
Create a canvas for drawing with the
Canvas method. The Canvas widget uses a coordinate
system with the x coordinate increasing as you move right, and the y
coordinate increasing as you move down (i.e., the y coordinate is
mathematically upside-down). The x and y coordinates are specified in
pixels by default.
$parentwidget->Canvas (options)
The standard configuration options that apply to
Canvas are: -background,
-bor-derwidth,
-cursor, -height,
-highlightbackground,
-highlightcolor,
-highlight-thickness,
-insertbackground,
-insertborderwidth,
-insertofftime,
-inserton-time,
-insertwidth, -relief,
-selectbackground,
-selectborderwidth,
-selectfore-ground,
-state, -takefocus,
-width, -xscrollcommand, and
-yscrollcommand.
Other options are:
- -closeenough => amount
-
The distance considered
"close enough" to an item to be
judged to be within it. Default is 1 pixel.
- -confine => boolean
-
Whether to limit the canvas to the
scroll region. Default is 1.
- -scrollregion => [ x, y, w, h ]
-
Sets the region that the user is
allowed to scroll. The option is a list reference that conveniently
corresponds to the return value of the bbox
method.
- -xscrollincrement => amount
-
The
distance to use for scrolling in the x direction.
- -yscrollincrement => amount
-
The
distance to use for scrolling in the y direction.
21.12.1. Canvas Creation Methods
To place graphic elements in a canvas, there are several item
creation methods:
- createArc
-
Creates an arc contained within the
given bounding box. For example, to create an oval bounded by the box
from (0,0) to (40,100):
$canvas->createArc(0,0,40,100, -extent => 360);
The -extent option gives a number between 0 and
360 defining the length of the arc. The default
-extent is 90, or 1/4 of an
oval; an extent of 360 gives you a full oval. The
complete list of options to createArc is:
- -extent => degrees
-
Creates an arc of the specified extent.
degrees can be any number between 0 and
360, as described above.
- -fill => color
-
Fills the arc with the specified color.
- -outline => color
-
Draws the arc with the specified color (default is
black).
- -outlinestipple => bitmap
-
Draws the outline with the specified bitmap pattern.
- -start => degrees
-
Starts drawing the arc from the specified position, which is
represented by a number from 0 to 360. The default is
0, which means to start drawing at the 3
o'clock position.
- -stipple => bitmap
-
Uses the specified bitmap to fill the arc (if
-fill is also specified).
- -style => type
-
Draws the arc as specified. Values are:
- pieslice
-
Draws lines from the center to the ends of the arc (the default)
- chord
-
Draws a line connecting the two ends of the arc
- arc
-
Draws the arc with no other lines
- -tags => tagnames
-
Associates the arc with the specified tag(s). Multiple tag names can
be supplied as an anonymous list.
- -width => amount
-
The width of the outline. Default is 1.
- createBitmap
-
Inserts a bitmap. For example, to place
the calculator bitmap at the (0,0) coordinates:
$canvas -> createBitmap(0, 0, -bitmap => 'calculator');
Options are:
- -anchor => position
-
Anchors the bitmap at the specified position. Values are
center (default), n,
e, s, w,
ne, nw, se,
and sw.
- -background => color
-
Specifies the color to use for the 0 pixels in the bitmap (default is
to be transparent).
- -bitmap => bitmap
-
Specifies the bitmap name. For a built-in bitmap, just specify the
name; for a local bitmap file, specify the name with an
@ preceding it.
- -foreground => color
-
Specifies the color to use for the 1 pixel in the bitmap (default is
black).
- -tags => tagnames
-
Associates the bitmap with the specified tag(s). Multiple tag names
can be supplied as an anonymous list.
- createImage
-
Creates an image. For example, to place
an image at (0,0):
$canvas->createImage(0,0, -image => $imgptr);
Options are:
- -anchor => position
-
Anchors the image at the specified position. Values are
center (default), n,
e, s, w,
ne, nw, se,
and sw.
- -image => $imgptr
-
$imgptr is a pointer to a Photo or Image
object made using a GIF or PPM file. For example:
$imgptr = $mainwindow->Photo(-file => "doggie.gif");
- -tags => tagnames
-
Associate the image with the specified tag(s). Multiple tag names can
be supplied as an anonymous list.
- createLine
-
Creates a line or several adjoining
lines. For example, to create a line from (0,0) to (100,100) and then
back to (100,0):
$canvas->createLine (0,0,100,100,100,0);
The first four coordinates are required. Any additional coordinates
are taken to represent a continuation of that line. Options are:
- -arrow => position
-
Specifies where to place arrowheads. Values are
none (default), first,
last, and both.
- -arrowshape => [ head, length, flare ]
-
Specifies the dimensions of the arrow as a three-element anonymous
list, describing (in order) the distance from the base to the head of
the arrow, the distance from the rear point(s) to the head of the
arrow, and the distance from the rear point(s) to the line.
- -capstyle => type
-
Defines the type of arrowhead. Values are butt
(the default), projecting, and
round.
- -fill => color
-
The color to use to draw the line.
- -joinstyle => type
-
Defines how multiple lines are joined. Values are
miter (default), bevel, and
round.
- -smooth => boolean
-
Determines whether the lines are drawn with a Bezier spine. Default
is 0.
- -splinesteps => n
-
Determines how smooth the Bezier curve is.
- -stipple => bitmap
-
Draws the line with the specified bitmap pattern.
- -tags => tagnames
-
Associates the line with the specified tag(s). Multiple tag names can
be supplied as an anonymous list.
- -width => amount
-
The width of the line (default is 1 pixel).
- createOval
-
Creates an oval. For example, to create
a circle bounded by the box from (50,50) to (150,150):
$canvas->createOval(50,50,150,150);
Options are:
- -fill => color
-
Fills the arc with the specified color.
- -outline => color
-
Specifies the color for the outline (default is
black).
- -stipple => bitmap
-
Specifies a bitmap to fill the oval with.
- -tags => tagnames
-
Associates the oval with the specified tag(s). Multiple tag names can
be supplied as an anonymous list.
- -width => amount
-
The width of the outline (default is 1 pixel).
- createPolygon
-
Creates a polygon. At least three sets
of coordinates are required; the first point is automatically
connected to the last point to complete the polygon.
$canvas -> createPolygon(0,0,130, 20, 90, -35);
Options are:
- -fill => color
-
The color to use to fill the polygon.
- -outline => color
-
Specifies the color of the outline (default is
black).
- -smooth => boolean
-
Determines whether the outline is drawn with a Bezier spine. Default
is 0.
- -splinesteps => n
-
Determines how smooth the Bezier curve is.
- -stipple => bitmap
-
Fills the polygon with the specified bitmap pattern.
- -tags => tagnames
-
Associates the polygon with the specified tag(s). Multiple tag names
can be supplied as an anonymous list.
- -width => amount
-
The width of the outline (default is 1 pixel).
- createRectangle
-
Creates a rectangle. For example, to
create a square with one corner at (0,0) and another at (100,100):
$canvas->createRectangle(0,0,100,100);
Options are:
- -fill => color
-
The color to use to fill the rectangle.
- -outline => color
-
Specifies the color of the outline (default is
black).
- -stipple => bitmap
-
Fills the rectangle with the specified bitmap pattern.
- -tags => tagnames
-
Associates the rectangle with the specified tag(s). Multiple tag
names can be supplied as an anonymous list.
- -width => amount
-
The width of the outline (default is 1 pixel).
- createText
-
Places text in a canvas widget. For
example, to write "Broadway"
centered at the position (130,-40):
$canvas->createText(130,-40, -text => "Broadway");
Options are:
- -anchor => position
-
Anchors the text at the specified position. Values are
center (default), n,
e, s, w,
ne, nw, se,
and sw.
- -fill => color
-
The color to use for the text.
- -font => fontname
-
The font for the text.
- -justify => position
-
The justification of the text (either left,
right, or center). The default
is left.
- -stipple => bitmap
-
Fills the text with the specified bitmap pattern.
- -tags => tagnames
-
Associates the text with the specified tag(s). Multiple tag names can
be supplied as an anonymous list.
- -text => string
-
Specifies the text to display.
- -width => amount
-
The maximum length of each line of text. Default is
0, which means that lines are broken only at
explicit newline characters.
There is a set of methods for manipulating text items within a Canvas
widget. For each of these methods, the first argument is the tag name
or tag ID, and subsequent arguments use text indexes as described for
the Text widget.
- dchars
-
Deletes characters from a text item, given the tag name or ID, and
indexes of the first and last characters to delete
- icursor
-
Places the insert cursor at the specified index
- index
-
Gets a numerical index from a named one
- insert
-
Adds a string to the text item
- createWindow
-
Embeds another widget inside of a
canvas. The widget must have been already created as a child of the
canvas or of the canvas's parent. Options are:
- -anchor => position
-
Anchors the widget at the specified position. Values are
center (default), n,
e, s, w,
ne, nw, se,
and sw.
- -height => amount
-
Specifies the height of the widget.
- -tags => tagnames
-
Associates the widget with the specified tag(s). Multiple tag names
can be supplied as an anonymous list.
- -width => amount
-
The width of the widget.
- -window => $widget
-
Specifies the widget to embed.
21.12.2. Item Tags and IDs
Each item in a Canvas widget is given a
unique ID when it is created. This ID is returned from the canvas
creation command. In addition, each item can have a tag associated
with it, either when created or with the addtag
method. You can use either the ID or the tag to refer to an item in
the canvas. Unlike IDs, tags do not have to be unique, which makes it
possible to configure several items as a group.
Two special tags are created automatically. The
"all" tag refers to all items in the canvas. The
"current" tag refers to the item that the cursor
is currently over, if any.
21.12.3. Canvas Methods
In addition to configure and
cget, the following methods are supported by the
Canvas widget:
- addtag
-
Defines a tag for an already created
canvas item. For example, to assign a tag called
"everything" to all items in a canvas:
$canvas->addtag("everything", "all");
To assign the tag origin to the item closest to
the coordinates (0,0):
$canvas->addtag("origin", "closest", 0, 0);
The full list of identifiers is:
- above
-
Assigns the tag to the item above the specified item in the display
list
- all
-
Assigns the tag to all items in the canvas
- below
-
Assigns the tag to the item below the specified item in the display
list
- closest
-
Assigns the tag to the item closest to the specified x,y coordinate
- enclosed
-
Assigns the tag to all items that are completely enclosed within the
specified bounding box
- overlapping
-
Assigns the tag to all items that are even partially inside the
specified bounding box
- withtag
-
Assigns the tag to all items with the specified tag
- bind
-
Binds a callback to an item. (To bind a
callback to the Canvas widget itself, you must specify Tk::bind.)
- bbox
-
Returns the bounding box of an item.
For example, to get the bounding box for all items in the canvas:
$canvas->bbox("all");
- itemconfigure
-
Configures one of the items within the
canvas. Works just like the configure method for
widgets, but the first argument is the tag name or ID for the canvas
item.
- itemcget
-
Gets configuration information for one
of the items within the canvas. Works just like the
cget method for widgets, but the first argument is
the tag name or ID for the canvas item.
- move
-
Moves an item on the canvas by adding
the specified x and y distances to it:
$canvas->move("circle1", 100, 100);
- coords
-
Gets the current x,y coordinates for an
item, or moves an item to an explicit x,y coordinate.
- lower
-
Sets the priority for the item in the
display list to be lower than the item identified by the specified
tag or ID.
- raise
-
Sets the priority for the item in the
display list to be higher than the item identified by the specified
tag or ID.
- delete
-
Removes an item from the canvas. You
can specify as many tags or IDs in the argument list as you want.
- find
-
Finds the specified items. The first
argument can be any of:
- above
-
Finds the item above the specified item in the display list
- all
-
Finds all items in the canvas
- below
-
Finds the item below the specified item in the display list
- closest
-
Finds the item closest to the specified x,y coordinate
- enclosed
-
Finds all items that are completely enclosed within the specified
bounding box
- overlapping
-
Finds all items that are even partially inside the specified bounding
box
- withtag
-
Finds all items with the specified tag
- gettags
-
Retrieves a list of all tags associated
with an item.
- type
-
Determines the type of the specified
item.
- focus
-
Assigns the keyboard focus to the
specified item.
- postscript
-
Renders the canvas as PostScript.
Options are:
- -colormap => \@colorcommand
-
Specifies a PostScript command for setting color values.
- -colormode => mode
-
Sets the mode to color (full color),
gray (grayscale), or mono
(black and white).
- -file => filename
-
The name of the file to store the PostScript output.
- -fontmap => \@fontspec
-
Specifies a font name and point size.
- -height => size
-
The height of the area to print.
- -pageanchor => position
-
The anchor position of the page. Values are center
(default), n, e,
s, and w.
- -pageheight => height
-
The height of the printed page.
- -pagewidth => width
-
The width of the printed page.
- -pagex => x
-
The x positioning point.
- -pagey => y
-
The y positioning point.
- -rotate => boolean
-
Whether to rotate to landscape orientation. Default is
0.
- -width => size
-
The width of the area to print.
- -x => x
-
The left edge of the canvas.
- -y => y
-
The top edge of the canvas.
- scale
-
Changes the scaling of the canvas or
any individual items. For example, to scale the entire canvas to half
its dimensions:
$canvas->scale("all", 0, 0, .5, .5);
- xview
-
Manipulates the canvas area in view.
With no arguments, returns a list of two numbers between 0 and 1,
defining the portion of the canvas that is currently hidden on the
left and right sides, respectively. With arguments, the function of
xview changes:
- moveto
-
Moves the specified fraction of the text to the left of the visible
portion.
- scroll
-
Scrolls the canvas left or right by the specified number of units or
pages. Used primarily as a callback to a scrollbar; pressing on an
arrow would move by units (characters), and pressing on the trough
would move by pages. The number is either 1 or
-1, to move forwards or backwards, respectively.
- yview
-
Manipulates the canvas in view. With no
arguments, returns a list of two numbers between 0 and 1, defining
that portion of the canvas that is currently hidden on the top and
bottom, respectively. With arguments, its function changes:
- moveto
-
Moves the specified fraction of the canvas area to the top of the
visible portion.
- scroll
-
Scrolls the canvas up or down by the specified number of units or
pages. Used primarily as a callback to a scrollbar; pressing on an
arrow would move by units (lines), and pressing on the trough would
move by pages. The number is either 1 or
-1, to move forwards or backwards,
respectively.
 |  |  |
| 21.11. The Text Widget |  | 21.13. The Scale Widget |
Copyright © 2002 O'Reilly & Associates. All rights reserved.