* Merged 8.1 branch into the main trunk

1 files changed, 79 insertions, 31 deletions

diff --git a/doc/GetFont.3 b/doc/GetFont.3
index 8971913..f052935 100644
--- a/doc/GetFont.3
+++ b/doc/GetFont.3
@@ -1,74 +1,122 @@
 '\"
 '\" Copyright (c) 1990-1992 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: GetFont.3,v 1.2 1998/09/14 18:22:49 stanton Exp $
+'\" RCS: @(#) $Id: GetFont.3,v 1.3 1999/04/16 01:51:08 stanton Exp $
 '\" 
 .so man.macros
-.TH Tk_GetFont 3 "" Tk "Tk Library Procedures"
+.TH Tk_AllocFontFromObj 3 8.1 Tk "Tk Library Procedures"
 .BS
 .SH NAME
-Tk_GetFont, Tk_NameOfFont, Tk_FreeFont \- maintain database of fonts
+Tk_AllocFontFromObj, Tk_GetFont, Tk_GetFontFromObj, Tk_NameOfFont, Tk_FreeFontFromObj, Tk_FreeFont \- maintain database of fonts
 .SH SYNOPSIS
 .nf
 \fB#include <tk.h>\fR
 .sp
+.VS 8.1
 Tk_Font 
-\fBTk_GetFont(\fIinterp, tkwin, string\fB)\fR
+\fBTk_AllocFontFromObj(\fIinterp, tkwin, objPtr\fB)\fR
+.sp
+Tk_Font 
+\fBTk_GetFont(\fIinterp, tkwin, string\fB)\fR 
+.sp
+Tk_Font 
+\fBTk_GetFontFromObj(\fItkwin, objPtr\fB)\fR
+.VE
 .sp
 char *
 \fBTk_NameOfFont(\fItkfont\fB)\fR
 .sp
+.VS 8.1
+Tk_Font 
+\fBTk_FreeFontFromObj(\fItkwin, objPtr\fB)\fR
+.VE
+.sp
 void
 \fBTk_FreeFont(\fItkfont\fB)\fR
 
 .SH ARGUMENTS
 .AS "const char" *tkfont
 .AP "Tcl_Interp" *interp in
-Interpreter to use for error reporting.
+Interpreter to use for error reporting.  If NULL, then no error
+messages are left after errors.
 .AP Tk_Window tkwin in
-Token for window on the display in which font will be used.
+Token for window in which font will be used.
+.VS 8.1 br
+.AP Tcl_Obj *objPtr in/out
+Gives name or description of font.  See documentation
+for the \fBfont\fR command for details on acceptable formats.
+Internal rep will be modified to cache corresponding Tk_Font.
 .AP "const char" *string in
-Name or description of desired font.  See documentation for the \fBfont\fR 
-command for details on acceptable formats.
+Same as \fIobjPtr\fR except description of font is passed as a string and
+resulting Tk_Font isn't cached.
+.VE
 .AP Tk_Font tkfont in
 Opaque font token.
 .BE
 .SH DESCRIPTION
 .PP
-\fBTk_GetFont\fR finds the font indicated by \fIstring\fR and returns a
-token that represents the font.  The return value can be used in subsequent
-calls to procedures such as \fBTk_FontMetrics\fR, \fBTk_MeasureChars\fR, and
-\fBTk_FreeFont\fR.  The token returned by \fBTk_GetFont\fR will remain
-valid until \fBTk_FreeFont\fR is called to release it.  \fIString\fR can
-be either a symbolic name or a font description; see the documentation for
-the \fBfont\fR command for a description of the valid formats.  If
-\fBTk_GetFont\fR is unsuccessful (because, for example, \fIstring\fR was
-not a valid font specification) then it returns \fBNULL\fR and stores an
-error message in \fIinterp->result\fR.
+.VS 8.1
+\fBTk_AllocFontFromObj\fR finds the font indicated by \fIobjPtr\fR and
+returns a token that represents the font.  The return value can be used
+in subsequent calls to procedures such as \fBTk_FontMetrics\fR,
+\fBTk_MeasureChars\fR, and \fBTk_FreeFont\fR.  The Tk_Font token
+will remain valid until
+\fBTk_FreeFontFromObj\fR or \fBTk_FreeFont\fR is called to release it. 
+\fIObjPtr\fR can contain either a symbolic name or a font description; see
+the documentation for the \fBfont\fR command for a description of the
+valid formats.  If \fBTk_AllocFontFromObj\fR is unsuccessful (because,
+for example, \fIobjPtr\fR did not contain a valid font specification) then it
+returns \fBNULL\fR and leaves an error message in \fIinterp\fR's result
+if \fIinterp\fR isn't NULL.  \fBTk_AllocFontFromObj\fR caches
+information about the return
+value in \fIobjPtr\fR, which speeds up future calls to procedures
+such as \fBTk_AllocFontFromObj\fR and \fBTk_GetFontFromObj\fR.
+.PP
+\fBTk_GetFont\fR is identical to \fBTk_AllocFontFromObj\fR except
+that the description of the font is specified with a string instead
+of an object.  This prevents \fBTk_GetFont\fR from caching the
+matching Tk_Font, so \fBTk_GetFont\fR is less efficient than
+\fBTk_AllocFontFromObj\fR.
+.PP
+\fBTk_GetFontFromObj\fR returns the token for an existing font, given
+the window and description used to create the font.
+\fBTk_GetFontFromObj\fR doesn't actually create the font; the font
+must already have been created with a previous call to
+\fBTk_AllocFontFromObj\fR or \fBTk_GetFont\fR.  The return
+value is cached in \fIobjPtr\fR, which speeds up
+future calls to \fBTk_GetFontFromObj\fR with the same \fIobjPtr\fR
+and \fItkwin\fR.
+.VE
 .PP
-\fBTk_GetFont\fR maintains a database of all fonts it has allocated.  If
-the same \fIstring\fR is requested multiple times (e.g. by different
-windows or for different purposes), then additional calls for the same
-\fIstring\fR will be handled without involving the platform-specific
-graphics server.
+\fBTk_AllocFontFromObj\fR and \fBTk_GetFont\fR maintain
+a database of all fonts they have allocated.  If
+the same font is requested multiple times (e.g. by different
+windows or for different purposes), then a single Tk_Font will be
+shared for all uses.  The underlying resources will be freed automatically
+when no-one is using the font anymore.
 .PP
 The procedure \fBTk_NameOfFont\fR is roughly the inverse of
 \fBTk_GetFont\fR.  Given a \fItkfont\fR that was created by
-\fBTk_GetFont\fR, the return value is the \fIstring\fR argument that was
+\fBTk_GetFont\fR (or \fBTk_AllocFontFromObj\fR), the return value is
+the \fIstring\fR argument that was
 passed to \fBTk_GetFont\fR to create the font.  The string returned by
 \fBTk_NameOfFont\fR is only guaranteed to persist until the \fItkfont\fR
 is deleted.  The caller must not modify this string.
 .PP
-When a font returned by \fBTk_GetFont\fR is no longer needed,
-\fBTk_FreeFont\fR should be called to release it.  There should be
-exactly one call to \fBTk_FreeFont\fR for each call to \fBTk_GetFont\fR.
-When a font is no longer in use anywhere (i.e. it has been freed as many
-times as it has been gotten) \fBTk_FreeFont\fR will release any
-platform-specific storage and delete it from the database.  
+.VS 8.1
+When a font is no longer needed,
+\fBTk_FreeFontFromObj\fR or \fBTk_FreeFont\fR should be called to
+release it.  For \fBTk_FreeFontFromObj\fR the font to release is specified
+with the same information used to create it; for
+\fBTk_FreeFont\fR the font to release is specified
+with its Tk_Font token.  There should be
+exactly one call to \fBTk_FreeFontFromObj\fR or \fBTk_FreeFont\fR
+for each call to \fBTk_AllocFontFromObj\fR or \fBTk_GetFont\fR.
+.VE
 
 .SH KEYWORDS
 font