* Merged 8.1 branch into the main trunk

FossilOrigin-Name: 1120dc4257448ed1955333e682de48e2940cc741

1 files changed, 94 insertions, 42 deletions

diff --git a/doc/GetBitmap.3 b/doc/GetBitmap.3
index 4321cce..28b5cb1 100644
--- a/doc/GetBitmap.3
+++ b/doc/GetBitmap.3
@@ -1,42 +1,61 @@
 '\"
 '\" Copyright (c) 1990 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" 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.2 1998/09/14 18:22:48 stanton Exp $
+'\" RCS: @(#) $Id: GetBitmap.3,v 1.3 1999/04/16 01:51:08 stanton Exp $
 '\" 
 .so man.macros
-.TH Tk_GetBitmap 3 8.0 Tk "Tk Library Procedures"
+.TH Tk_AllocBitmapFromObj 3 8.1 Tk "Tk Library Procedures"
 .BS
 .SH NAME
-Tk_GetBitmap, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmap, Tk_GetBitmapFromData \- maintain database of single-plane pixmaps
+Tk_AllocBitmapFromObj, Tk_GetBitmap, Tk_GetBitmapFromObj, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmapFromObj, Tk_FreeBitmap, Tk_GetBitmapFromData \- maintain database of single-plane pixmaps
 .SH SYNOPSIS
 .nf
 \fB#include <tk.h>\fR
 .sp
+.VS 8.1
 Pixmap
-\fBTk_GetBitmap(\fIinterp, tkwin, id\fB)\fR
+\fBTk_GetBitmapFromObj(\fIinterp, tkwin, objPtr\fB)\fR
+.sp
+Pixmap
+\fBTk_GetBitmap(\fIinterp, tkwin, info\fB)\fR
+.sp
+Pixmap
+\fBTk_GetBitmapFromObj(\fItkwin, objPtr\fB)\fR
+.VE
 .sp
 int
-\fBTk_DefineBitmap(\fIinterp, nameId, source, width, height\fB)\fR
+\fBTk_DefineBitmap(\fIinterp, name, source, width, height\fB)\fR
 .sp
-Tk_Uid
+char *
 \fBTk_NameOfBitmap(\fIdisplay, bitmap\fB)\fR
 .sp
 \fBTk_SizeOfBitmap(\fIdisplay, bitmap, widthPtr, heightPtr\fB)\fR
 .sp
+.VS 8.1
+\fBTk_FreeBitmapFromObj(\fItkwin, objPtr\fB)\fR
+.VE
+.sp
 \fBTk_FreeBitmap(\fIdisplay, bitmap\fB)\fR
 .SH ARGUMENTS
 .AS "unsigned long" *pixelPtr
 .AP Tcl_Interp *interp in
-Interpreter to use for error reporting.
+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.
-.AP Tk_Uid id in
-Description of bitmap;  see below for possible values.
-.AP Tk_Uid nameId in
+.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 \fIobjPtr\fR 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 char *source in
 Data for bitmap, in standard bitmap format.
@@ -52,7 +71,8 @@ Pointer to word to fill in with \fIbitmap\fR's height.
 .AP Display *display in
 Display for which \fIbitmap\fR was allocated.
 .AP Pixmap bitmap in
-Identifier for a bitmap allocated by \fBTk_GetBitmap\fR.
+Identifier for a bitmap allocated by \fBTk_AllocBitmapFromObj\fR or
+\fBTk_GetBitmap\fR.
 .BE
 
 .SH DESCRIPTION
@@ -62,11 +82,13 @@ 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
-\fBTk_GetBitmap\fR takes as argument a Tk_Uid describing a bitmap.
-It returns a Pixmap identifier for a bitmap corresponding to the
-description.  It re-uses an existing bitmap, if possible, and
-creates a new one otherwise.  At present, \fIid\fR must have
-one of the following forms:
+.VS 8.1
+\fBTk_AllocBitmapFromObj\fR returns a Pixmap identifier for a bitmap
+that matches the description in \fIobjPtr\fR and is suitable for use
+in \fItkwin\fR.  It re-uses an existing bitmap, if possible, and
+creates a new one otherwise.  \fIObjPtr\fR's value must have one
+of the following forms:
+.VE
 .TP 20
 \fB@\fIfileName\fR
 \fIFileName\fR must be the name of a file containing a bitmap
@@ -166,15 +188,35 @@ A face with ballon words.
 A triangle with an exclamation point.
 .RE
 .LP
-Under normal conditions, \fBTk_GetBitmap\fR
+.VS 8.1
+Under normal conditions, \fBTk_AllocBitmapFromObj\fR
 returns an identifier for the requested bitmap.  If an error
-occurs in creating the bitmap, such as when \fIid\fR refers
+occurs in creating the bitmap, such as when \fIobjPtr\fR refers
 to a non-existent file, then \fBNone\fR is returned and an error
-message is left in \fIinterp->result\fR.
+message is left in \fIinterp\fR's result if \fIinterp\fR isn't
+NULL. \fBTk_AllocBitmapFromObj\fR caches information about the return
+value in \fIobjPtr\fR, which speeds up future calls to procedures
+such as \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmapFromObj\fR.
+.PP
+\fBTk_GetBitmap\fR is identical to \fBTk_AllocBitmapFromObj\fR except
+that the description of the bitmap is specified with a string instead
+of an object.  This prevents \fBTk_GetBitmap\fR from caching the
+return value, so \fBTk_GetBitmap\fR is less efficient than
+\fBTk_AllocBitmapFromObj\fR.
+.PP
+\fBTk_GetBitmapFromObj\fR returns the token for an existing bitmap, given
+the window and description used to create the bitmap.
+\fBTk_GetBitmapFromObj\fR doesn't actually create the bitmap; the bitmap
+must already have been created with a previous call to
+\fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR.  The return
+value is cached in \fIobjPtr\fR, which speeds up
+future calls to \fBTk_GetBitmapFromObj\fR with the same \fIobjPtr\fR
+and \fItkwin\fR.
+.VE
 .PP
 \fBTk_DefineBitmap\fR associates a name with
 in-memory bitmap data so that the name can be used in later
-calls to \fBTk_GetBitmap\fR.  The \fInameId\fR
+calls to \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR.  The \fInameId\fR
 argument gives a name for the bitmap;  it must not previously
 have been used in a call to \fBTk_DefineBitmap\fR.
 The arguments \fIsource\fR, \fIwidth\fR, and \fIheight\fR
@@ -186,7 +228,8 @@ TCL_ERROR is returned and an error message is left in
 Note:  \fBTk_DefineBitmap\fR expects the memory pointed to by
 \fIsource\fR to be static:  \fBTk_DefineBitmap\fR doesn't make
 a private copy of this memory, but uses the bytes pointed to
-by \fIsource\fR later in calls to \fBTk_GetBitmap\fR.
+by \fIsource\fR later in calls to \fBTk_AllocBitmapFromObj\fR or
+\fBTk_GetBitmap\fR.
 .PP
 Typically \fBTk_DefineBitmap\fR is used by \fB#include\fR-ing a
 bitmap file directly into a C program and then referencing
@@ -196,36 +239,40 @@ which was created by the \fBbitmap\fR program and contains
 a stipple pattern.
 The following code uses \fBTk_DefineBitmap\fR to define a
 new bitmap named \fBfoo\fR:
+.VS
 .CS
 Pixmap bitmap;
 #include "stip.bitmap"
-Tk_DefineBitmap(interp, Tk_GetUid("foo"), stip_bits,
+Tk_DefineBitmap(interp, "foo", stip_bits,
 	stip_width, stip_height);
 \&...
-bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("foo"));
+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_GetBitmap\fR:
+.VS
 .CS
 Pixmap bitmap;
-bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("@stip.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
-\fBTk_GetBitmap\fR maintains a
-database of all the bitmaps that are currently in use.
+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_GetBitmap\fR should generally be used in preference to Xlib
-procedures like \fBXReadBitmapFile\fR.
+\fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR should generally
+be used in preference to Xlib procedures like \fBXReadBitmapFile\fR.
 .PP
-The bitmaps returned by \fBTk_GetBitmap\fR
+The bitmaps returned by \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR
 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 \fBXReadBitmapFile\fR
@@ -233,28 +280,33 @@ or \fBXCreatePixmap\fR directly.
 .PP
 The procedure \fBTk_NameOfBitmap\fR is roughly the inverse of
 \fBTk_GetBitmap\fR.
-Given an X Pixmap argument, it returns the \fIid\fR that was
+Given an X Pixmap argument, it returns the textual description that was
 passed to \fBTk_GetBitmap\fR when the bitmap was created.
 \fIBitmap\fR must have been the return value from a previous
-call to \fBTk_GetBitmap\fR.
+call to \fBTk_AllocBitmapFromObj\fR or \fBTk_GetBitmap\fR.
 .PP
 \fBTk_SizeOfBitmap\fR returns the dimensions of its \fIbitmap\fR
 argument in the words pointed to by the \fIwidthPtr\fR and
 \fIheightPtr\fR arguments.  As with \fBTk_NameOfBitmap\fR,
-\fIbitmap\fR must have been created by \fBTk_GetBitmap\fR.
+\fIbitmap\fR must have been created by \fBTk_AllocBitmapFromObj\fR or
+\fBTk_GetBitmap\fR.
 .PP
-When a bitmap returned by \fBTk_GetBitmap\fR
-is no longer needed, \fBTk_FreeBitmap\fR should be called to release it.
-There should be exactly one call to \fBTk_FreeBitmap\fR for
-each call to \fBTk_GetBitmap\fR.
-When a bitmap is no longer in use anywhere (i.e. it has been freed as
-many times as it has been gotten) \fBTk_FreeBitmap\fR will release
-it to the X server and delete it from the database.
+.VS 8.1
+When a bitmap is no longer needed, \fBTk_FreeBitmapFromObj\fR or
+\fBTk_FreeBitmap\fR should be called to release it.
+For \fBTk_FreeBitmapFromObj\fR the bitmap to release is specified
+with the same information used to create it; for
+\fBTk_FreeBitmap\fR the bitmap to release is specified
+with its Pixmap token.
+There should be exactly one call to \fBTk_FreeBitmapFromObj\fR
+or \fBTk_FreeBitmap\fR for each call to \fBTk_AllocBitmapFromObj\fR or
+\fBTk_GetBitmap\fR.
+.VE
 
 .SH BUGS
 In determining whether an existing bitmap can be used to satisfy
-a new request, \fBTk_GetBitmap\fR
-considers only the immediate value of its \fIid\fR argument.  For
+a new request, \fBTk_AllocBitmapFromObj\fR and \fBTk_GetBitmap\fR
+consider only the immediate value of the string description.  For
 example, when a file name is passed to \fBTk_GetBitmap\fR,
 \fBTk_GetBitmap\fR will assume it is safe to re-use an existing
 bitmap created from the same file name:  it will not check to