Author:         Scott Pitcher <scottypitcher@gmail.com>
State:          Final
Type:           Project
Vote:           Done
Created:        02-Dec-2017
Post-History:
Keywords:       canvas, image
Tcl-Version:    8.7

Abstract

This TIP adds an image widget command to the Tk canvas. This new command provides a mechanism for the contents of the canvas to be drawn onto a Tk photo image.

Rationale

The canvas is an amazing tool or drawing and managing graphical objects. However, one thing it lacks is a method for creating an image of the canvas contents. There are various alternate methods which generally involve some form of screen capture (see this and this), but nothing that can capture a simple image.

The original application for canvas image was to render a printer page at 300dpi, which involves a canvas perhaps approximately 3300px high and as much as approximately 2400px wide. For this reason the extension was given the ability to draw even when the canvas is unmapped, providing one of the ancestors is mapped.

Optional subsample and zoom parameters can be specified, and the Tk_PhotoPutZoomedBlock() will be used to draw into the Tk image instead of the Tk_PhotoPutBlock(). The boundaries of the region drawn are set by the canvas -scrollregion boundaries, and if one hasn't been defined then the canvas's width and height with an origin of 0,0 are used.

Documentation

The following is an extract from the manual page for the image widget command:

pathName image imagename ?subsample? ?zoom?

Draw the canvas into the Tk photo image named imagename. If a -scrollregion has been set then this will define the boundaries of the canvas region drawn and the final size of the photo image. Otherwise the widget width and height with an origin of 0,0 will define the size of the canvas region drawn and the final size of the photo image. Optionally an integer subsample factor may be given and the photo image will be reduced in size. In addition to the subsample an integer zoom factor can also be given and the photo image will be enlarged. The image background will be filled with the canvas background colour. The canvas widget does not need to be mapped for this widget command to work, but at least one of it's ancestors must be mapped. This command returns an empty string.

Examples

First example of the canvas image command follows. Here a Tk photo image named "testimage" is drawn on by canvas .c, with no subsample or zoom. After the image is drawn the size of the Tk photo image size will be 100px x 100px, the same as the canvas's -scrollregion.

.c configure -scrollregion {0 0 99 99}
.c image testimage

This example shows the subsample option being used. After the canvas is drawn onto the Tk photo image, the image size will be 1/4 that of the canvas source drawn.

.c image testimage 4

And this time with subsample of 1 and zoom of 2, resulting in an image twice as large as the canvas source region.

.c image testimage 1 2

Implementation

An implementation of this TIP can be found in the Tk canvas_image branch.

Copyright