TkGetVisual(3) Tk Library Procedures TkGetVisual(3)

NAME
       TkGetVisual - translate from string to visual

SYNOPSIS
       ##iinncclluuddee <>

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

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

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

       CONST char   *string        (in)      String    that   identifies   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  col-
                                             ormap for visual is found and its
                                             identifier is stored here.



DESCRIPTION
       TTkkGGeettVViissuuaall takes a string description of a visual and finds  a  suit-
       able  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
       suitable visual could be found, then NULL is returned and  TTkkGGeettVViissuuaall
       leaves  an  error  message  in interp->result.  If colormap is non-NULL
       then TTkkGGeettVViissuuaall 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 follow-
       ing ways:

       class depth    The string consists of a class name followed by an inte-
                      ger  depth,  with  any  amount of white space (including
                      none) in between.  class selects what sort of visual  is
                      desired  and  must  be  one  of  ddiirreeccttccoolloorr, ggrraayyssccaallee,
                      ggrreeyyssccaallee, ppsseeuuddooccoolloorr, ssttaattiiccccoolloorr, ssttaattiiccggrraayy, ssttaattiicc-
                      ggrreeyy,  or  ttrruueeccoolloorr,  or  a unique abbreviation.  depth
                      specifies how many bits per pixel  are  needed  for  the
                      visual.   If possible, TTkkGGeettVViissuuaall will return a visual
                      with this depth; if there is no visual  of  the  desired
                      depth  then  TTkkGGeettVViissuuaall  looks first for a visual with
                      greater depth, then one with less depth.

       ddeeffaauulltt        Use the default visual for tkwin's screen.

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

       number         Use the visual whose X identifier is number.

       bbeesstt ?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 lit-
                      tle 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 available
                      visual  is  chosen; (c) ppsseeuuddooccoolloorr is better than ttrruuee-
                      ccoolloorr or ddiirreeccttccoolloorr, which are better than ssttaattiiccccoolloorr,
                      which  is  better  than ssttaattiiccggrraayy or ggrraayyssccaallee; (d) the
                      default visual for the screen is better than  any  other
                      visual.


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


KKEEYYWWOORRDDSS
       colormap, screen, visual



Tk                                    4.0                      TkGetVisual(3)