Tk_GetColormap - allocate and free colormaps
#include <tk.h> Colormap Tk_GetColormap(interp, tkwin, string) Tk_PreserveColormap(display, colormap) Tk_FreeColormap(display, colormap)
Tk_GetColormap(3tk) Tk Library Procedures Tk_GetColormap(3tk)
______________________________________________________________________________
NAME
Tk_GetColormap, Tk_PreserveColormap, Tk_FreeColormap - allocate and
free colormaps
SYNOPSIS
#include <tk.h>
Colormap
Tk_GetColormap(interp, tkwin, string)
Tk_PreserveColormap(display, colormap)
Tk_FreeColormap(display, colormap)
ARGUMENTS
Tcl_Interp *interp (in) Interpreter to use for error reporting.
Tk_Window tkwin (in) Token for window in which colormap will
be used.
const char *string (in) Selects a colormap: either new or the
name of a window with the same screen
and visual as tkwin.
Display *display (in) Display for which colormap was allo-
cated.
Colormap colormap (in) Colormap to free or preserve; must
have been returned by a previous call
to Tk_GetColormap or Tk_GetVisual.
______________________________________________________________________________
DESCRIPTION
These procedures are used to manage colormaps. Tk_GetColormap returns
a colormap suitable for use in tkwin. If its string argument is new
then a new colormap is created; otherwise string must be the name of
another window with the same screen and visual as tkwin, and the col-
ormap from that window is returned. If string does not make sense, or
if it refers to a window on a different screen from tkwin or with a
different visual than tkwin, then Tk_GetColormap returns None and
leaves an error message in interp's result.
Tk_PreserveColormap increases the internal reference count for a col-
ormap previously returned by Tk_GetColormap, which allows the colormap
to be stored in several locations without knowing which order they will
be released.
Tk_FreeColormap should be called when a colormap returned by Tk_GetCol-
ormap is no longer needed. Tk maintains a reference count for each
colormap returned by Tk_GetColormap, so there should eventually be one
call to Tk_FreeColormap for each call to Tk_GetColormap and each call
to Tk_PreserveColormap. When a colormap's reference count becomes
zero, Tk releases the X colormap.
Tk_GetVisual and Tk_GetColormap work together, in that a new colormap
created by Tk_GetVisual may later be returned by Tk_GetColormap. The
reference counting mechanism for colormaps includes both procedures, so
callers of Tk_GetVisual must also call Tk_FreeColormap to release the
colormap. If Tk_GetColormap is called with a string value of new then
the resulting colormap will never be returned by Tk_GetVisual; how-
ever, it can be used in other windows by calling Tk_GetColormap with
the original window's name as string.
KEYWORDS
colormap, visual
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+---------------+------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+------------------+
|Availability | runtime/tk-8 |
+---------------+------------------+
|Stability | Uncommitted |
+---------------+------------------+
NOTES
Source code for open source software components in Oracle Solaris can
be found at https://www.oracle.com/downloads/opensource/solaris-source-
code-downloads.html.
This software was built from source available at
https://github.com/oracle/solaris-userland. The original community
source was downloaded from https://source-
forge.net/projects/tcl/files/Tcl/8.6.7/tk8.6.7-src.tar.gz/download.
Further information about this software can be found on the open source
community website at https://www.tcl.tk/.
Tk 4.0 Tk_GetColormap(3tk)