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 is not 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  is  not  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 does not 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