| 1 |
578 |
markom |
'\"
|
| 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: GetVisual.3,v 1.1.1.1 2002-01-16 10:25:48 markom Exp $
|
| 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 \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 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
|
