1Tk_GetColormap(3)            Tk Library Procedures           Tk_GetColormap(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tk_GetColormap,  Tk_PreserveColormap,  Tk_FreeColormap  -  allocate and
9       free colormaps
10

SYNOPSIS

12       #include <tk.h>
13
14       Colormap
15       Tk_GetColormap(interp, tkwin, string)
16
17       Tk_PreserveColormap(display, colormap)
18
19       Tk_FreeColormap(display, colormap)
20

ARGUMENTS

22       Tcl_Interp *interp (in)         Interpreter to use for error reporting.
23
24       Tk_Window tkwin (in)            Token for window in which colormap will
25                                       be used.
26
27       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
31       Display *display (in)           Display  for  which  colormap was allo‐
32                                       cated.
33
34       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

DESCRIPTION

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
49       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
54       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
61       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

KEYWORDS

71       colormap, visual
72
73
74
75Tk                                    4.0                    Tk_GetColormap(3)
Impressum