Tk_AllocFontFromObj

Tk_AllocFontFromObj(3)       Tk Library Procedures      Tk_AllocFontFromObj(3)



______________________________________________________________________________

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  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- |
       quent  calls  to procedures such as Tk_GetFontMetrics, Tk_MeasureChars, |
       and Tk_FreeFont.  The Tk_Font token will remain  valid  until  Tk_Free- |
       FontFromObj 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_Alloc- |
       FontFromObj is unsuccessful (because, for example, objPtr did not  con- |
       tain  a  valid  font  specification) then it returns NULL and leaves an |
       error message in interp's result if interp isn't  NULL.   Tk_AllocFont- |
       FromObj  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 descrip- |
       tion 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 |
       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)