TkAllocFontFromObj(3) Tk Library Procedures TkAllocFontFromObj(3)

NAME
       TkAllocFontFromObj,   TkGetFont,   TkGetFontFromObj,  TkNameOfFont,
       TkFreeFontFromObj, TkFreeFont - maintain database of fonts

SYNOPSIS
       ##iinncclluuddee <>

       TkFont                                                                 |
       TTkkAAllllooccFFoonnttFFrroommOObbjj((interp, tkwin, objPtr))                              |

       TkFont                                                                 |
       TTkkGGeettFFoonntt((interp, tkwin, string))                                       |

       TkFont                                                                 |
       TTkkGGeettFFoonnttFFrroommOObbjj((tkwin, objPtr))                                        |

       CONST char *
       TTkkNNaammeeOOffFFoonntt((tkfont))

       TkFont                                                                 |
       TTkkFFrreeeeFFoonnttFFrroommOObbjj((tkwin, objPtr))                                       |

       void
       TTkkFFrreeeeFFoonntt((tkfont))


AARRGGUUMMEENNTTSS
       TclInterp   *interp   (in)      Interpreter to use for  error  report-
                                        ing.   If NULL, then no error messages
                                        are left after errors.

       TkWindow    tkwin     (in)      Token for window in which font will be
                                        used.

       TclObj      *objPtr   (in/out)                                         ||
                                        Gives name  or  description  of  font. |
                                        See documentation for the ffoonntt command |
                                        for  details  on  acceptable  formats. |
                                        Internal rep will be modified to cache |
                                        corresponding TkFont.                 |

       const                                                                   |
       char   *string   (in)                                             |     |
                                        Same  as  objPtr except description of |
                                        font is passed as a string and result- |
                                        ing TkFont isn't cached.

       TkFont      tkfont    (in)      Opaque font token.


DESCRIPTION
       TTkkAAllllooccFFoonnttFFrroommOObbjj  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 TTkkGGeettFFoonnttMMeettrriiccss, TTkkMMeeaassuurreeCChhaarrss, |
       and TTkkFFrreeeeFFoonntt.  The TkFont token will remain  valid  until  TTkkFFrreeee- |
       FFoonnttFFrroommOObbjj or TTkkFFrreeeeFFoonntt is called to release it.  ObjPtr can contain |
       either a symbolic name or a font description; see the documentation for |
       the  ffoonntt command for a description of the valid formats.  If TTkkAAlllloocc- |
       FFoonnttFFrroommOObbjj is unsuccessful (because, for example, objPtr did not  con- |
       tain  a  valid  font  specification) then it returns NNUULLLL and leaves an |
       error message in interp's result if interp isn't  NULL.   TTkkAAllllooccFFoonntt- |
       FFrroommOObbjj  caches  information  about  the  return value in objPtr, which |
       speeds up future calls to procedures such  as  TTkkAAllllooccFFoonnttFFrroommOObbjj  and |
       TTkkGGeettFFoonnttFFrroommOObbjj.                                                      |

       TTkkGGeettFFoonntt is identical to TTkkAAllllooccFFoonnttFFrroommOObbjj except that the descrip- |
       tion of the font is specified with a string instead of an object.  This |
       prevents TTkkGGeettFFoonntt from caching the matching TkFont, so TTkkGGeettFFoonntt is |
       less efficient than TTkkAAllllooccFFoonnttFFrroommOObbjj.                                |

       TTkkGGeettFFoonnttFFrroommOObbjj returns the token for an  existing  font,  given  the |
       window  and  description  used  to  create the font.  TTkkGGeettFFoonnttFFrroommOObbjj |
       doesn't actually create the font; the font must already have been  cre- |
       ated  with  a  previous call to TTkkAAllllooccFFoonnttFFrroommOObbjj or TTkkGGeettFFoonntt.  The |
       return value is cached in objPtr,  which  speeds  up  future  calls  to |
       TTkkGGeettFFoonnttFFrroommOObbjj with the same objPtr and tkwin.

       TTkkAAllllooccFFoonnttFFrroommOObbjj  and  TTkkGGeettFFoonntt  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
       TkFont will be shared for all uses.  The underlying resources will  be
       freed automatically when no-one is using the font anymore.

       The  procedure  TTkkNNaammeeOOffFFoonntt  is  roughly  the  inverse of TTkkGGeettFFoonntt.
       Given a tkfont that was created by TTkkGGeettFFoonntt (or TTkkAAllllooccFFoonnttFFrroommOObbjj),
       the  return  value is the string argument that was passed to TTkkGGeettFFoonntt
       to create the font.  The string returned by TTkkNNaammeeOOffFFoonntt 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,  TTkkFFrreeeeFFoonnttFFrroommOObbjj  or  TTkkFFrreeeeFFoonntt |
       should  be  called  to  release it.  For TTkkFFrreeeeFFoonnttFFrroommOObbjj the font to |
       release is specified with the same information used to create  it;  for |
       TTkkFFrreeeeFFoonntt  the  font  to release is specified with its TkFont token. |
       There should be exactly one call to TTkkFFrreeeeFFoonnttFFrroommOObbjj  or  TTkkFFrreeeeFFoonntt |
       for each call to TTkkAAllllooccFFoonnttFFrroommOObbjj or TTkkGGeettFFoonntt.


SEE ALSO
       TkFontId(3)


KKEEYYWWOORRDDSS
       font



Tk                                    8.1               TkAllocFontFromObj(3)