1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
|
# Copyright (c) 1994 The Regents of the University of California.
# Copyright (c) 1994-1996 Sun Microsystems, Inc.
# See the file "license.terms" for information on usage and redistribution
# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
#
#
=head1 NAME
Tk_GetColormap, Tk_FreeColormap - allocate and free colormaps
=for category C Programming
=head1 SYNOPSIS
B<#include E<lt>tk.hE<gt>>
Colormap
B<Tk_GetColormap(>I<interp, tkwin, string>B<)>
B<Tk_FreeColormap(>I<display, colormap>B<)>
=head1 ARGUMENTS
=over 4
=item Tcl_Interp *interp (in)
Interpreter to use for error reporting.
=item Tk_Window tkwin (in)
Token for window in which colormap will be used.
=item char *string (in)
Selects a colormap: either B<new> or the name of a window
with the same screen and visual as I<tkwin>.
=item Display *display (in)
Display for which I<colormap> was allocated.
=item Colormap colormap (in)
Colormap to free; must have been returned by a previous
call to B<Tk_GetColormap> or B<Tk_GetVisual>.
=back
=head1 DESCRIPTION
These procedures are used to manage colormaps.
B<Tk_GetColormap> returns a colormap suitable for use in I<tkwin>.
If its I<string> argument is B<new> then a new colormap is
created; otherwise I<string> must be the name of another window
with the same screen and visual as I<tkwin>, and the colormap from that
window is returned.
If I<string> doesn't make sense, or if it refers to a window on
a different screen from I<tkwin> or with
a different visual than I<tkwin>, then B<Tk_GetColormap> returns
B<None> and leaves an error message in I<interp-E<gt>result>.
B<Tk_FreeColormap> should be called when a colormap returned by
B<Tk_GetColormap> is no longer needed.
Tk maintains a reference count for each colormap returned by
B<Tk_GetColormap>, so there should eventually be one call to
B<Tk_FreeColormap> for each call to B<Tk_GetColormap>.
When a colormap's reference count becomes zero, Tk releases the
X colormap.
B<Tk_GetVisual> and B<Tk_GetColormap> work together, in that
a new colormap created by B<Tk_GetVisual> may later be returned
by B<Tk_GetColormap>.
The reference counting mechanism for colormaps includes both procedures,
so callers of B<Tk_GetVisual> must also call B<Tk_FreeColormap>
to release the colormap.
If B<Tk_GetColormap> is called with a I<string> value of
B<new> then the resulting colormap will never
be returned by B<Tk_GetVisual>; however, it can be used in other
windows by calling B<Tk_GetColormap> with the original window's
name as I<string>.
=head1 KEYWORDS
colormap
|
