NAME

       Tk_GetVisual - translate from string to visual


SYNOPSIS

       #include <tk.h>

       Visual *
       Tk_GetVisual(interp, tkwin, string, depthPtr, colormapPtr)


ARGUMENTS

       Tcl_Interp   *interp        (in)      Interpreter  to  use
                                             for error reporting.

       Tk_Window    tkwin          (in)      Token  for window in
                                             which   the   visual
                                             will be used.

       char         *string        (in)      String  that identi­
                                             fies   the   desired
                                             visual.   See  below
                                             for valid formats.

       int          *depthPtr      (out)     Depth  of   returned
                                             visual  gets  stored
                                             here.

       Colormap     *colormapPtr   (out)     If non-NULL  then  a
                                             suitable    colormap
                                             for visual is  found
                                             and  its  identifier
                                             is stored here.
_________________________________________________________________



DESCRIPTION

       Tk_GetVisual takes a string description of  a  visual  and
       finds  a  suitable  X Visual for use in tkwin, if there is
       one.  It returns a pointer to the X Visual  structure  for
       the  visual and stores the number of bits per pixel for it
       at *depthPtr.  If string is unrecognizable or if no  suit­
       able  visual  could  be  found,  then NULL is returned and
       Tk_GetVisual leaves an error  message  in  interp->result.
       If  colormap is non-NULL then Tk_GetVisual also locates an
       appropriate colormap for use with the  result  visual  and
       stores its X identifier at *colormapPtr.

       The string argument specifies the desired visual in one of
       the following ways:

       class depth    The string consists of a  class  name  fol­
                      lowed  by an integer depth, with any amount
                      desired and must  be  one  of  directcolor,
                      grayscale,  greyscale, pseudocolor, static­
                      color,  staticgray,  staticgrey,  or  true­
                      color,  or  a  unique  abbreviation.  depth
                      specifies  how  many  bits  per  pixel  are
                      needed   for   the  visual.   If  possible,
                      Tk_GetVisual will return a visual with this
                      depth; if there is no visual of the desired
                      depth then Tk_GetVisual looks first  for  a
                      visual  with  greater  depth, then one with
                      less depth.

       default        Use the default visual for tkwin's  screen.

       pathName       Use  the  visual  for  the  window given by
                      pathName.  pathName must be the name  of  a
                      window on the same screen as tkwin.

       number         Use  the  visual whose X identifier is num­
                      ber.

       best ?depth?   Choose the ``best possible'' visual,  using
                      the following rules, in decreasing order of
                      priority: (a) a visual that has exactly the
                      desired depth is best, followed by a visual
                      with greater depth than requested  (but  as
                      little  extra  as  possible), followed by a
                      visual with less depth than requested  (but
                      as  great  a  depth as possible); (b) if no
                      depth is specified, then the deepest avail­
                      able  visual  is chosen; (c) pseudocolor is
                      better than truecolor or directcolor, which
                      are  better than staticcolor, which is bet­
                      ter than staticgray or grayscale;  (d)  the
                      default  visual  for  the  screen is better
                      than any other visual.



CREDITS

       The idea for Tk_GetVisual, and the  first  implementation,
       came from Paul Mackerras.



KEYWORDS

       colormap, screen, visual