Bitmaps and Images

The label and all the button widgets have an image attribute that specifies a graphic image to display. Using an image takes two steps. In the first step the image is created via the image create command. This command returns an identifier for the image, and it is this identifier that is passed to widgets as the value of their image attribute.

Example 41-3 Specifying an image for a widget

set im [image create bitmap \
   -file glyph.bitmap -maskfile glyph.mask \
   -background white -foreground blue]
button .foo -image $im

There are three things that can be displayed by labels and all the buttons: text, bitmaps, and images. If more than one of these attributes are specified, then the image has priority over the bitmap, and the bitmap has priority over the text. You can remove the image or bitmap attribute by specifying a null string for its value:

.foo config -image {}

Tk 8.4 introduced the compound attribute for labels, menu entries, and the various button widgets, which specifies whether the widgets should display both an image (or bitmap) and text, and if so, where the image should be placed relative to the text. For example, the following command would cause a label to display a bitmap on the left, and text to the right:

label .warn -text Warning -bitmap warning -compound left

The image Command

Table 41-5 summarizes the image command.

Table 41-5. Summary of the image command

image create type ?name? ?options?	Creates an image of the specified type. If name is not specified, one is made up. The remaining arguments depend on the type of image being created.
image delete name	Deletes the named image.
image height name	Returns the height of the image, in pixels.
image inuse name	Returns a boolean value indicating whether or not the image given by name is in use by any widgets.
image names	Returns the list of defined images.
image type name	Returns the type of the named image.
image types	Returns the list of possible image types.
image width name	Returns the width of the image, in pixels.

The exact set of options for image create depend on the image type. There are two built-in image types: bitmap and photo. Chapter 48 describes the C interface for defining new image types.

Bitmap Images

A bitmap image has a main image and an optional mask image. The main image is drawn in the foreground color. The mask image is drawn in the background color, unless the corresponding bit is set in the main image. The remaining bits are "clear" and the widget's normal background color shows through. Table 41-6 lists the options supported by the bitmap image type:

Table 41-6. Bitmap image options

-background color	The background color (no -bg equivalent).
-data string	The contents of the bitmap as a string.
-file name	The name of the file containing a bitmap definition.
-foreground color	The foreground color (no -fg equivalent).
-maskdata string	The contents of the mask as a string.
-maskfile name	The name of the file containing the mask data.

The bitmap definition files are stylized C structure definitions that the Tk library parses. The files usually have a .xbm file name extension. These are generated by bitmap editors such as bitmap program, which comes with the standard X distribution. The -file and -maskfile options name a file that contains such a definition. The -data and -maskdata options specify a string in the same format as the contents of one of those files.

The bitmap Attribute

The label and all the button widgets also support a bitmap attribute, which is a special case of an image. This attribute is a little more convenient than the image attribute because the extra step of creating an image is not required. However, there are some power and flexibility with the image command, such as the ability to reconfigure a named image (e.g., for animation) that is not possible with a bitmap.

Example 41-4 Specifying a bitmap for a widget

button .foo -bitmap @glyph.xbm -fg blue

The @ syntax for the bitmap attribute signals that a file containing the bitmap is being specified. It is also possible to name built-in bitmaps. The predefined bitmaps are shown in the next figure along with their symbolic name. Chapter 48 describes the C interface for defining built in bitmaps.

Example 41-5 The built-in bitmaps

frame .f -bd 4; frame .g -bd 4 ; pack .f .g -side left
set parent .f ; set next .g
foreach name {error gray12 gray50 hourglass \
             info questhead question warning} {
   frame $parent.$name
   label $parent.$name.l -text $name -width 9 -anchor w
   label $parent.$name.b -bitmap $name
   pack $parent.$name.l -side right
   pack $parent.$name.b -side top
   pack $parent.$name -side top -expand true -fill x
   set tmp $parent ; set parent $next ; set next $tmp
}

Photo Images

The photo image type was contributed to Tk by Paul Mackerras. It displays full color images and can do dithering and gamma correction. Table 41-7 lists the attributes for photo images. These are specified in the image create photo command.

Table 41-7. Photo image attributes

-data string	The contents of the photo as a base64 encoded or binary string.
-file name	The name of the file containing a photo definition.
-format format	Specifies the data format for the file or data string.
-gamma value	A gamma correction factor, which must be greater than zero. A value greater than one brightens an image.
-height value	The height, in screen units.
-palette spec	The number of shades of gray or color for the image.
-width value	The width of the image, in screen units.

The format indicates what format the data are in. The photo image supports different image formats. Tk has built-in support for the PPM, PGM, and GIF formats. There is a C interface to define new photo formats. The CD-ROM has a "plus-patch" version of Tk that supports pixmaps and JPEG files. Normally you do not need to specify the format because the photo implementation will try all format handlers until it find one that accepts the data. An explicit format limits what handlers are tried. The format name is treated as a prefix that is compared against the names of handlers. Case is not significant in the format name.

The palette setting determines how many colors or graylevels are used when rendering an image. If a single number is specified, the image is rendered in greyscale with that many shades of gray. For full color, three numbers separated by slashes specify the number of shades of red, green, and blue, respectively. The more shades you specify the more room you take up in your colormap. The photo widget will switch to a private colormap if necessary. Multiply the number of red, green, and blue shades to determine how many different colors you use. If you have an 8-bit display, there are only 256 colors available. Reasonable palette settings that do not hog the colormap include 5/5/4 and 6/6/5. You can use fewer shades of blue because the human eye is less sensitive to blue.

After you create an image you can operate on it. Table 41-8 lists the image instance operations. In the table, $p is a photo image handle returned by the image create photo command.

Table 41-8. Photo image operations

$p blank	Clears the image. It becomes transparent.
$p cget option	Returns the configuration attribute option.
$p configure ...	Reconfigures the photo image attributes.
$p copy source ?options?	Copies another image. Table 41-9 lists the copy options.
$p data ?options?	Returns image data in the form of a list of rows, where each row is a list of colors in #rrggbb format. Table 41-11 lists the data options.
$p get x y	Returns the pixel value at position x y.
$p put data ?-to x1 y1 x2 y2?	Inserts data into the image. data is a list of rows, where each row is a list of colors in #rrggbb format.
$p read file options	Loads an image from a file. Table 41-10 lists the read options.
$p redither	Reapplies the dithering algorithm to the image.
$p tranparency get x y	Returns a boolean indicating if the specified pixel is transparent
$p tranparency set x y boolean	Makes the specified pixel transparent if boolean is true, or opaque otherwise.
$p write file ?options?	Saves the image to file according to options. Table 41-11 lists the write options.

Table 41-9 lists the options available when you copy data from one image to another. The regions involved in the copy are specified by the upper-left and lower-right corners. If the lower-right corner of the source is not specified, then it defaults to the lower-right corner of the image. If the lower-right corner of the destination is not specified, then the size is determined by the area of the source. Otherwise, the source image may be cropped or replicated to fill the destination.

Table 41-9. Copy options for photo images

-compositingrule rule	Specifies how transparent pixels in the source image are combined with the destination image. When rule is overlay (default), the old contents of the destination image remain visible. When rule is set, the old contents of the destination image are discarded and the source image is used as-is.
-from x1 y1 ?x2 y2?	Specifies the location and area in the source image. If x2 and y2 are not given, they are set to the bottom-right corner.
-to x1 y1 ?x2 y2?	Specifies the location and area in the destination. If x2 and y2 are not given, the size is determined by the source. The source may be cropped or tiled to fill the destination.
-shrink	Shrinks the destination so that its bottom right corner matches the bottom right corner of the data copied in. This has no effect if the width and height have been set for the image.
-zoom x ?y?	Magnifies the source so each source pixel becomes a block of x by y pixels. y defaults to x if it is not specified.
-subsample x ?y?	Reduces the source by taking every xth pixel in the X direction and every yth pixel in the Y direction. y defaults to x.

Table 41-10 lists the read options. If not specified, the format is determined automatically. If there are multiple image types that can read the same data, you may specify a read format

Table 41-10. Read options for photo images

-format format	Specifies the format of the data. By default, the format is determined automatically.
-from x1 y1 ?x2 y2?	Specifies a subregion of the source data. If x2 and y2 are not given, the size is determined by the data.
-to x1 y1	Specifies the top-left corner of the new data.
-shrink	Shrinks the destination so that its bottom-right corner matches the bottom-right corner of the data read in. This has no effect if the width and height have been set for the image.

Table 41-11 lists the options used for write and data. When writing to files, the -format option is important because if you don't specify it, the first format found is used. On the other hand, you shouldn't use the -format option with data operation, as data returns the image date as a list of rows, where each row is a list of colors in #rrggbb format (suitable as input to the put command).

Table 41-11. Write options for photo images

-background color	If specified, all transparent pixels are replaced by the specified color.
-format format	Specifies the format of the data.
-from x1 y1 ?x2 y2?	Specifies a subregion of the data to save. If x2 and y2 are not given, they are set to the lower-right corner.
-grayscale	If specified, the data is transformed into grayscale.