Provided by: tk8.4-doc_8.4.19-4_all
Tk_AllocFontFromObj, Tk_GetFont, Tk_GetFontFromObj, Tk_NameOfFont, Tk_FreeFontFromObj, Tk_FreeFont - maintain database of fonts
#include <tk.h> Tk_Font │ Tk_AllocFontFromObj(interp, tkwin, objPtr) │ Tk_Font │ Tk_GetFont(interp, tkwin, string) │ Tk_Font │ Tk_GetFontFromObj(tkwin, objPtr) │ CONST char * Tk_NameOfFont(tkfont) Tk_Font │ Tk_FreeFontFromObj(tkwin, objPtr) │ void Tk_FreeFont(tkfont)
Tcl_Interp *interp (in) Interpreter to use for error reporting. If NULL, then no error messages are left after errors. Tk_Window tkwin (in) Token for window in which font will be used. Tcl_Obj *objPtr (in/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 (in) │ Same as objPtr except description of font is passed as a │ string and resulting Tk_Font isn't cached. Tk_Font tkfont (in) Opaque font token. _________________________________________________________________
Tk_AllocFontFromObj finds the font indicated by objPtr and returns a token that represents │ the font. The return value can be used in subsequent calls to procedures such as │ Tk_GetFontMetrics, Tk_MeasureChars, and Tk_FreeFont. The Tk_Font token will remain valid │ until Tk_FreeFontFromObj 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_AllocFontFromObj is unsuccessful (because, │ for example, objPtr did not contain a valid font specification) then it returns NULL and │ leaves an error message in interp's result if interp isn't NULL. Tk_AllocFontFromObj │ caches information about the return value in 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 description of the font is │ specified with a string instead of an object. This prevents Tk_GetFont from caching the │ matching Tk_Font, so Tk_GetFont is less 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 created with a previous call to Tk_AllocFontFromObj or Tk_GetFont. │ The return value is cached in 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 argument that was passed to Tk_GetFont to create the font. The string returned by Tk_NameOfFont is only guaranteed 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.