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)                           |

       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 mes­
                                        sages  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  documenta­ |
                                        tion 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  isn't |


       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_FreeFontFro­ |
       mObj 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 unsuc­ |
       cessful (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 isn't  NULL. |
       Tk_AllocFontFromObj  caches  information  about the return |
       value in objPtr, which speeds up future  calls  to  proce­ |
       dures 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  effi­ |
       cient 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 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_Get­ |
       FontFromObj 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_Free­ |
       FontFromObj the font to release is specified with the same |

       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


Man(1) output converted with man2html