#  Copyright (c) 1990-1992 The Regents of the University of California.
#  Copyright (c) 1994 Sun Microsystems, Inc.
#  See the file "license.terms" for information on usage and redistribution
#  of this file, and for a DISCLAIMER OF ALL WARRANTIES.
#
#  @(#) GetFontStr.3 1.8 95/05/06 15:29:34
#

=head1 NAME

Tk_GetFontStruct, Tk_NameOfFontStruct, Tk_FreeFontStruct - maintain database of fonts

=for category C Programming

=head1 SYNOPSIS

B<#include E<lt>tk.hE<gt>>

XFontStruct *
B<Tk_GetFontStruct(>I<interp, tkwin, nameId>B<)>

char *
B<Tk_NameOfFontStruct(>I<fontStructPtr>B<)>

B<Tk_FreeFontStruct(>I<fontStructPtr>B<)>

=head1 ARGUMENTS

=over 4

=item Tcl_Interp *interp (in)

Interpreter to use for error reporting.

=item Tk_Window tkwin (in)

Token for window in which font will be used.

=item Tk_Uid nameId (in)

Name of desired font.

=item XFontStruct *fontStructPtr (in)

Font structure to return name for or delete.

=back

=head1 DESCRIPTION

B<Tk_GetFont> loads the font indicated
by I<nameId> and returns a pointer to information about the
font.  The pointer returned by B<Tk_GetFont>
will remain valid until B<Tk_FreeFont>
is called to release it.
I<NameId> can be either a font name or pattern;  any
value that could be passed to B<XLoadQueryFont> may be
passed to B<Tk_GetFont>.  If B<Tk_GetFont> is unsuccessful
(because, for example, there is no font corresponding to
I<nameId>) then it returns B<NULL> and stores an error
message in I<interp-E<gt>result>.

B<Tk_GetFont> maintains a database of all fonts it has allocated.
If the same I<nameId> is requested multiple times (e.g. by
different windows or for different purposes), then additional
calls for the same I<nameId> will be handled very quickly, without
involving the X server.  For this reason, it is generally better
to use B<Tk_GetFont> in place of X library procedures like
B<XLoadQueryFont>.

The procedure B<Tk_NameOfFontStruct> is roughly the inverse of
B<Tk_GetFontStruct>.  If its I<fontStructPtr> argument was created
by B<Tk_GetFontStruct>, then the return value is the I<nameId>
argument that was passed to B<Tk_GetFontStruct> to create the
font.  If I<fontStructPtr> was not created by a call
to B<Tk_GetFontStruct>, then the return value is a hexadecimal string
giving the X identifier for the associated font.
Note:  the string returned by B<Tk_NameOfFontStruct> is
only guaranteed to persist until the next call to B<Tk_NameOfFontStruct>.

When a font returned by B<Tk_GetFont> is no longer
needed, B<Tk_FreeFont> should be called to release it.
There should be exactly one call to B<Tk_FreeFont> for
each call to B<Tk_GetFont>.  When a font is no longer in
use anywhere (i.e. it has been freed as many times as it has been gotten)
B<Tk_FreeFont> will release it to the X server and delete it from
the database.

=head1 KEYWORDS

font