Tk_AllocFontFromObj(3tk)

Tk_AllocFontFromObj(3)Tk Library ProceduresTk_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                      Last change: 8.1                        1

Tk_AllocFontFromObj(3)Tk Library ProceduresTk_AllocFontFromObj(3)

     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  subsequent  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 mes-
     sage   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

Tk                      Last change: 8.1                        2

Tk_AllocFontFromObj(3)Tk Library ProceduresTk_AllocFontFromObj(3)

     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                      Last change: 8.1                        3