www.gibmonks.com

  Previous section   Next section

Practical Programming in Tcl & Tk, Third Edition
By Brent B. Welch

Table of Contents
Chapter 38.  Color, Images, and Cursors


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 38-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 {}

The image Command

Table 38-5 summarizes the image command.

Table 38-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 nameDeletes the named image.
image height nameReturns the height of the image, in pixels.
image namesReturns the list of defined images.
image type nameReturns the type of the named image.
image typesReturns the list of possible image types.
image width nameReturns 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 47 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 38-6 lists the options supported by the bitmap image type:

Table 38-6. Bitmap image options.
-background colorThe background color (no -bg equivalent).
-data stringThe contents of the bitmap as a string.
-file nameThe name of the file containing a bitmap definition.
-foreground colorThe foreground color (no -fg equivalent).
-maskdata stringThe contents of the mask as a string.
-maskfile nameThe 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 38-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 47 describes the C interface for defining built in bitmaps.

Example 38-5 The built-in bitmaps.

graphics/38fig01.gif


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 38-7 lists the attributes for photo images. These are specified in the image create photo command.

Table 38-7. Photo image attributes.
-format formatSpecifies the data format for the file or data string.
-data stringThe contents of the photo as a base64 coded string.
-file nameThe name of the file containing a photo definition.
-gamma valueA gamma correction factor, which must be greater than zero. A value greater than one brightens an image.
-height valueThe height, in screen units.
-width valueThe width of the image, in screen units.
-palette specThe number of shades of gray or color for the image.

The format indicates what format the data are in. The photo image supports different image formats. Tk 4.0 supports 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 38-8 lists the image instance operations. In the table, $p is a photo image handle returned by the image create photo command.

Table 38-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 38-8. Photo image operations.
$p blankClears the image. It becomes transparent.
$p cget optionReturns the configuration attribute option.
$p configure ...Reconfigures the photo image attributes.
$p copy source optionsCopies another image. Table 38-9 lists the copy options.
$p get x yReturns 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.
$p read file optionsLoads an image from a file. Table 38-10 lists the read options.
$p reditherReapplies the dithering algorithm to the image.
$p write file optionsSaves the image to file according to options. Table 38-11 lists the write options.

Table 38-9. Copy options for photo images.
-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.
-shrinkShrinks 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 38-10 lists the read options, and Table 38-11 lists the write options. The -format option is more important for writing, because the first format found is used. With reading, the format is determined automatically. If there are multiple image types that can read the same data, you may specify a read format.

Table 38-10. Read options for photo images.
-format formatSpecifies 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 y1Specifies the top-left corner of the new data.
-shrinkShrinks 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 38-11. Write options for photo images.
-format formatSpecifies 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.


      Previous section   Next section
    Top