Provided by: tk8.4-doc_8.4.19-4_all bug

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)                                                          │

       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)      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.
_________________________________________________________________

DESCRIPTION

       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.

SEE ALSO

       Tk_FontId(3tk)

KEYWORDS

       font