1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
|
# 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.
#
#
=head1 NAME
Tk_GetFont, Tk_NameOfFont, Tk_FreeFont - maintain database of fonts
=for category C Programming
=head1 SYNOPSIS
B<#include E<lt>tk.hE<gt>>
Tk_Font
B<Tk_GetFont(>I<interp, tkwin, string>B<)>
char *
B<Tk_NameOfFont(>I<tkfont>B<)>
void
B<Tk_FreeFont(>I<tkfont>B<)>
=head1 ARGUMENTS
=over 4
=item "Tcl_Interp" *interp (in)
Interpreter to use for error reporting.
=item Tk_Window tkwin (in)
Token for window on the display in which font will be used.
=item "const char" *string (in)
Name or description of desired font. See documentation for the B<font>
command for details on acceptable formats.
=item Tk_Font tkfont (in)
Opaque font token.
=back
=head1 DESCRIPTION
B<Tk_GetFont> finds the font indicated by I<string> and returns a
token that represents the font. The return value can be used in subsequent
calls to procedures such as B<Tk_FontMetrics>, B<Tk_MeasureChars>, and
B<Tk_FreeFont>. The token returned by B<Tk_GetFont> will remain
valid until B<Tk_FreeFont> is called to release it. I<String> can
be either a symbolic name or a font description; see the documentation for
the B<font> command for a description of the valid formats. If
B<Tk_GetFont> is unsuccessful (because, for example, I<string> was
not a valid font specification) 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<string> is requested multiple times (e.g. by different
windows or for different purposes), then additional calls for the same
I<string> will be handled without involving the platform-specific
graphics server.
The procedure B<Tk_NameOfFont> is roughly the inverse of
B<Tk_GetFont>. Given a I<tkfont> that was created by
B<Tk_GetFont>, the return value is the I<string> argument that was
passed to B<Tk_GetFont> to create the font. The string returned by
B<Tk_NameOfFont> is only guaranteed to persist until the I<tkfont>
is deleted. The caller must not modify this string.
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 any
platform-specific storage and delete it from the database.
=head1 KEYWORDS
font
|
