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)

       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 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 for-
					mats.  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  sub-
       sequent	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  docu-
       mentation  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_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(3)

KEYWORDS

       font

Tk									8.1						    Tk_AllocFontFromObj(3)