NAME

       Tk_AllocFontFromObj,  Tk_GetFont,  Tk_GetFontFromObj,  Tk_NameOfFont,  Tk_FreeFontFromObj,  Tk_FreeFont -
       maintain database of fonts

SYNOPSIS

       #include <tk.h>

       Tk_Font                                                                                                   2
       Tk_AllocFontFromObj(interp, tkwin, objPtr)                                                                2

       Tk_Font                                                                                                   2
       Tk_GetFont(interp, tkwin, string)                                                                         2

       Tk_Font                                                                                                   2
       Tk_GetFontFromObj(tkwin, objPtr)                                                                          2

       CONST char *
       Tk_NameOfFont(tkfont)

       Tk_Font                                                                                                   2
       Tk_FreeFontFromObj(tkwin, objPtr)                                                                         2

       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)                                                                           2
                                        Gives name or description of  font.   See  documentation  for  the  font 2
                                        command  for  details  on  acceptable  formats.   Internal  rep  will be 2
                                        modified to cache corresponding Tk_Font.                                 2

       const char   *string   (in)                                                                               2
                                        Same as objPtr except description of font is  passed  as  a  string  and 2
                                        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 2
       return  value  can  be used in subsequent calls to procedures such as Tk_GetFontMetrics, Tk_MeasureChars, 2
       and Tk_FreeFont.  The Tk_Font token will remain valid until Tk_FreeFontFromObj or Tk_FreeFont  is  called 2
       to  release  it.   ObjPtr can contain either a symbolic name or a font description; see the documentation 2
       for the font command for a description of the valid  formats.   If  Tk_AllocFontFromObj  is  unsuccessful 2
       (because, for example, objPtr did not contain a valid font specification) then it returns NULL and leaves 2
       an  error  message in interp's result if interp isn't NULL.  Tk_AllocFontFromObj caches information about 2
       the return value in objPtr, which speeds up future calls to procedures such  as  Tk_AllocFontFromObj  and 2
       Tk_GetFontFromObj.                                                                                        2

       Tk_GetFont  is identical to Tk_AllocFontFromObj except that the description of the font is specified with 2
       a string instead of an object.  This prevents Tk_GetFont from caching the matching Tk_Font, so Tk_GetFont 2
       is less efficient than Tk_AllocFontFromObj.                                                               2

       Tk_GetFontFromObj returns the token for an existing font, given the window and description used to create 2
       the font.  Tk_GetFontFromObj doesn't actually create the font; the font must already  have  been  created 2
       with  a  previous call to Tk_AllocFontFromObj or Tk_GetFont.  The return value is cached in objPtr, which 2
       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 2
       Tk_FreeFontFromObj the font to release is specified with the same information  used  to  create  it;  for 2
       Tk_FreeFont the font to release is specified with its Tk_Font token.  There should be exactly one call to 2
       Tk_FreeFontFromObj or Tk_FreeFont for each call to Tk_AllocFontFromObj or Tk_GetFont.

SEE ALSO

       Tk_FontId(3tk)

KEYWORDS

       font

Tk                                                     8.1                              Tk_AllocFontFromObj(3tk)