2
'\" Copyright (c) 1990-1992 The Regents of the University of California.
3
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
5
'\" See the file "license.terms" for information on usage and redistribution
6
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
8
'\" RCS: @(#) $Id: GetFont.3,v 1.2 1998/09/14 18:22:49 stanton Exp $
11
.TH Tk_GetFont 3 "" Tk "Tk Library Procedures"
14
Tk_GetFont, Tk_NameOfFont, Tk_FreeFont \- maintain database of fonts
20
\fBTk_GetFont(\fIinterp, tkwin, string\fB)\fR
23
\fBTk_NameOfFont(\fItkfont\fB)\fR
26
\fBTk_FreeFont(\fItkfont\fB)\fR
29
.AS "const char" *tkfont
30
.AP "Tcl_Interp" *interp in
31
Interpreter to use for error reporting.
32
.AP Tk_Window tkwin in
33
Token for window on the display in which font will be used.
34
.AP "const char" *string in
35
Name or description of desired font. See documentation for the \fBfont\fR
36
command for details on acceptable formats.
42
\fBTk_GetFont\fR finds the font indicated by \fIstring\fR and returns a
43
token that represents the font. The return value can be used in subsequent
44
calls to procedures such as \fBTk_FontMetrics\fR, \fBTk_MeasureChars\fR, and
45
\fBTk_FreeFont\fR. The token returned by \fBTk_GetFont\fR will remain
46
valid until \fBTk_FreeFont\fR is called to release it. \fIString\fR can
47
be either a symbolic name or a font description; see the documentation for
48
the \fBfont\fR command for a description of the valid formats. If
49
\fBTk_GetFont\fR is unsuccessful (because, for example, \fIstring\fR was
50
not a valid font specification) then it returns \fBNULL\fR and stores an
51
error message in \fIinterp->result\fR.
53
\fBTk_GetFont\fR maintains a database of all fonts it has allocated. If
54
the same \fIstring\fR is requested multiple times (e.g. by different
55
windows or for different purposes), then additional calls for the same
56
\fIstring\fR will be handled without involving the platform-specific
59
The procedure \fBTk_NameOfFont\fR is roughly the inverse of
60
\fBTk_GetFont\fR. Given a \fItkfont\fR that was created by
61
\fBTk_GetFont\fR, the return value is the \fIstring\fR argument that was
62
passed to \fBTk_GetFont\fR to create the font. The string returned by
63
\fBTk_NameOfFont\fR is only guaranteed to persist until the \fItkfont\fR
64
is deleted. The caller must not modify this string.
66
When a font returned by \fBTk_GetFont\fR is no longer needed,
67
\fBTk_FreeFont\fR should be called to release it. There should be
68
exactly one call to \fBTk_FreeFont\fR for each call to \fBTk_GetFont\fR.
69
When a font is no longer in use anywhere (i.e. it has been freed as many
70
times as it has been gotten) \fBTk_FreeFont\fR will release any
71
platform-specific storage and delete it from the database.
added
removed
doc/GetFont.3
