Table 41-1 lists the resource names for color attributes. The table indicates what widgets use the different color attributes. Remember to use all lowercase and a leading dash when specifying attributes in a Tcl command.

The foreground color is used to draw an element, while the background color is used for the blank area behind the element. Text, for example, is painted with the foreground color. There are several variations on foreground and background that reflect different states for widgets or items they are displaying.

Each attribute also has a resource class. This is most useful for the variations on foreground and background colors. For example, Tk does not have a reverse video mode. However, with a couple of resource specifications you can convert a monochrome display into reverse video. The definitions are given in Example 41-1. The Foreground and Background resource class names are used, and the various foreground and background colors (e.g., activeBackground) have the correct resource class so these settings work. You have to set these resources before you create any widgets:

proc ReverseVideo {} {
   option add *Foreground white
   option add *Background black
}

tk_setPalette #0088cc

tk_bisque

tk_setPalette activeBackground red activeForeground white

Color Values

Color values are specified in two ways: symbolically (e.g., red), or by hexadecimal numbers (e.g., #ff0000). The leading # distinguishes the hexadecimal representation from the symbolic one. The number is divided into three equal-sized fields that give the red, green, and blue values, respectively. The fields can specify 4, 8, 12, or 16 bits of a color:

#RGB          4 bits per color
#RRGGBB       8 bits per color
#RRRGGGBBB    12 bits per color
#RRRRGGGGBBBB 16 bits per color

If you specify more resolution than is supported by the display, the low-order bits of each field are discarded. The different display types supported by Tk are described in the next section. Each field ranges from 0, which means no color, to a maximum, which is all ones in binary, or all f in hex, that means full color saturation. For example, pure red can be specified four ways:

#f00 #ff0000 #fff000000 #ffff00000000

There is a large collection of symbolic color names like "red," "blue," "green," "thistle," "medium sea green," and "yellow4." These names originate from X and UNIX, and Tk supports these colors on all platforms. As of Tk 8.3.2, these color names are documented in the colors online reference page. Prior to that, you could find the list in the Tk sources in the xlib/xcolor.c file. Or, run the xcolors program that comes with the standard X distribution.

The Windows and Macintosh platforms have a small set of colors that are guaranteed to exist, and Tk defines names for these. The advantage of using these colors is that they are shared by all applications, so the system can manage colors efficiently. Table 41-2 lists the system colors on Windows. Several of these colors map to the same RGB value. Table 41-3 lists the system colors on Macintosh.

Table 41-2. Windows system colors

system3dDarkShadow	Dark part of button 3D-relief.
system3dLight	Light part of button 3D-relief.
systemActiveBorder	Window border when activated.
systemActiveCaption	Caption (i.e., title bar) when activated.
systemAppWorkspace	Background for MDI workspaces.
systemBackground	Widget background.
systemButtonFace	Button background.
systemButtonHighlight	Lightest part of button 3D-relief.
systemButtonShadow	Darkest part of button 3D-relief.
systemButtonText	Button foreground.
systemCaptionText	Caption (i.e., title bar) text.
systemDisabledText	Text when disabled.
systemGrayText	Grey text color.
systemHighlight	Selection background.
systemHighlightText	Selection foreground.
systemInactiveBorder	Window border when not activated.
systemInactiveCaption	Caption background when not activated.
systemInactiveCaptionText	Caption text when not activated.
systemInfoBackground	Help pop-up background.
systemInfoText	Help pop-up text.
systemMenu	Menu background.
systemMenuText	Menu foreground.
systemScrollbar	Scrollbar background.
systemWindow	Text window background.
systemWindowFrame	Text window frame.
systemWindowText	Text window text color.

Table 41-3. Macintosh system colors

systemHighlight	Selection background.
systemHighlightText	Selection foreground.
systemButtonFace	Button background.
systemButtonFrame	Button frame.
systemButtonText	Button foreground.
systemWindowBody	Widget background.
systemMenuActive	Selected menu item background.
systemMenuActiveText	Selected menu item foreground.
systemMenu	Menu background.
systemMenuDisabled	Disabled menu item background.
systemMenuText	Menu foreground.

Note

Getting RGB values.

The winfo rgb command maps from a color name (or value) to three numbers that are its red, green, and blue values. You can use this to compute variations on a color. The ColorDarken procedure shown below uses the winfo rgb command to get the red, green, and blue components of the input color. It reduces these amounts by 5 percent, and reconstructs the color specification using the format command.

Example 41-2. Computing a darker color

proc ColorDarken { win color } {
   set rgb [winfo rgb $win $color]
   return [format "#%03x%03x%03x" 
      [expr round([lindex $rgb 0] * 0.95)] 
      [expr round([lindex $rgb 1] * 0.95)] 
      [expr round([lindex $rgb 2] * 0.95)]]
}

Computer screens can display only a fixed number of different colors at one time. The best monitors can display 24 million colors, but it is common to find 256 color displays. Really old VGA displays only display 16 colors. If you run several applications at once, it is possible that more colors are requested than can be displayed. The Windows and Macintosh platforms manage this scenario automatically. X provides lower-level facilities that Tk uses on UNIX to do the management. So, for the most part you don't have to worry. However, if you need more control, especially under X, then you need to understand colormaps and the different visual types.

Each pixel on the screen is represented by one or more bits of memory. There are a number of ways to map from a value stored at a pixel to the color that appears on the screen at that pixel. The mapping is a function of the number of bits at each pixel, which is called the depth of the display, and the style of interpretation, or visual class. The six visual classes defined by X are listed in the following table. Some of the visuals use a colormap that maps from the value stored at a pixel to a value used by the hardware to generate a color. A colormap enables a compact encoding for a much richer color. For example, a 256-entry colormap can be indexed with 8 bits, but it may contain 24 bits of color information. The UNIX xdpyinfo program reports the different visual classes supported by your display. Table 41-4 lists the visual classes:

The frame and toplevel widgets support a colormap and visual attribute. You can query these attributes on all platforms. On Windows and Macintosh there is only one visual type at a time, and users may be able to change it for their whole system. On UNIX, the X server typically supports more than one visual class on the same display, and you can create frames and toplevels that use a particular visual class. The value of the visual attribute has two parts, a visual type and the desired depth of the display. The following example requests a greyscale visual with a depth of 4 bits per pixel:

toplevel .grey -visual "greyscale 4"

You can start wish with a -visual command line argument:

wish -visual "truecolor 24"

A visual is associated with a colormap. Windows and Macintosh have a single colormap that is shared by all applications. UNIX allows for private colormaps, which can be useful if you absolutely must have lots of colors. However, the drawback of a private colormap is that the display flashes as the mouse enters windows with their own colormap. This is because the monitor hardware really only has one colormap, so the X server must swap colormaps. Macintosh and Windows manage their colormap more gracefully, although if you use too many colors some flashing can occur. Tk can simulate private colormaps on Windows, but it is probably better to let the system manage the colormap. Tk on the Macintosh always uses a 24-bit truecolor visual, which is basically unlimited colors, and lets the operating system dither colors if necessary.

By default a widget inherits the colormap and visual from its parent widget. The value of the colormap attribute can be the keyword new, in which case the frame or toplevel gets a new private colormap, or it can be the name of another widget, in which case the frame or toplevel shares the colormap of that widget. When sharing colormaps, the other widget must be on the same screen and using the same visual class.

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.

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

The text, entry, and canvas widgets have a second cursor to mark the text insertion point. The text insert cursor is described by a set of attributes. These attributes can make the insert cursor vary from a thin vertical line to a large rectangle with its own relief. Table 41-12 lists these attributes. The default insert cursor is a two-pixel-wide vertical line. You may not like the look of a wide insert cursor. The cursor is centered between two characters, so a wide one does not look the same as the block cursors found in many terminal emulators. Instead of occupying the space of a single character, it partially overlaps the two characters on either side:

On Unix systems, a foreground and background color for the cursor can be specified. Here are some example cursor specifications:

$w config -cursor watch             ;# stop-watch cursor
$w config -cursor {gumby blue}      ;# blue gumby
$w config -cursor {X_cursor red white}  ;# red X on white 

The other form for the cursor attribute specifies a file that contains the definition of the cursor bitmap. If two file names are specified, then the second specifies the cursor mask that determines what bits of the background get covered up. Bitmap editing programs like idraw and iconedit can be used to generate these files. Here are some example cursor specification using files. You need to specify a foreground color, and if you specify a mask file, then you also need to specify a background color:

$w config -cursor "@timer.xbm black"
$w config -cursor "@timer.xbm timer.mask black red"

The cursors shown in Example 41-6 are available on all platforms. However, on Windows and Macintosh some of the cursors are mapped to native cursors and appear differently. On Windows the following cursors are mapped to native cursors: arrow, ibeam, icon, crosshair, fleur, sb_v_double_arrow, sb_h_double_arrow, center_ptr, watch, and xterm. These additional cursors are defined on Windows: starting, size, size_ne_sw, size_ns, size_nw_se, size_we, uparrow, and wait. On Windows, use the no cursor to eliminate the cursor. On Macintosh, the following cursors are mapped to native cursors: ibeam, xterm, cross, crosshair, plus, watch, arrow. These additional cursors are defined on Macintosh: text and cross-hair.

As of Tk 8.3, when running on Windows you can also use Windows system cursors by specifying the name of the appropriate .ani or .cur file. For example:

$w config -cursor @C:/WINNT/Cursors/globe.ani

Figure 41-6. The Tk cursors