Perl in a Nutshell

Perl in a NutshellSearch this book
Previous: 18.11 The Text WidgetChapter 18
Perl/Tk
Next: 18.13 The Scale Widget
 

18.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, -borderwidth, -cursor, -height, -highlightbackground, -highlightcolor, -highlightthickness, -insertbackground, -insertborderwidth, -insertofftime, -insertontime, -insertwidth, -relief, -selectbackground, -selectborderwidth, -selectforeground, -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.

18.12.1 Canvas Creation Methods

To place graphic elements in a canvas, there are several item creation commands:

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 = black).

-outlinestipple => bitmap

Draws the outline with the specified bitmap pattern.

-start => degrees

Starts drawing the arc from the specified position, where the position 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 "@" symbol preceding it.

-foreground => color

Specifies the color to use for the "1" pixels 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 = 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 = 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 = 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 for the outline (default = 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 = 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 for the outline (default = 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 = 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 (any of 'left', 'right', and '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 only broken 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.

18.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.

18.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 change the tag for an item from "tmp" to "circle":
$canvas->addtag("circle", "withtag", "tmp");
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 what portion of the canvas 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 what portion of the canvas 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.


Previous: 18.11 The Text WidgetPerl in a NutshellNext: 18.13 The Scale Widget
18.11 The Text WidgetBook Index18.13 The Scale Widget