DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

Tk_GetColormap(3)




Tk_GetColormap(3)     Tk Library Procedures     Tk_GetColormap(3)

_________________________________________________________________


NAME

     Tk_GetColormap, Tk_PreserveColormap, Tk_FreeColormap - allo-
     cate 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 allocated.

     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 win-
     dow with the same screen and visual as tkwin, and the color-
     map  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 colormap previously returned by Tk_GetColormap, which

Tk                      Last change: 4.0                        1

Tk_GetColormap(3)     Tk Library Procedures     Tk_GetColormap(3)

     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_GetColormap  is  no longer needed.  Tk maintains a refer-
     ence 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 color-
     maps  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;
     however,  it  can  be  used  in  other  windows  by  calling
     Tk_GetColormap with the original window's name as string.


KEYWORDS

     colormap, visual

Tk                      Last change: 4.0                        2


Man(1) output converted with man2html