Tk_GetFont(3)

_________________________________________________________________

NAME
       Tk_GetFont, Tk_NameOfFont, Tk_FreeFont - maintain database
       of fonts

SYNOPSIS
       #include <<tk.h>>

       Tk_Font
       Tk_GetFont(interp, tkwin, string)

       char *
       Tk_NameOfFont(tkfont)

       void
       Tk_FreeFont(tkfont)

ARGUMENTS
       Tcl_Interp   *interp   (in)      Interpreter  to  use  for
                                        error reporting.

       Tk_Window    tkwin     (in)      Token  for  window on the
                                        display  in  which   font
                                        will be used.

       const char   *string   (in)      Name  or  description  of
                                        desired font.  See  docu-
                                        mentation  for  the  font
                                        command  for  details  on
                                        acceptable formats.

       Tk_Font      tkfont    (in)      Opaque font token.
_________________________________________________________________

DESCRIPTION
       Tk_GetFont  finds the font indicated by string and returns
       a token that represents the font.  The return value can be
       used in subsequent calls to procedures such as Tk_FontMet-
       rics,  Tk_MeasureChars,  and   Tk_FreeFont.    The   token
       returned by Tk_GetFont will remain valid until Tk_FreeFont
       is called to release it.  String can be either a  symbolic
       name  or a font description; see the documentation for the
       font command for a description of the valid  formats.   If
       Tk_GetFont  is  unsuccessful (because, for example, string
       was not a valid font specification) then it  returns  NULL
       and stores an error message in interp-&gt;result.

       Tk_GetFont  maintains a database of all fonts it has allo-
       cated.  If the same string  is  requested  multiple  times
       (e.g.  by  different  windows  or for different purposes),
       then additional calls for the same string will be  handled
       without involving the platform-specific graphics server.

       The  procedure  Tk_NameOfFont  is  roughly  the inverse of
       Tk_GetFont.  Given a tkfont that was  created  by  Tk_Get-
       Font,  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  returned by Tk_GetFont is no longer needed,
       Tk_FreeFont should be called to release it.  There  should
       be  exactly  one  call  to  Tk_FreeFont  for  each call to
       Tk_GetFont.  When a font is  no  longer  in  use  anywhere
       (i.e.  it has been freed as many times as it has been got-
       ten) Tk_FreeFont will release any platform-specific  stor-
       age and delete it from the database.

KEYWORDS
       font