util/src/TclTk/tk8.6.12/doc/GetClrmap.3

   1 '\"
   2 '\" Copyright (c) 1994 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 .TH Tk_GetColormap 3 4.0 Tk "Tk Library Procedures"
   9 .so man.macros
  10 .BS
  11 .SH NAME
  12 Tk_GetColormap, Tk_PreserveColormap, Tk_FreeColormap \- allocate and free colormaps
  13 .SH SYNOPSIS
  14 .nf
  15 \fB#include <tk.h>\fR
  16 .sp
  17 Colormap
  18 \fBTk_GetColormap(\fIinterp, tkwin, string\fB)\fR
  19 .sp
  20 \fBTk_PreserveColormap(\fIdisplay, colormap\fB)\fR
  21 .sp
  22 \fBTk_FreeColormap(\fIdisplay, colormap\fB)\fR
  23 .SH ARGUMENTS
  24 .AS "Colormap" colormap
  25 .AP Tcl_Interp *interp in
  26 Interpreter to use for error reporting.
  27 .AP Tk_Window tkwin in
  28 Token for window in which colormap will be used.
  29 .AP "const char" *string in
  30 Selects a colormap:  either \fBnew\fR or the name of a window
  31 with the same screen and visual as \fItkwin\fR.
  32 .AP Display *display in
  33 Display for which \fIcolormap\fR was allocated.
  34 .AP Colormap colormap in
  35 Colormap to free or preserve;  must have been returned by a previous
  36 call to \fBTk_GetColormap\fR or \fBTk_GetVisual\fR.
  37 .BE
  38 .SH DESCRIPTION
  39 .PP
  40 These procedures are used to manage colormaps.
  41 \fBTk_GetColormap\fR returns a colormap suitable for use in \fItkwin\fR.
  42 If its \fIstring\fR argument is \fBnew\fR then a new colormap is
  43 created;  otherwise \fIstring\fR must be the name of another window
  44 with the same screen and visual as \fItkwin\fR, and the colormap from that
  45 window is returned.
  46 If \fIstring\fR does not make sense, or if it refers to a window on
  47 a different screen from \fItkwin\fR or with
  48 a different visual than \fItkwin\fR, then \fBTk_GetColormap\fR returns
  49 \fBNone\fR and leaves an error message in \fIinterp\fR's result.
  50 .PP
  51 \fBTk_PreserveColormap\fR increases the internal reference count for a
  52 colormap previously returned by \fBTk_GetColormap\fR, which allows the
  53 colormap to be stored in several locations without knowing which order
  54 they will be released.
  55 .PP
  56 \fBTk_FreeColormap\fR should be called when a colormap returned by
  57 \fBTk_GetColormap\fR is no longer needed.
  58 Tk maintains a reference count for each colormap returned by
  59 \fBTk_GetColormap\fR, so there should eventually be one call to
  60 \fBTk_FreeColormap\fR for each call to \fBTk_GetColormap\fR and each
  61 call to \fBTk_PreserveColormap\fR.
  62 When a colormap's reference count becomes zero, Tk releases the
  63 X colormap.
  64 .PP
  65 \fBTk_GetVisual\fR and \fBTk_GetColormap\fR work together, in that
  66 a new colormap created by \fBTk_GetVisual\fR may later be returned
  67 by \fBTk_GetColormap\fR.
  68 The reference counting mechanism for colormaps includes both procedures,
  69 so callers of \fBTk_GetVisual\fR must also call \fBTk_FreeColormap\fR
  70 to release the colormap.
  71 If \fBTk_GetColormap\fR is called with a \fIstring\fR value of
  72 \fBnew\fR then the resulting colormap will never
  73 be returned by \fBTk_GetVisual\fR;  however, it can be used in other
  74 windows by calling \fBTk_GetColormap\fR with the original window's
  75 name as \fIstring\fR.
  76 .SH KEYWORDS
  77 colormap, visual