tk4.2 C API - GetFontStr






NAME

     Tk_GetFontStruct, Tk_NameOfFontStruct,  Tk_FreeFontStruct  -
     maintain database of fonts


SYNOPSIS

     #include <tk.h>

     XFontStruct *
     Tk_GetFontStruct(interp, tkwin, nameId)

     char *
     Tk_NameOfFontStruct(fontStructPtr)

     Tk_FreeFontStruct(fontStructPtr)


ARGUMENTS

     Tcl_Interp    *interp          (in)      Interpreter to  use
                                              for  error  report-
                                              ing.

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

     Tk_Uid        nameId           (in)      Name   of   desired
                                              font.

     XFontStruct   *fontStructPtr   (in)      Font  structure  to
                                              return  name for or
                                              delete.





DESCRIPTION

     Tk_GetFont loads the font indicated by nameId and returns  a
     pointer to information about the font.  The pointer returned
     by Tk_GetFont will remain valid until Tk_FreeFont is  called
     to release it.  NameId can be either a font name or pattern;
     any value that could be  passed  to  XLoadQueryFont  may  be
     passed   to   Tk_GetFont.   If  Tk_GetFont  is  unsuccessful
     (because, for example, there is  no  font  corresponding  to
     nameId)  then it returns NULL and stores an error message in
     interp->result.

     Tk_GetFont maintains a database of all fonts  it  has  allo-
     cated.  If the same nameId is requested multiple times (e.g.
     by different windows or for different purposes), then  addi-
     tional  calls  for  the  same  nameId  will  be handled very
     quickly, without involving the X server.  For  this  reason,
     it  is  generally  better  to  use  Tk_GetFont in place of X
     library procedures like XLoadQueryFont.

     The procedure Tk_NameOfFontStruct is roughly the inverse  of
     Tk_GetFontStruct.  If its fontStructPtr argument was created
     by Tk_GetFontStruct, then the return  value  is  the  nameId
     argument  that  was passed to Tk_GetFontStruct to create the
     font.  If  fontStructPtr  was  not  created  by  a  call  to
     Tk_GetFontStruct,  then  the  return  value is a hexadecimal
     string giving the X  identifier  for  the  associated  font.
     Note:   the  string  returned by Tk_NameOfFontStruct is only
     guaranteed   to   persist   until   the   next    call    to
     Tk_NameOfFontStruct.

     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 gotten) Tk_FreeFont  will
     release it to the X server and delete it from the database.



KEYWORDS

     font