tk/doc/GetVisual.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 '\" RCS: @(#) $Id$
   9 '\"
  10 .so man.macros
  11 .TH Tk_GetVisual 3 4.0 Tk "Tk Library Procedures"
  12 .BS
  13 .SH NAME
  14 Tk_GetVisual \- translate from string to visual
  15 .SH SYNOPSIS
  16 .nf
  17 \fB#include <tk.h>\fR
  18 .sp
  19 Visual *
  20 \fBTk_GetVisual(\fIinterp, tkwin, string, depthPtr, colormapPtr\fB)\fR
  21 .SH ARGUMENTS
  22 .AS "Tcl_Interp" *colormapPtr
  23 .AP Tcl_Interp *interp in
  24 Interpreter to use for error reporting.
  25 .AP Tk_Window tkwin in
  26 Token for window in which the visual will be used.
  27 .AP "CONST char" *string in
  28 String that identifies the desired visual.  See below for
  29 valid formats.
  30 .AP int *depthPtr out
  31 Depth of returned visual gets stored here.
  32 .AP Colormap *colormapPtr out
  33 If non-NULL then a suitable colormap for visual is found and its
  34 identifier is stored here.
  35 .BE
  36
  37 .SH DESCRIPTION
  38 .PP
  39 \fBTk_GetVisual\fR takes a string description of a visual and
  40 finds a suitable X Visual for use in \fItkwin\fR, if there is one.
  41 It returns a pointer to the X Visual structure for the visual
  42 and stores the number of bits per pixel for it at \fI*depthPtr\fR.
  43 If \fIstring\fR is unrecognizable or if no suitable visual could
  44 be found, then NULL is returned and \fBTk_GetVisual\fR leaves
  45 an error message in \fIinterp->result\fR.
  46 If \fIcolormap\fR is non-NULL then \fBTk_GetVisual\fR
  47 also locates an appropriate colormap for use with the result visual
  48 and stores its X identifier at \fI*colormapPtr\fR.
  49 .PP
  50 The \fIstring\fR argument specifies the desired visual in one
  51 of the following ways:
  52 .TP 15
  53 \fIclass depth\fR
  54 The string consists of a class name followed by an integer depth,
  55 with any amount of white space (including none) in between.
  56 \fIclass\fR selects what sort of visual is desired and must be one of
  57 \fBdirectcolor\fR, \fBgrayscale\fR, \fBgreyscale\fR, \fBpseudocolor\fR,
  58 \fBstaticcolor\fR, \fBstaticgray\fR, \fBstaticgrey\fR, or
  59 \fBtruecolor\fR, or a unique abbreviation.
  60 \fIdepth\fR specifies how many bits per pixel are needed for the
  61 visual.
  62 If possible, \fBTk_GetVisual\fR will return a visual with this depth;
  63 if there is no visual of the desired depth then \fBTk_GetVisual\fR
  64 looks first for a visual with greater depth, then one with less
  65 depth.
  66 .TP 15
  67 \fBdefault\fR
  68 Use the default visual for \fItkwin\fR's screen.
  69 .TP 15
  70 \fIpathName\fR
  71 Use the visual for the window given by \fIpathName\fR.
  72 \fIpathName\fR must be the name of a window on the same screen
  73 as \fItkwin\fR.
  74 .TP 15
  75 \fInumber\fR
  76 Use the visual whose X identifier is \fInumber\fR.
  77 .TP 15
  78 \fBbest\fR ?\fIdepth\fR?
  79 Choose the ``best possible'' visual, using the following rules, in
  80 decreasing order of priority:
  81 (a) a visual that has exactly the desired depth is best, followed
  82 by a visual with greater depth than requested (but as little extra
  83 as possible), followed by a visual with less depth than requested
  84 (but as great a depth as possible);
  85 (b) if no \fIdepth\fR is specified, then the deepest available visual
  86 is chosen;
  87 (c) \fBpseudocolor\fR is better than \fBtruecolor\fR or \fBdirectcolor\fR,
  88 which are better than \fBstaticcolor\fR, which is better than
  89 \fBstaticgray\fR or \fBgrayscale\fR;
  90 (d) the default visual for the screen is better than any other visual.
  91
  92 .SH CREDITS
  93 .PP
  94 The idea for \fBTk_GetVisual\fR, and the first implementation, came
  95 from Paul Mackerras.
  96
  97 .SH KEYWORDS
  98 colormap, screen, visual