'\"
'\" Copyright (c) 1990-1992 The Regents of the University of California.
'\" Copyright (c) 1994-1996 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 $
'\" 
.so man.macros
.TH Tk_GetFont 3 "" Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_GetFont, Tk_NameOfFont, Tk_FreeFont \- maintain database of fonts
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
Tk_Font 
\fBTk_GetFont(\fIinterp, tkwin, string\fB)\fR
.sp
char *
\fBTk_NameOfFont(\fItkfont\fB)\fR
.sp
void
\fBTk_FreeFont(\fItkfont\fB)\fR

.SH ARGUMENTS
.AS "const char" *tkfont
.AP "Tcl_Interp" *interp in
Interpreter to use for error reporting.
.AP Tk_Window tkwin in
Token for window on the display in which font will be used.
.AP "const char" *string in
Name or description of desired font.  See documentation for the \fBfont\fR 
command for details on acceptable formats.
.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.
.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.
.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
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.  

.SH KEYWORDS
font