通讯编程

开发平台：
Visual C++

GetColor.3：源码内容
							'"
'" Copyright (c) 1990-1991 The Regents of the University of California.
'" Copyright (c) 1994-1998 Sun Microsystems, Inc.
'"
'" See the file "license.terms" for information on usage and redistribution
'" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'" 
'" RCS: @(#) $Id: GetColor.3,v 1.4 2002/08/05 04:30:38 dgp Exp $
'" 
.so man.macros
.TH Tk_AllocColorFromObj 3 8.1 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_AllocColorFromObj, Tk_GetColor, Tk_GetColorFromObj, Tk_GetColorByValue, Tk_NameOfColor, Tk_FreeColorFromObj, Tk_FreeColor - maintain database of colors
.SH SYNOPSIS
.nf
fB#include <tk.h>fR
.VS 8.1
.sp
XColor *
fBTk_AllocColorFromObj(fIinterp, tkwin, objPtrfB)fR
.sp
XColor *
fBTk_GetColor(fIinterp, tkwin, namefB)fR
.sp
XColor *
fBTk_GetColorFromObj(fItkwin, objPtrfB)fR
.VE
.sp
XColor *
fBTk_GetColorByValue(fItkwin, prefPtrfB)fR
.sp
CONST char *
fBTk_NameOfColor(fIcolorPtrfB)fR
.sp
GC
fBTk_GCForColor(fIcolorPtr, drawablefB)fR
.sp
.VS 8.1
fBTk_FreeColorFromObj(fItkwin, objPtrfB)fR
.VE
.sp
fBTk_FreeColor(fIcolorPtrfB)fR
.SH ARGUMENTS
.AS "Tcl_Interp" *colorPtr
.AP Tcl_Interp *interp in
Interpreter to use for error reporting.
.AP Tk_Window tkwin in
Token for window in which color will be used.
.VS 8.1 br
.AP Tcl_Obj *objPtr in/out
String value describes desired color; internal rep will be
modified to cache pointer to corresponding (XColor *).
.AP char *name in
Same as fIobjPtrfR except description of color is passed as a string and
resulting (XColor *) isn't cached.
.VE
.AP XColor *prefPtr in
Indicates red, green, and blue intensities of desired
color.
.AP XColor *colorPtr in
Pointer to X color information.  Must have been allocated by previous
call to fBTk_AllocColorFromObjfR, fBTk_GetColorfR or
fBTk_GetColorByValuefR, except when passed to fBTk_NameOfColorfR.
.AP Drawable drawable in
Drawable in which the result graphics context will be used.  Must have
same screen and depth as the window for which the color was allocated.
.BE
.SH DESCRIPTION
.VS 8.1
.PP
These procedures manage the colors being used by a Tk application.
They allow colors to be shared whenever possible, so that colormap
space is preserved, and they pick closest available colors when
colormap space is exhausted.
.PP
Given a textual description of a color, fBTk_AllocColorFromObjfR
locates a pixel value that may be used to render the color
in a particular window.  The desired color is specified with an
object whose string value must have one of the following forms:
.VE
.TP 20
fIcolornamefR
Any of the valid textual names for a color defined in the
server's color database file, such as fBredfR or fBPeachPufffR.
.TP 20
fB#fIRGBfR
.TP 20
fB#fIRRGGBBfR
.TP 20
fB#fIRRRGGGBBBfR
.TP 20
fB#fIRRRRGGGGBBBBfR
A numeric specification of the red, green, and blue intensities
to use to display the color.  Each fIRfR, fIGfR, or fIBfR
represents a single hexadecimal digit.  The four forms permit
colors to be specified with 4-bit, 8-bit, 12-bit or 16-bit values.
When fewer than 16 bits are provided for each color, they represent
the most significant bits of the color.  For example, #3a7 is the
same as #3000a0007000.
.PP
.VS 8.1
fBTk_AllocColorFromObjfR returns a pointer to
an XColor structure;  the structure indicates the exact intensities of
the allocated color (which may differ slightly from those requested,
depending on the limitations of the screen) and a pixel value
that may be used to draw with the color in fItkwinfR.
If an error occurs in fBTk_AllocColorFromObjfR (such as an unknown
color name) then NULL is returned and an error message is stored in
fIinterpfR's result if fIinterpfR isn't NULL.
If the colormap for fItkwinfR is full, fBTk_AllocColorFromObjfR
will use the closest existing color in the colormap.
fBTk_AllocColorFromObjfR caches information about
the return value in fIobjPtrfR, which speeds up future calls to procedures
such as fBTk_AllocColorFromObjfR and fBTk_GetColorFromObjfR.
.PP
fBTk_GetColorfR is identical to fBTk_AllocColorFromObjfR except
that the description of the color is specified with a string instead
of an object.  This prevents fBTk_GetColorfR from caching the
return value, so fBTk_GetColorfR is less efficient than
fBTk_AllocColorFromObjfR.
.PP
fBTk_GetColorFromObjfR returns the token for an existing color, given
the window and description used to create the color.
fBTk_GetColorFromObjfR doesn't actually create the color; the color
must already have been created with a previous call to
fBTk_AllocColorFromObjfR or fBTk_GetColorfR.  The return
value is cached in fIobjPtrfR, which speeds up
future calls to fBTk_GetColorFromObjfR with the same fIobjPtrfR
and fItkwinfR.
.VE
.PP
fBTk_GetColorByValuefR is similar to fBTk_GetColorfR except that
the desired color is indicated with the fIredfR, fIgreenfR, and
fIbluefR fields of the structure pointed to by fIcolorPtrfR.
.PP
This package maintains a database
of all the colors currently in use.
If the same color is requested multiple times from
fBTk_GetColorfR or fBTk_AllocColorFromObjfR (e.g. by different
windows), or if the 
same intensities are requested multiple times from
fBTk_GetColorByValuefR, then existing pixel values will
be re-used.  Re-using an existing pixel avoids any interaction
with the window server, which makes the allocation much more
efficient.  These procedures also provide a portable interface that
works across all platforms.  For this reason, you should generally use
fBTk_AllocColorFromObjfR, fBTk_GetColorfR, or fBTk_GetColorByValuefR
instead of lower level procedures like fBXAllocColorfR.
.PP
Since different calls to this package
may return the same shared
pixel value, callers should never change the color of a pixel
returned by the procedures.
If you need to change a color value dynamically, you should use
fBXAllocColorCellsfR to allocate the pixel value for the color.
.PP
The procedure fBTk_NameOfColorfR is roughly the inverse of
fBTk_GetColorfR.  If its fIcolorPtrfR argument was created
by fBTk_AllocColorFromObjfR or fBTk_GetColorfR then the return value
is the string that was used to create the
color.  If fIcolorPtrfR was created by a call to fBTk_GetColorByValuefR,
or by any other mechanism, then the return value is a string
that could be passed to fBTk_GetColorfR to return the same
color.  Note:  the string returned by fBTk_NameOfColorfR is
only guaranteed to persist until the next call to
fBTk_NameOfColorfR.
.PP
fBTk_GCForColorfR returns a graphics context whose fBforegroundfR
field is the pixel allocated for fIcolorPtrfR and whose other fields
all have default values.
This provides an easy way to do basic drawing with a color.
The graphics context is cached with the color and will exist only as
long as fIcolorPtrfR exists;  it is freed when the last reference
to fIcolorPtrfR is freed by calling fBTk_FreeColorfR.
.PP
.VS 8.1
When a color is no longer needed fBTk_FreeColorFromObjfR or
fBTk_FreeColorfR should be called to release it.
For fBTk_FreeColorFromObjfR the color to release is specified
with the same information used to create it; for
fBTk_FreeColorfR the color to release is specified
with a pointer to its XColor structure.
There should be exactly one call to fBTk_FreeColorFromObjfR
or fBTk_FreeColorfR for each call to fBTk_AllocColorFromObjfR,
fBTk_GetColorfR, or fBTk_GetColorByValuefR.
.VE
.SH KEYWORDS
color, intensity, object, pixel value

						