Initial revision

1 files changed, 98 insertions, 0 deletions

diff --git a/doc/GetVisual.3 b/doc/GetVisual.3
new file mode 100644
index 0000000..cf54c2c
--- /dev/null
+++ b/doc/GetVisual.3
@@ -0,0 +1,98 @@
+'\"
+'\" Copyright (c) 1994 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+'\" SCCS: @(#) GetVisual.3 1.9 96/03/26 18:13:20
+'\" 
+.so man.macros
+.TH Tk_GetVisual 3 4.0 Tk "Tk Library Procedures"
+.BS
+.SH NAME
+Tk_GetVisual \- translate from string to visual
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+Visual *
+\fBTk_GetVisual(\fIinterp, tkwin, string, depthPtr, colormapPtr\fB)\fR
+.SH ARGUMENTS
+.AS "Tcl_Interp" *colormapPtr
+.AP Tcl_Interp *interp in
+Interpreter to use for error reporting.
+.AP Tk_Window tkwin in
+Token for window in which the visual will be used.
+.AP char *string in
+String that identifies the desired visual.  See below for
+valid formats.
+.AP int *depthPtr out
+Depth of returned visual gets stored here.
+.AP Colormap *colormapPtr out
+If non-NULL then a suitable colormap for visual is found and its
+identifier is stored here.
+.BE
+
+.SH DESCRIPTION
+.PP
+\fBTk_GetVisual\fR takes a string description of a visual and
+finds a suitable X Visual for use in \fItkwin\fR, 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 \fI*depthPtr\fR.
+If \fIstring\fR is unrecognizable or if no suitable visual could
+be found, then NULL is returned and \fBTk_GetVisual\fR leaves
+an error message in \fIinterp->result\fR.
+If \fIcolormap\fR is non-NULL then \fBTk_GetVisual\fR
+also locates an appropriate colormap for use with the result visual
+and stores its X identifier at \fI*colormapPtr\fR.
+.PP
+The \fIstring\fR argument specifies the desired visual in one
+of the following ways:
+.TP 15
+\fIclass depth\fR
+The string consists of a class name followed by an integer depth,
+with any amount of white space (including none) in between.
+\fIclass\fR selects what sort of visual is desired and must be one of
+\fBdirectcolor\fR, \fBgrayscale\fR, \fBgreyscale\fR, \fBpseudocolor\fR,
+\fBstaticcolor\fR, \fBstaticgray\fR, \fBstaticgrey\fR, or
+\fBtruecolor\fR, or a unique abbreviation.
+\fIdepth\fR specifies how many bits per pixel are needed for the
+visual.
+If possible, \fBTk_GetVisual\fR will return a visual with this depth;
+if there is no visual of the desired depth then \fBTk_GetVisual\fR
+looks first for a visual with greater depth, then one with less
+depth.
+.TP 15
+\fBdefault\fR
+Use the default visual for \fItkwin\fR's screen.
+.TP 15
+\fIpathName\fR
+Use the visual for the window given by \fIpathName\fR.
+\fIpathName\fR must be the name of a window on the same screen
+as \fItkwin\fR.
+.TP 15
+\fInumber\fR
+Use the visual whose X identifier is \fInumber\fR.
+.TP 15
+\fBbest\fR ?\fIdepth\fR?
+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 \fIdepth\fR is specified, then the deepest available visual
+is chosen;
+(c) \fBpseudocolor\fR is better than \fBtruecolor\fR or \fBdirectcolor\fR,
+which are better than \fBstaticcolor\fR, which is better than
+\fBstaticgray\fR or \fBgrayscale\fR;
+(d) the default visual for the screen is better than any other visual.
+
+.SH CREDITS
+.PP
+The idea for \fBTk_GetVisual\fR, and the first implementation, came
+from Paul Mackerras.
+
+.SH KEYWORDS
+colormap, screen, visual