1Tk_GetColormap(3) Tk Library Procedures Tk_GetColormap(3)
2______________________________________________________________________________
6
8 Tk_GetColormap, Tk_PreserveColormap, Tk_FreeColormap - allocate and
9 free colormaps
10
12 #include <tk.h>
13 Colormap
15 Tk_GetColormap(interp, tkwin, string)
16 Tk_PreserveColormap(display, colormap)
18 Tk_FreeColormap(display, colormap)
20
22 Tcl_Interp *interp (in) Interpreter to use for error reporting.
23 Tk_Window tkwin (in) Token for window in which colormap will
25 be used.
26 const char *string (in) Selects a colormap: either new or the
28 name of a window with the same screen
29 and visual as tkwin.
30 Display *display (in) Display for which colormap was allo‐
32 cated.
33 Colormap colormap (in) Colormap to free or preserve; must
35 have been returned by a previous call
36 to Tk_GetColormap or Tk_GetVisual.
37______________________________________________________________________________
38
40 These procedures are used to manage colormaps. Tk_GetColormap returns
41 a colormap suitable for use in tkwin. If its string argument is new
42 then a new colormap is created; otherwise string must be the name of
43 another window with the same screen and visual as tkwin, and the col‐
44 ormap from that window is returned. If string does not make sense, or
45 if it refers to a window on a different screen from tkwin or with a
46 different visual than tkwin, then Tk_GetColormap returns None and
47 leaves an error message in interp's result.
48 Tk_PreserveColormap increases the internal reference count for a col‐
50 ormap previously returned by Tk_GetColormap, which allows the colormap
51 to be stored in several locations without knowing which order they will
52 be released.
53 Tk_FreeColormap should be called when a colormap returned by Tk_GetCol‐
55 ormap is no longer needed. Tk maintains a reference count for each
56 colormap returned by Tk_GetColormap, so there should eventually be one
57 call to Tk_FreeColormap for each call to Tk_GetColormap and each call
58 to Tk_PreserveColormap. When a colormap's reference count becomes
59 zero, Tk releases the X colormap.
60 Tk_GetVisual and Tk_GetColormap work together, in that a new colormap
62 created by Tk_GetVisual may later be returned by Tk_GetColormap. The
63 reference counting mechanism for colormaps includes both procedures, so
64 callers of Tk_GetVisual must also call Tk_FreeColormap to release the
65 colormap. If Tk_GetColormap is called with a string value of new then
66 the resulting colormap will never be returned by Tk_GetVisual; how‐
67 ever, it can be used in other windows by calling Tk_GetColormap with
68 the original window's name as string.
69
71 colormap, visual
72Tk 4.0 Tk_GetColormap(3)