1Tk_AllocFontFromObj(3) Tk Library Procedures Tk_AllocFontFromObj(3)
2______________________________________________________________________________
6
8 Tk_AllocFontFromObj, Tk_GetFont, Tk_GetFontFromObj, Tk_NameOfFont,
9 Tk_FreeFontFromObj, Tk_FreeFont - maintain database of fonts
10
12 #include <tk.h>
13 Tk_Font
15 Tk_AllocFontFromObj(interp, tkwin, objPtr)
16 Tk_Font
18 Tk_GetFont(interp, tkwin, string)
19 Tk_Font
21 Tk_GetFontFromObj(tkwin, objPtr)
22 const char *
24 Tk_NameOfFont(tkfont)
25 Tk_Font
27 Tk_FreeFontFromObj(tkwin, objPtr)
28 void
30 Tk_FreeFont(tkfont)
31
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 Tk_Window tkwin (in) Token for window in which font will be
38 used.
39 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 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 Tk_Font tkfont (in) Opaque font token.
51______________________________________________________________________________
52
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 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 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 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 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 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
101 Tk_FontId(3)
102
104 font
105Tk 8.1 Tk_AllocFontFromObj(3)