9.6.1. The Arc Item

When you create an arc, you specify a bounding rectangle with two sets of x and y coordinates. The arc is drawn within the confines of the bounding box. The basic createArc statement is as follows:

$id = $canvas->createArc(x1, y1, x2, y2);

Any additional options used with createArc are specified after the coordinates:

$id = $canvas->createArc(x1, y1, x2, y2, option => value);

9.6.2. The Bitmap Item

$id = $canvas->createBitmap(x, y);

$id = $canvas->createBitmap(x, y, -bitmap => bitmap);

9.6.3. The Image Item

If we can create a bitmap on a Canvas, it makes sense that we can create an image as well. We can do so with the createImage method:

$id = $canvas->createImage(x, y, -image => image);

9.6.4. The Line Item

$id = $canvas->createLine(0,0, 400,400);           # creates one line
$id = $canvas->createLine(0,0, 400,400, -50, 240); # creates two lines

After the coordinates, you can specify any options and values you wish to configure the line(s); the options and values are as follows:

Specify the three distances by using an anonymous list such as this:

$canvas->createLine(10, 10, 200, -40, -arrow => "both", 
                    -arrowshape => [ 20, 20, 20]);

Figure 9-4. Definition of arrowhead

9.6.5. The Oval Item

$id = $canvas->createOval(0,0, 50, 50);  # creates a circle
$id = $canvas->createOval(0,0, 50, 100); # creates an oval

9.6.6. The Polygon Item

$id = $canvas->createPolygon(1000,1000, 850,950, 30,40);

Additional (x, y) coordinate pairs can be specified as well; for example:

$id = $canvas->createPolygon(1000,1000, 850,950, 30,40, 500,500);

The options you can specify with createPolygon are the same as those you use with createLine: -fill, -outline, -smooth, -splinesteps, -stipple, -tags, and -width. Just remember that createPolygon connects the first point to the last point to enclose the area.

9.6.7. The Rectangle Item

$id = $canvas->createRectangle(10, 10, 50, 150);

# A blue rectangle with black outline:
$canvas->createRectangle(10,10, 50, 150, -fill => 'blue');
# A blue rectangle with a thicker outline:
$canvas->createRectangle(10,10, 50, 150, -fill => 'blue', -width => 10);

9.6.8. The Text Item

Finally, an item type that doesn't have lines in it! You can use the createText method to add text to a Canvas widget. It requires an (x, y) coordinate pair, which determines where you place the text in the Canvas and the text to be displayed:

$id = $canvas->createText(0,0, -text => "origin");

9.6.9. The Widget Item

$bttn = $canvas->Button(-text => "Button", 
                        -command => sub { print "Button in Canvas\n"; });
$id = $canvas->createWindow(0, 0, -window => $bttn);

There are a few things you should note about this example (which is fairly typical, except the subroutine associated with the Button doesn't do anything useful):

• The Button is a child of the Canvas widget. The Button could be a child of an ancestor of the Canvas (the Button could be a child of the MainWindow if the Canvas is also a child of the MainWindow). However, the Button should not be a child of a different Toplevel widget that has nothing to with the Canvas.

• The createWindow method doesn't actually create the widget; it just puts it in the Canvas. The Button is placed at the specified coordinates inside the Canvas and has not been placed on the screen with pack, grid, or place.

• The widget must be created before you call createWindow.

• You can click the Button and the callback associated with it will be invoked, just as with any other Button.

• When you create the widget, you can use any of that widget's options to configure it. To continue configuring the widget, use the reference to it (e.g., $bttn).

The following options, which you can use when you call createWindow, are more like options you use with pack than widget options:

It makes sense to create the widget inline if you don't need to do anything fancy with it.

9.6.10. The Grid Item

Grid items cover the entire Canvas, but never enclose or overlap any area and are not near any point, so you cannot search for them using the closest, enclosed, or overlapping attributes. In most other regards, they behave like other Canvas item types. Currently, grids, like window items, do not appear in PostScript output.

 $canvas->createGrid(x1, y1, x2, y2, ... );

x1 and y1 specify the origin of the basal grid cell, and x2 and y2 specify its width and height, respectively; the cell is replicated over the entire surface of the Canvas widget. By default, dots are drawn at every grid intersection, unless the -lines option is set true. When drawing lines, dash specifications are honored.

Figure 9-5. A canvas with three grid items

9.6.11. The Group Item

$one = $canvas->createOval(5,  0, 20, 30, -fill => 'blue');
$two = $canvas->createRectangle(0, 20, 50, 75, -fill => 'red');
$group = $canvas->createGroup([0, 0], -members => [$one, $two]);
$mw->update;
$mw->after(1000);
$canvas->move($group, 100, 100);

Figure 9-6. Before move

Figure 9-7. After move

Of course, sometimes you want to get to individual items within the group, perhaps to configure a special attribute. The current idiom is to iterate through the members of the group, like this:

foreach my $member ($canvas->itemcget($group, -members)) {
    print "member=$member\n";
}

This example prints out the item ID for each member of the group, but you can use the item IDs in an itemconfigure call.