<HTML><HEAD><TITLE>Tk Library Procedures - Tk_GetColormap manual page</TITLE></HEAD><BODY> <H3><A NAME="M2">NAME</A></H3> Tk_GetColormap, Tk_FreeColormap - allocate and free colormaps <H3><A NAME="M3">SYNOPSIS</A></H3> <B>#include <tk.h></B><BR> Colormap<BR> <B>Tk_GetColormap(</B><I>interp, tkwin, string</I><B>)</B><BR> <B>Tk_FreeColormap(</B><I>display, colormap</I><B>)</B><BR> <H3><A NAME="M4">ARGUMENTS</A></H3> <DL> <P><DT><A HREF="../TclLib/Interp.htm">Tcl_Interp</A> <B>*interp</B> (in)<DD> Interpreter to use for error reporting. <P><DT>Tk_Window <B>tkwin</B> (in)<DD> Token for window in which colormap will be used. <P><DT>char <B>*string</B> (in)<DD> Selects a colormap: either <B>new</B> or the name of a window with the same screen and visual as <I>tkwin</I>. <P><DT>Display <B>*display</B> (in)<DD> Display for which <I>colormap</I> was allocated. <P><DT>Colormap <B>colormap</B> (in)<DD> Colormap to free; must have been returned by a previous call to <B>Tk_GetColormap</B> or <B><A HREF="../TkLib/GetVisual.htm">Tk_GetVisual</A></B>. <P></DL> <H3><A NAME="M5">DESCRIPTION</A></H3> These procedures are used to manage colormaps. <B>Tk_GetColormap</B> returns a colormap suitable for use in <I>tkwin</I>. If its <I>string</I> argument is <B>new</B> then a new colormap is created; otherwise <I>string</I> must be the name of another window with the same screen and visual as <I>tkwin</I>, and the colormap from that window is returned. If <I>string</I> doesn't make sense, or if it refers to a window on a different screen from <I>tkwin</I> or with a different visual than <I>tkwin</I>, then <B>Tk_GetColormap</B> returns <B>None</B> and leaves an error message in <I>interp->result</I>. <P> <B>Tk_FreeColormap</B> should be called when a colormap returned by <B>Tk_GetColormap</B> is no longer needed. Tk maintains a reference count for each colormap returned by <B>Tk_GetColormap</B>, so there should eventually be one call to <B>Tk_FreeColormap</B> for each call to <B>Tk_GetColormap</B>. When a colormap's reference count becomes zero, Tk releases the X colormap. <P> <B><A HREF="../TkLib/GetVisual.htm">Tk_GetVisual</A></B> and <B>Tk_GetColormap</B> work together, in that a new colormap created by <B><A HREF="../TkLib/GetVisual.htm">Tk_GetVisual</A></B> may later be returned by <B>Tk_GetColormap</B>. The reference counting mechanism for colormaps includes both procedures, so callers of <B><A HREF="../TkLib/GetVisual.htm">Tk_GetVisual</A></B> must also call <B>Tk_FreeColormap</B> to release the colormap. If <B>Tk_GetColormap</B> is called with a <I>string</I> value of <B>new</B> then the resulting colormap will never be returned by <B><A HREF="../TkLib/GetVisual.htm">Tk_GetVisual</A></B>; however, it can be used in other windows by calling <B>Tk_GetColormap</B> with the original window's name as <I>string</I>. <H3><A NAME="M6">KEYWORDS</A></H3> <A href="../Keywords/C.htm#colormap">colormap</A> <HR><PRE> <A HREF="../copyright.htm">Copyright</A> © 1994 The Regents of the University of California. <A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc. <A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE> </BODY></HTML>