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  report-
                                        ing.   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 result- |
                                        ing 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 subse- |
       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  cre- |
       ated  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 guar-
       anteed  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(3)

KEYWORDS

       font



Tk                                    8.1               Tk_AllocFontFromObj(3)