NAME

       Tk_AllocFontFromObj,     Tk_GetFont,     Tk_GetFontFromObj,     Tk_NameOfFont,     Tk_FontGetDescription,
       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)

       Tcl_Obj *
       Tk_FontGetDescription(tkfont)

       const char *
       Tk_NameOfFont(tkfont)

       Tk_Font
       Tk_FreeFontFromObj(tkwin, objPtr)

       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_FontGetDescription returns information about the font description as  a  Tcl  list.  One
       possible result is “{{DejaVu Sans} -16 bold underline}”.

       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

Tk                                                     8.1                              Tk_AllocFontFromObj(3tk)