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