Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
Tk_AllocFontFromObj(3)	      Tk Library Procedures	  Tk_AllocFontFromObj(3)

________________________________________________________________________________

NAME
     Tk_AllocFontFromObj, Tk_GetFont, Tk_GetFontFromObj, Tk_NameOfFont, Tk_Free-
     FontFromObj, 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 de-
				      tails on acceptable formats.  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 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 documentation for the font command for a descrip-
     tion  of  the  valid  formats.  If Tk_AllocFontFromObj is unsuccessful (be-
     cause, 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_AllocFontFro-
     mObj 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 effi-
     cient 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 actu-
     ally create the font; the font must already have been created with a previ-
     ous 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 dif-
     ferent  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  ex-
     actly one call to Tk_FreeFontFromObj or Tk_FreeFont for each call to Tk_Al-
     locFontFromObj or Tk_GetFont.

SEE ALSO
     Tk_FontId(3)

KEYWORDS
     font

Tk				       8.1		  Tk_AllocFontFromObj(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=Tk_FreeFont.tk86&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help