通讯编程

开发平台：
Visual C++

GetBitmap.3：源码内容
							'"
'" Copyright (c) 1990 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: GetBitmap.3,v 1.5.2.1 2005/06/21 23:01:36 dkf Exp $
'" 
.so man.macros
.TH Tk_AllocBitmapFromObj 3 8.1 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_AllocBitmapFromObj, Tk_GetBitmap, Tk_GetBitmapFromObj, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmapFromObj, Tk_FreeBitmap - maintain database of single-plane pixmaps
.SH SYNOPSIS
.nf
fB#include <tk.h>fR
.sp
.VS 8.1
Pixmap
fBTk_AllocBitmapFromObj(fIinterp, tkwin, objPtrfB)fR
.sp
Pixmap
fBTk_GetBitmap(fIinterp, tkwin, infofB)fR
.sp
Pixmap
fBTk_GetBitmapFromObj(fItkwin, objPtrfB)fR
.VE
.sp
int
fBTk_DefineBitmap(fIinterp, name, source, width, heightfB)fR
.sp
CONST char *
fBTk_NameOfBitmap(fIdisplay, bitmapfB)fR
.sp
fBTk_SizeOfBitmap(fIdisplay, bitmap, widthPtr, heightPtrfB)fR
.sp
.VS 8.1
fBTk_FreeBitmapFromObj(fItkwin, objPtrfB)fR
.VE
.sp
fBTk_FreeBitmap(fIdisplay, bitmapfB)fR
.SH ARGUMENTS
.AS "unsigned long" *pixelPtr
.AP Tcl_Interp *interp in
Interpreter to use for error reporting; if NULL then no error message
is left after errors.
.AP Tk_Window tkwin in
Token for window in which the bitmap will be used.
.VS 8.1 br
.AP Tcl_Obj *objPtr in/out
String value describes desired bitmap; internal rep will be
modified to cache pointer to corresponding Pixmap.
.AP "CONST char" *info in
Same as fIobjPtrfR except description of bitmap is passed as a string and
resulting Pixmap isn't cached.
.VE
.AP "CONST char" *name in
Name for new bitmap to be defined.
.AP "CONST char" *source in
Data for bitmap, in standard bitmap format.
Must be stored in static memory whose value will never change.
.AP "int" width in
Width of bitmap.
.AP "int" height in
Height of bitmap.
.AP "int" *widthPtr out
Pointer to word to fill in with fIbitmapfR's width.
.AP "int" *heightPtr out
Pointer to word to fill in with fIbitmapfR's height.
.AP Display *display in
Display for which fIbitmapfR was allocated.
.AP Pixmap bitmap in
Identifier for a bitmap allocated by fBTk_AllocBitmapFromObjfR or
fBTk_GetBitmapfR.
.BE
.SH DESCRIPTION
.PP
These procedures manage a collection of bitmaps (one-plane pixmaps)
being used by an application.  The procedures allow bitmaps to be
re-used efficiently, thereby avoiding server overhead, and also
allow bitmaps to be named with character strings.
.PP
.VS 8.1
fBTk_AllocBitmapFromObjfR returns a Pixmap identifier for a bitmap
that matches the description in fIobjPtrfR and is suitable for use
in fItkwinfR.  It re-uses an existing bitmap, if possible, and
creates a new one otherwise.  fIObjPtrfR's value must have one
of the following forms:
.VE
.TP 20
fB@fIfileNamefR
fIFileNamefR must be the name of a file containing a bitmap
description in the standard X11 or X10 format.
.TP 20
fInamefR
fINamefR must be the name of a bitmap defined previously with
a call to fBTk_DefineBitmapfR.  The following names are pre-defined
by Tk:
.RS
.TP 12
fBerrorfR
The international "don't" symbol:  a circle with a diagonal line
across it.
.VS "" br
.TP 12
fBgray75fR
75% gray: a checkerboard pattern where three out of four bits are on.
.VE
.TP 12
fBgray50fR
50% gray: a checkerboard pattern where every other bit is on.
.VS "" br
.TP 12
fBgray25fR
25% gray: a checkerboard pattern where one out of every four bits is on.
.VE
.TP 12
fBgray12fR
12.5% gray: a pattern where one-eighth of the bits are on, consisting of
every fourth pixel in every other row.
.TP 12
fBhourglassfR
An hourglass symbol.
.TP 12
fBinfofR
A large letter ``i''.
.TP 12
fBquestheadfR
The silhouette of a human head, with a question mark in it.
.TP 12
fBquestionfR
A large question-mark.
.TP 12
fBwarningfR
A large exclamation point.
.PP
In addition, the following pre-defined names are available only on the
fBMacintoshfR platform:
.TP 12
fBdocumentfR
A generic document.
.TP 12
fBstationeryfR
Document stationery.
.TP 12
fBeditionfR
The fIeditionfR symbol.
.TP 12
fBapplicationfR
Generic application icon.
.TP 12
fBaccessoryfR
A desk accessory.
.TP 12
fBfolderfR
Generic folder icon.
.TP 12
fBpfolderfR
A locked folder.
.TP 12
fBtrashfR
A trash can.
.TP 12
fBfloppyfR
A floppy disk.
.TP 12
fBramdiskfR
A floppy disk with chip.
.TP 12
fBcdromfR
A cd disk icon.
.TP 12
fBpreferencesfR
A folder with prefs symbol.
.TP 12
fBquerydocfR
A database document icon.
.TP 12
fBstopfR
A stop sign.
.TP 12
fBnotefR
A face with ballon words.
.TP 12
fBcautionfR
A triangle with an exclamation point.
.RE
.LP
.VS 8.1
Under normal conditions, fBTk_AllocBitmapFromObjfR
returns an identifier for the requested bitmap.  If an error
occurs in creating the bitmap, such as when fIobjPtrfR refers
to a non-existent file, then fBNonefR is returned and an error
message is left in fIinterpfR's result if fIinterpfR isn't
NULL. fBTk_AllocBitmapFromObjfR caches information about the return
value in fIobjPtrfR, which speeds up future calls to procedures
such as fBTk_AllocBitmapFromObjfR and fBTk_GetBitmapFromObjfR.
.PP
fBTk_GetBitmapfR is identical to fBTk_AllocBitmapFromObjfR except
that the description of the bitmap is specified with a string instead
of an object.  This prevents fBTk_GetBitmapfR from caching the
return value, so fBTk_GetBitmapfR is less efficient than
fBTk_AllocBitmapFromObjfR.
.PP
fBTk_GetBitmapFromObjfR returns the token for an existing bitmap, given
the window and description used to create the bitmap.
fBTk_GetBitmapFromObjfR doesn't actually create the bitmap; the bitmap
must already have been created with a previous call to
fBTk_AllocBitmapFromObjfR or fBTk_GetBitmapfR.  The return
value is cached in fIobjPtrfR, which speeds up
future calls to fBTk_GetBitmapFromObjfR with the same fIobjPtrfR
and fItkwinfR.
.VE
.PP
fBTk_DefineBitmapfR associates a name with
in-memory bitmap data so that the name can be used in later
calls to fBTk_AllocBitmapFromObjfR or fBTk_GetBitmapfR.  The fInameIdfR
argument gives a name for the bitmap;  it must not previously
have been used in a call to fBTk_DefineBitmapfR.
The arguments fIsourcefR, fIwidthfR, and fIheightfR
describe the bitmap.
fBTk_DefineBitmapfR normally returns TCL_OK;  if an error occurs
(e.g. a bitmap named fInameIdfR has already been defined) then
TCL_ERROR is returned and an error message is left in
fIinterp->resultfR.
Note:  fBTk_DefineBitmapfR expects the memory pointed to by
fIsourcefR to be static:  fBTk_DefineBitmapfR doesn't make
a private copy of this memory, but uses the bytes pointed to
by fIsourcefR later in calls to fBTk_AllocBitmapFromObjfR or
fBTk_GetBitmapfR.
.PP
Typically fBTk_DefineBitmapfR is used by fB#includefR-ing a
bitmap file directly into a C program and then referencing
the variables defined by the file.
For example, suppose there exists a file fBstip.bitmapfR,
which was created by the fBbitmapfR program and contains
a stipple pattern.
The following code uses fBTk_DefineBitmapfR to define a
new bitmap named fBfoofR:
.VS
.CS
Pixmap bitmap;
#include "stip.bitmap"
Tk_DefineBitmap(interp, "foo", stip_bits,
	stip_width, stip_height);
&...
bitmap = Tk_GetBitmap(interp, tkwin, "foo");
.CE
.VE
This code causes the bitmap file to be read
at compile-time and incorporates the bitmap information into
the program's executable image.  The same bitmap file could be
read at run-time using fBTk_GetBitmapfR:
.VS
.CS
Pixmap bitmap;
bitmap = Tk_GetBitmap(interp, tkwin, "@stip.bitmap");
.CE
.VE
The second form is a bit more flexible (the file could be modified
after the program has been compiled, or a different string could be
provided to read a different file), but it is a little slower and
requires the bitmap file to exist separately from the program.
.PP
Tk maintains a database of all the bitmaps that are currently in use.
Whenever possible, it will return an existing bitmap rather
than creating a new one.
When a bitmap is no longer used, Tk will release it automatically.
This approach can substantially reduce server overhead, so
fBTk_AllocBitmapFromObjfR and fBTk_GetBitmapfR should generally
be used in preference to Xlib procedures like fBXReadBitmapFilefR.
.PP
The bitmaps returned by fBTk_AllocBitmapFromObjfR and fBTk_GetBitmapfR
are shared, so callers should never modify them.
If a bitmap must be modified dynamically, then it should be
created by calling Xlib procedures such as fBXReadBitmapFilefR
or fBXCreatePixmapfR directly.
.PP
The procedure fBTk_NameOfBitmapfR is roughly the inverse of
fBTk_GetBitmapfR.
Given an X Pixmap argument, it returns the textual description that was
passed to fBTk_GetBitmapfR when the bitmap was created.
fIBitmapfR must have been the return value from a previous
call to fBTk_AllocBitmapFromObjfR or fBTk_GetBitmapfR.
.PP
fBTk_SizeOfBitmapfR returns the dimensions of its fIbitmapfR
argument in the words pointed to by the fIwidthPtrfR and
fIheightPtrfR arguments.  As with fBTk_NameOfBitmapfR,
fIbitmapfR must have been created by fBTk_AllocBitmapFromObjfR or
fBTk_GetBitmapfR.
.PP
.VS 8.1
When a bitmap is no longer needed, fBTk_FreeBitmapFromObjfR or
fBTk_FreeBitmapfR should be called to release it.
For fBTk_FreeBitmapFromObjfR the bitmap to release is specified
with the same information used to create it; for
fBTk_FreeBitmapfR the bitmap to release is specified
with its Pixmap token.
There should be exactly one call to fBTk_FreeBitmapFromObjfR
or fBTk_FreeBitmapfR for each call to fBTk_AllocBitmapFromObjfR or
fBTk_GetBitmapfR.
.VE
.SH BUGS
In determining whether an existing bitmap can be used to satisfy
a new request, fBTk_AllocBitmapFromObjfR and fBTk_GetBitmapfR
consider only the immediate value of the string description.  For
example, when a file name is passed to fBTk_GetBitmapfR,
fBTk_GetBitmapfR will assume it is safe to re-use an existing
bitmap created from the same file name:  it will not check to
see whether the file itself has changed, or whether the current
directory has changed, thereby causing the name to refer to
a different file.
.SH KEYWORDS
bitmap, pixmap

						