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
86
87
88
89
90
91
|
# 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
|
