Tk_AllocFontFromObj(3) Tk Library Procedures Tk_AllocFontFromObj(3) ______________________________________________________________________________ NAME Tk_AllocFontFromObj, Tk_GetFont, Tk_GetFontFromObj, Tk_NameOfFont, Tk_FreeFontFromObj, Tk_FreeFont - maintain database of fonts SYNOPSIS #include <tk.h> Tk_Font | Tk_AllocFontFromObj(interp, tkwin, objPtr) | Tk_Font | Tk_GetFont(interp, tkwin, string(3,n)) | Tk_Font | Tk_GetFontFromObj(tkwin, objPtr) | CONST char * Tk_NameOfFont(tkfont) Tk_Font | Tk_FreeFontFromObj(tkwin, objPtr) | void Tk_FreeFont(tkfont) ARGUMENTS Tcl_Interp *interp (in(1,8)) Interpreter to use for error(8,n) report- ing. If NULL, then no error(8,n) messages are left after errors. Tk_Window tkwin (in(1,8)) Token for window in(1,8) which font will be used. Tcl_Obj *objPtr (in(1,8)/out) || Gives name or description of font. | See documentation for the font command | for details on acceptable formats. | Internal rep will be modified to cache | corresponding Tk_Font. | const | char *string(3,n) (in(1,8)) | | Same as objPtr except description of | font is passed as a string(3,n) and result- | ing Tk_Font isn't cached. Tk_Font tkfont (in(1,8)) Opaque font token. _________________________________________________________________ DESCRIPTION Tk_AllocFontFromObj finds the font indicated by objPtr and returns a | token that represents the font. The return value can be used in(1,8) subse- | quent calls to procedures such as Tk_GetFontMetrics, Tk_MeasureChars, | and Tk_FreeFont. The Tk_Font token will remain valid until Tk_Free- | FontFromObj or Tk_FreeFont is called to release it. ObjPtr can contain | either a symbolic name or a font description; see the documentation for | the font command for a description of the valid formats. If Tk_Alloc- | FontFromObj is unsuccessful (because, for example, objPtr did not con- | tain a valid font specification) then it returns NULL and leaves an | error(8,n) message in(1,8) interp's result if(3,n) interp isn't NULL. Tk_AllocFont- | FromObj caches information about the return value in(1,8) objPtr, which | speeds up future calls to procedures such as Tk_AllocFontFromObj and | Tk_GetFontFromObj. | Tk_GetFont is identical to Tk_AllocFontFromObj except that the descrip- | tion of the font is specified with a string(3,n) instead of an object. This | prevents Tk_GetFont from caching the matching Tk_Font, so Tk_GetFont is | less(1,3) efficient than Tk_AllocFontFromObj. | Tk_GetFontFromObj returns the token for an existing font, given the | window and description used to create the font. Tk_GetFontFromObj | doesn't actually create the font; the font must already have been cre- | ated with a previous call to Tk_AllocFontFromObj or Tk_GetFont. The | return value is cached in(1,8) objPtr, which speeds up future calls to | Tk_GetFontFromObj with the same objPtr and tkwin. Tk_AllocFontFromObj and Tk_GetFont maintain a database of all fonts they have allocated. If the same font is requested multiple times (e.g. by different windows or for different purposes), then a single Tk_Font will be shared for all uses. The underlying resources will be freed automatically when no-one is using the font anymore. The procedure Tk_NameOfFont is roughly the inverse of Tk_GetFont. Given a tkfont that was created by Tk_GetFont (or Tk_AllocFontFromObj), the return value is the string(3,n) argument that was passed to Tk_GetFont to create the font. The string(3,n) returned by Tk_NameOfFont is only guar- anteed to persist until the tkfont is deleted. The caller must not modify this string. When a font is no longer needed, Tk_FreeFontFromObj or Tk_FreeFont | should be called to release it. For Tk_FreeFontFromObj the font to | release is specified with the same information used to create it; for | Tk_FreeFont the font to release is specified with its Tk_Font token. | There should be exactly one call to Tk_FreeFontFromObj or Tk_FreeFont | for each call to Tk_AllocFontFromObj or Tk_GetFont. SEE ALSO Tk_FontId(3) KEYWORDS font Tk 8.1 Tk_AllocFontFromObj(3)