tk4.2 C API - GetClrmap
NAME
Tk_GetColormap, Tk_FreeColormap - allocate and free color-
maps
SYNOPSIS
#include <tk.h>
Colormap
Tk_GetColormap(interp, tkwin, string)
Tk_FreeColormap(display, colormap)
ARGUMENTS
Tcl_Interp *interp (in) Interpreter to use for error
reporting.
Tk_Window tkwin (in) Token for window in which
colormap will be used.
char *string (in) Selects a colormap: either
new or the name of a window
with the same screen and
visual as tkwin.
Display *display (in) Display for which colormap
was allocated.
Colormap colormap (in) Colormap to free; must have
been returned by a previous
call to Tk_GetColormap or
Tk_GetVisual.
DESCRIPTION
These procedures are used to manage colormaps.
Tk_GetColormap returns a colormap suitable for use in tkwin.
If its string argument is new then a new colormap is
created; otherwise string must be the name of another win-
dow with the same screen and visual as tkwin, and the color-
map from that window is returned. If string doesn't make
sense, or if it refers to a window on a different screen
from tkwin or with a different visual than tkwin, then
Tk_GetColormap returns None and leaves an error message in
interp->result.
Tk_FreeColormap should be called when a colormap returned by
Tk_GetColormap is no longer needed. Tk maintains a refer-
ence count for each colormap returned by Tk_GetColormap, so
there should eventually be one call to Tk_FreeColormap for
each call to Tk_GetColormap. When a colormap's reference
count becomes zero, Tk releases the X colormap.
Tk_GetVisual and Tk_GetColormap work together, in that a new
colormap created by Tk_GetVisual may later be returned by
Tk_GetColormap. The reference counting mechanism for color-
maps includes both procedures, so callers of Tk_GetVisual
must also call Tk_FreeColormap to release the colormap. If
Tk_GetColormap is called with a string value of new then the
resulting colormap will never be returned by Tk_GetVisual;
however, it can be used in other windows by calling
Tk_GetColormap with the original window's name as string.
KEYWORDS
colormap