1Tk_AllocFontFromObj(3)       Tk Library Procedures      Tk_AllocFontFromObj(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tk_AllocFontFromObj,   Tk_GetFont,   Tk_GetFontFromObj,  Tk_NameOfFont,
9       Tk_FreeFontFromObj, Tk_FreeFont - maintain database of fonts
10

SYNOPSIS

12       #include <tk.h>
13
14       Tk_Font
15       Tk_AllocFontFromObj(interp, tkwin, objPtr)
16
17       Tk_Font
18       Tk_GetFont(interp, tkwin, string)
19
20       Tk_Font
21       Tk_GetFontFromObj(tkwin, objPtr)
22
23       const char *
24       Tk_NameOfFont(tkfont)
25
26       Tk_Font
27       Tk_FreeFontFromObj(tkwin, objPtr)
28
29       void
30       Tk_FreeFont(tkfont)
31

ARGUMENTS

33       Tcl_Interp *interp (in)          Interpreter to use for  error  report‐
34                                        ing.   If NULL, then no error messages
35                                        are left after errors.
36
37       Tk_Window tkwin (in)             Token for window in which font will be
38                                        used.
39
40       Tcl_Obj *objPtr (in/out)         Gives  name  or  description  of font.
41                                        See documentation for the font command
42                                        for  details  on  acceptable  formats.
43                                        Internal rep will be modified to cache
44                                        corresponding Tk_Font.
45
46       const char *string (in)          Same  as  objPtr except description of
47                                        font is passed as a string and result‐
48                                        ing Tk_Font is not cached.
49
50       Tk_Font tkfont (in)              Opaque font token.
51______________________________________________________________________________
52

DESCRIPTION

54       Tk_AllocFontFromObj  finds  the  font indicated by objPtr and returns a
55       token that represents the font.  The return value can be used in subse‐
56       quent  calls  to procedures such as Tk_GetFontMetrics, Tk_MeasureChars,
57       and Tk_FreeFont.  The Tk_Font token will remain  valid  until  Tk_Free‐
58       FontFromObj or Tk_FreeFont is called to release it.  ObjPtr can contain
59       either a symbolic name or a font description; see the documentation for
60       the  font command for a description of the valid formats.  If Tk_Alloc‐
61       FontFromObj is unsuccessful (because, for example, objPtr did not  con‐
62       tain  a  valid  font  specification) then it returns NULL and leaves an
63       error message in interp's result if interp is not NULL.   Tk_AllocFont‐
64       FromObj  caches  information  about  the  return value in objPtr, which
65       speeds up future calls to procedures such  as  Tk_AllocFontFromObj  and
66       Tk_GetFontFromObj.
67
68       Tk_GetFont is identical to Tk_AllocFontFromObj except that the descrip‐
69       tion of the font is specified with a string instead of an object.  This
70       prevents Tk_GetFont from caching the matching Tk_Font, so Tk_GetFont is
71       less efficient than Tk_AllocFontFromObj.
72
73       Tk_GetFontFromObj returns the token for an  existing  font,  given  the
74       window and description used to create the font.  Tk_GetFontFromObj does
75       not actually create the font; the font must already have  been  created
76       with  a previous call to Tk_AllocFontFromObj or Tk_GetFont.  The return
77       value is cached in objPtr, which speeds up future calls to  Tk_GetFont‐
78       FromObj with the same objPtr and tkwin.
79
80       Tk_AllocFontFromObj  and  Tk_GetFont  maintain  a database of all fonts
81       they have allocated.  If the same  font  is  requested  multiple  times
82       (e.g.  by  different  windows or for different purposes), then a single
83       Tk_Font will be shared for all uses.  The underlying resources will  be
84       freed automatically when no-one is using the font anymore.
85
86       The  procedure  Tk_NameOfFont  is  roughly  the  inverse of Tk_GetFont.
87       Given a tkfont that was created by Tk_GetFont (or Tk_AllocFontFromObj),
88       the  return  value is the string argument that was passed to Tk_GetFont
89       to create the font.  The string returned by Tk_NameOfFont is only guar‐
90       anteed  to  persist  until  the tkfont is deleted.  The caller must not
91       modify this string.
92
93       When a font is no  longer  needed,  Tk_FreeFontFromObj  or  Tk_FreeFont
94       should  be  called  to  release it.  For Tk_FreeFontFromObj the font to
95       release is specified with the same information used to create  it;  for
96       Tk_FreeFont  the  font  to release is specified with its Tk_Font token.
97       There should be exactly one call to Tk_FreeFontFromObj  or  Tk_FreeFont
98       for each call to Tk_AllocFontFromObj or Tk_GetFont.
99

SEE ALSO

101       Tk_FontId(3)
102

KEYWORDS

104       font
105
106
107
108Tk                                    8.1               Tk_AllocFontFromObj(3)
Impressum