Provided by: tk8.4-doc_8.4.19-4_all bug

NAME

       Tk_GetColormap, Tk_FreeColormap - allocate and free colormaps

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.

       CONST 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 window with the same screen and visual as
       tkwin, and the colormap 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 reference 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  colormaps  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