tk4.2 C API - GetFontStr
NAME
Tk_GetFontStruct, Tk_NameOfFontStruct, Tk_FreeFontStruct -
maintain database of fonts
SYNOPSIS
#include <tk.h>
XFontStruct *
Tk_GetFontStruct(interp, tkwin, nameId)
char *
Tk_NameOfFontStruct(fontStructPtr)
Tk_FreeFontStruct(fontStructPtr)
ARGUMENTS
Tcl_Interp *interp (in) Interpreter to use
for error report-
ing.
Tk_Window tkwin (in) Token for window in
which font will be
used.
Tk_Uid nameId (in) Name of desired
font.
XFontStruct *fontStructPtr (in) Font structure to
return name for or
delete.
DESCRIPTION
Tk_GetFont loads the font indicated by nameId and returns a
pointer to information about the font. The pointer returned
by Tk_GetFont will remain valid until Tk_FreeFont is called
to release it. NameId can be either a font name or pattern;
any value that could be passed to XLoadQueryFont may be
passed to Tk_GetFont. If Tk_GetFont is unsuccessful
(because, for example, there is no font corresponding to
nameId) then it returns NULL and stores an error message in
interp->result.
Tk_GetFont maintains a database of all fonts it has allo-
cated. If the same nameId is requested multiple times (e.g.
by different windows or for different purposes), then addi-
tional calls for the same nameId will be handled very
quickly, without involving the X server. For this reason,
it is generally better to use Tk_GetFont in place of X
library procedures like XLoadQueryFont.
The procedure Tk_NameOfFontStruct is roughly the inverse of
Tk_GetFontStruct. If its fontStructPtr argument was created
by Tk_GetFontStruct, then the return value is the nameId
argument that was passed to Tk_GetFontStruct to create the
font. If fontStructPtr was not created by a call to
Tk_GetFontStruct, then the return value is a hexadecimal
string giving the X identifier for the associated font.
Note: the string returned by Tk_NameOfFontStruct is only
guaranteed to persist until the next call to
Tk_NameOfFontStruct.
When a font returned by Tk_GetFont is no longer needed,
Tk_FreeFont should be called to release it. There should be
exactly one call to Tk_FreeFont for each call to 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) Tk_FreeFont will
release it to the X server and delete it from the database.
KEYWORDS
font